circular-buffer.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2015-2025 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
#ifndef CMSIS_PLUS_POSIX_DRIVER_CIRCULAR_BUFFER_H_
#define CMSIS_PLUS_POSIX_DRIVER_CIRCULAR_BUFFER_H_
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#include <cstdint>
#include <cstddef>
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace posix
  {
    // ------------------------------------------------------------------------
 
    template <typename T>
    class circular_buffer
    {
      // ----------------------------------------------------------------------
 
    public:
      using value_type = T;
 
    public:
      circular_buffer (const value_type* buf, std::size_t size,
                       std::size_t high_water_mark,
                       std::size_t low_water_mark = 0);
 
      circular_buffer (const value_type* buf, std::size_t size);
 
      // The rule of five.
      circular_buffer (const circular_buffer&) = delete;
      circular_buffer (circular_buffer&&) = delete;
      circular_buffer&
      operator= (const circular_buffer&)
          = delete;
      circular_buffer&
      operator= (circular_buffer&&)
          = delete;
 
      ~circular_buffer ();
 
      // ----------------------------------------------------------------------
    public:
      void
      clear (void);
 
      const value_type&
      operator[] (std::size_t idx) const;
 
      // Insert bytes to the back of the buffer.
      std::size_t
      push_back (value_type v);
 
      std::size_t
      push_back (const value_type* buf, std::size_t count);
 
      std::size_t
      advance_back (std::size_t count);
 
      void
      retreat_back (void);
 
      // Retrieve bytes from the front of the buffer.
      std::size_t
      pop_front (value_type* buf);
 
      std::size_t
      pop_front (value_type* buf, std::size_t size);
 
      std::size_t
      advance_front (std::size_t count);
 
      // Get the address of the largest contiguous buffer in the front, and
      // length; might be only partial, if buffer wraps.
      std::size_t
      front_contiguous_buffer (value_type** ppbuf);
 
      // Get the address of the largest contiguous buffer in the back, and
      // length; might be only partial, if buffer wraps.
      std::size_t
      back_contiguous_buffer (value_type** ppbuf);
 
      bool
      empty (void) const;
 
      bool
      full (void) const;
 
      bool
      above_high_water_mark (void) const;
 
      bool
      below_high_water_mark (void) const;
 
      bool
      above_low_water_mark (void) const;
 
      bool
      below_low_water_mark (void) const;
 
      std::size_t
      length (void) const;
 
      std::size_t
      size (void) const;
 
      void
      dump (void);
 
      // ----------------------------------------------------------------------
    private:
      const value_type* const buf_;
      std::size_t const size_;
      std::size_t const high_water_mark_;
      std::size_t const low_water_mark_;
 
      // The following are volatile because they can be updated on
      // different threads or even on interrupts.
 
      // Actual length: [0 - size].
      std::size_t volatile len_;
 
      // Next free position to push, at the back.
      value_type* volatile back_;
 
      // First used position to pop, at the front.
      value_type* volatile front_;
 
    };
    // ========================================================================
 
    using circular_buffer_bytes = circular_buffer<uint8_t>;
 
    // ========================================================================
  } /* namespace posix */
} /* namespace os */
 
// ===== Inline & template implementations ====================================
 
namespace os
{
  namespace posix
  {
 
    template <typename T>
    circular_buffer<T>::circular_buffer (const value_type* buf,
                                         std::size_t siz,
                                         std::size_t high_water_mark,
                                         std::size_t low_water_mark)
        : buf_ (buf), //
          size_ (siz), //
          high_water_mark_ (high_water_mark <= size_ ? high_water_mark
                                                     : siz), //
          low_water_mark_ (low_water_mark)
    {
      assert (low_water_mark_ <= high_water_mark_);
 
      clear ();
    }
 
    template <typename T>
    circular_buffer<T>::circular_buffer (const value_type* buf,
                                         std::size_t siz)
        : circular_buffer{ buf, siz, siz, 0 }
    {
      trace::printf ("%s(%p,%u) %p\n", __func__, buf, siz, this);
    }
 
    template <typename T>
    circular_buffer<T>::~circular_buffer ()
    {
      trace::printf ("%s() %p\n", __func__, this);
    }
 
    // ------------------------------------------------------------------------
 
    template <typename T>
    void
    circular_buffer<T>::clear (void)
    {
      back_ = front_ = const_cast<value_type* volatile> (buf_);
      len_ = 0;
#if defined(DEBUG)
      std::memset (static_cast<void*> (const_cast<value_type*> (buf_)), '?',
                   size_ * sizeof (value_type));
#endif
    }
 
    template <typename T>
    inline const typename circular_buffer<T>::value_type&
    circular_buffer<T>::operator[] (std::size_t idx) const
    {
      return buf_[idx];
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::empty (void) const
    {
      return (len_ == 0);
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::full (void) const
    {
      return (len_ >= size_);
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::above_high_water_mark (void) const
    {
      // Allow for water mark to be size.
      return (len_ >= high_water_mark_);
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::below_low_water_mark (void) const
    {
      // Allow for water mark to be 0.
      return (len_ <= low_water_mark_);
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::below_high_water_mark (void) const
    {
      return !above_high_water_mark ();
    }
 
    template <typename T>
    inline bool
    circular_buffer<T>::above_low_water_mark (void) const
    {
      return !below_low_water_mark ();
    }
 
    template <typename T>
    inline std::size_t
    circular_buffer<T>::length (void) const
    {
      return len_;
    }
 
    template <typename T>
    inline std::size_t
    circular_buffer<T>::size (void) const
    {
      return size_;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::push_back (value_type v)
    {
      if (full ())
        {
          return 0;
        }
 
      // Add to back.
      *back_++ = v;
      if (static_cast<std::size_t> (back_ - buf_) >= size_)
        {
          // Wrap.
          back_ = const_cast<value_type* volatile> (buf_);
        }
      len_++;
      return 1;
    }
 
    // Return the actual number of bytes, if not enough space for all.
    template <typename T>
    std::size_t
    circular_buffer<T>::push_back (const value_type* buf, std::size_t count)
    {
      assert (buf != nullptr);
 
      std::size_t len = count;
      if (count > (size_ - len_))
        {
          len = size_ - len_;
        }
 
      if (len == 0)
        {
          return 0;
        }
 
      std::size_t sizeToEnd = static_cast<std::size_t> (
          size_ - static_cast<std::size_t> (back_ - buf_));
      if (len <= sizeToEnd)
        {
          std::memcpy (back_, buf, len);
          back_ += len;
          if (static_cast<std::size_t> (back_ - buf_) >= size_)
            {
              // Wrap.
              back_ = const_cast<value_type* volatile> (buf_);
            }
          len_ += len;
        }
      else
        {
          std::memcpy (back_, buf, sizeToEnd);
          back_ = const_cast<value_type* volatile> (buf_);
          std::memcpy (back_, buf + sizeToEnd, len - sizeToEnd);
          back_ += (len - sizeToEnd);
          len_ += len;
        }
      return len;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::advance_back (std::size_t count)
    {
      std::size_t adjust = count;
      if (count > (size_ - len_))
        {
          adjust = size_ - len_;
        }
 
      if (adjust == 0)
        {
          return 0;
        }
 
      back_ += adjust;
      if (back_ >= (buf_ + size_))
        {
          // Wrap.
          back_ -= size_;
        }
      len_ += adjust;
 
      return adjust;
    }
 
    template <typename T>
    void
    circular_buffer<T>::retreat_back (void)
    {
      if (back_ == buf_)
        {
          back_ = static_cast<value_type*> (const_cast<value_type*> (buf_)
                                            + size_ - 1);
        }
      else
        {
          back_ -= 1;
        }
      len_--;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::pop_front (value_type* buf)
    {
      assert (buf != nullptr);
 
      value_type c;
      if (len_ == 0)
        {
          return 0;
        }
      else
        {
          c = *front_++;
          if (static_cast<std::size_t> (front_ - buf_) >= size_)
            {
              front_ = const_cast<value_type* volatile> (buf_);
            }
          len_--;
          *buf = c;
          return 1;
        }
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::pop_front (value_type* buf, std::size_t siz)
    {
      assert (buf != nullptr);
 
      std::size_t len = siz;
      if (len > len_)
        {
          len = len_;
        }
 
      std::size_t sizeToEnd = size_ - static_cast<std::size_t> (front_ - buf_);
      if (len <= sizeToEnd)
        {
          std::memcpy (buf, front_, len);
          front_ += len;
          if (static_cast<std::size_t> (front_ - buf_) >= size_)
            {
              front_ = const_cast<value_type* volatile> (buf_);
            }
          len_ -= len;
        }
      else
        {
          std::memcpy (buf, front_, sizeToEnd);
          front_ = const_cast<value_type* volatile> (buf_);
          std::memcpy (buf + sizeToEnd, front_, len - sizeToEnd);
          front_ += (len - sizeToEnd);
          len_ -= len;
        }
      return len;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::advance_front (std::size_t count)
    {
      if (count == 0)
        {
          return 0;
        }
 
      std::size_t adjust = count;
      if (adjust > len_)
        {
          adjust = len_;
        }
 
      front_ += adjust;
      if (front_ >= (buf_ + size_))
        {
          // Wrap.
          front_ -= size_;
        }
      len_ -= adjust;
 
      return adjust;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::front_contiguous_buffer (value_type** ppbuf)
    {
      assert (ppbuf != nullptr);
 
      *ppbuf = front_;
 
      std::size_t sizeToEnd = size_ - static_cast<std::size_t> (front_ - buf_);
      std::size_t len = sizeToEnd;
      if (len > len_)
        {
          len = len_;
        }
 
      return len;
    }
 
    template <typename T>
    std::size_t
    circular_buffer<T>::back_contiguous_buffer (value_type** ppbuf)
    {
      assert (ppbuf != nullptr);
 
      *ppbuf = back_;
 
      std::size_t sizeToEnd = size_ - static_cast<std::size_t> (back_ - buf_);
      std::size_t len = sizeToEnd;
      if (len > (size_ - len_))
        {
          len = size_ - len_;
        }
 
      return len;
    }
 
    template <typename T>
    void
    circular_buffer<T>::dump (void)
    {
      os::trace::printf ("%s @%p {buf=%p, size=%d, len=%d, hwm=%d, lwn=%d}\n",
                         __PRETTY_FUNCTION__, buf_, size_, len_,
                         high_water_mark_, low_water_mark_);
    }
 
    // ========================================================================
  } /* namespace posix */
} /* namespace os */
 
// ----------------------------------------------------------------------------
 
#endif /* __cplusplus */
 
// ----------------------------------------------------------------------------
 
#endif /* CMSIS_PLUS_POSIX_DRIVER_CIRCULAR_BUFFER_H_ */