MySensors/drivers/CircularBuffer/CircularBuffer.h

/*
  CircularBuffer - An Arduino circular buffering library for arbitrary types.

  Created by Ivo Pullens, Emmission, 2014-2016 -- www.emmission.nl

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

 /**
 * @file CircularBuffer.h
 *
 * Circular buffering for arbitrary types.
 */
 
#ifndef CircularBuffer_h
#define CircularBuffer_h

/**
 * The circular buffer class.
 * Pass the datatype to be stored in the buffer as template parameter.
 */
template <class T> class CircularBuffer
{
  public:
    /**
     * Constructor
     * @param buffer   Preallocated buffer of at least size records.
     * @param size     Number of records available in the buffer.
     */
    CircularBuffer(T* buffer, const uint8_t size )
      : m_size(size), m_buff(buffer)
    {
      clear();
    }

    /**
      * Clear all entries in the circular buffer.
      */
    void clear(void)
    {
      MY_CRITICAL_SECTION
      {
        m_front = 0;
        m_fill  = 0;
      }
    }

    /**
     * Test if the circular buffer is empty.
     * @return True, when empty.
     */
    inline bool empty(void) const
    {
      bool empty;
      MY_CRITICAL_SECTION
      {
        empty = !m_fill;
      }
      return empty;
    }

    /**
     * Test if the circular buffer is full.
     * @return True, when full.
     */
    inline bool full(void) const
    {
      bool full;
      MY_CRITICAL_SECTION
      {
        full = m_fill == m_size;
      }
      return full;
    }

    /**
     * Return the number of records stored in the buffer.
     * @return number of records.
     */
    inline uint8_t available(void) const
    {
      MY_CRITICAL_SECTION
      {
        return m_fill;
      }
    }
    
    /**
     * Aquire unused record on front of the buffer, for writing.
     * After filling the record, it has to be pushed to actually
     * add it to the buffer.
     * @return Pointer to record, or NULL when buffer is full.
     */
    T* getFront(void) const
    {
      MY_CRITICAL_SECTION
      {
          if (!full()) return get(m_front);
      }
      return static_cast<T*>(NULL);
    }
    
    /**
     * Push record to front of the buffer.
     * @param record   Record to push. If record was aquired previously (using getFront) its
     *                 data will not be copied as it is already present in the buffer.
     * @return True, when record was pushed successfully.
     */
    bool pushFront(T* record)
    {
      MY_CRITICAL_SECTION
      {
          if (!full())
          {
            T* f = get(m_front);
            if (f != record)
              *f = *record;
            m_front = (m_front+1) % m_size;
            m_fill++;
            return true;
          }
      }
      return false;
    }

    /**
     * Aquire record on back of the buffer, for reading.
     * After reading the record, it has to be pop'ed to actually
     * remove it from the buffer.
     * @return Pointer to record, or NULL when buffer is empty.
     */
    T* getBack(void) const
    {
      MY_CRITICAL_SECTION
      {
          if (!empty()) return get(back());
      }
      return static_cast<T*>(NULL);
    }

    /**
     * Remove record from back of the buffer.
     * @return True, when record was pop'ed successfully.
     */
    bool popBack(void)
    {
      MY_CRITICAL_SECTION
      {
          if (!empty())
          {
            m_fill--;
            return true;
          }
      }
      return false;
    }
    
  protected:
    /**
     * Internal getter for records.
     * @param idx   Record index in buffer.
     * @return Ptr to record.
     */
    inline T * get(const uint8_t idx) const
    {
      return &(m_buff[idx]);
    }

    /**
     * Internal getter for index of last used record in buffer.
     * @return Index of last record.
     */
    inline uint8_t back(void) const
    {
      return (m_front - m_fill + m_size) % m_size;
    }

    const uint8_t      m_size;     //!< Total number of records that can be stored in the buffer.
    T* const           m_buff;     //!< Ptr to buffer holding all records.
    volatile uint8_t   m_front;    //!< Index of front element (not pushed yet).
    volatile uint8_t   m_fill;     //!< Amount of records currently pushed.
};

#endif // CircularBuffer_h