:orphan: .. index:: pair: group; Ring buffers. .. _doxid-group__te__tools__te__ring: Ring buffers. ============= .. toctree:: :hidden: struct_te_ring.rst Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`te_ring` :ref:`te_ring`; // structs struct :ref:`te_ring`; // global functions :ref:`te_errno` :ref:`te_ring_put`(:ref:`te_ring`* ring, const void* element); :ref:`te_errno` :ref:`te_ring_get`(:ref:`te_ring`* ring, void* element); const void* :ref:`te_ring_peek`(const :ref:`te_ring`* ring); size_t :ref:`te_ring_copy`(const :ref:`te_ring`* ring, size_t count, :ref:`te_vec`* dest); size_t :ref:`te_ring_put_many`(:ref:`te_ring`* ring, size_t count, const void* elements); size_t :ref:`te_ring_get_many`(:ref:`te_ring`* ring, size_t count, :ref:`te_vec`* dest); void :ref:`te_ring_resize`(:ref:`te_ring`* ring, size_t new_ring_size); void :ref:`te_ring_free`(:ref:`te_ring`* ring); // macros #define :ref:`TE_RING_INIT`(type_, destroy_, ring_size_) #define :target:`TE_RING_INIT_AUTOPTR`(type_, ring_size_) .. _details-group__te__tools__te__ring: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Typedefs -------- .. index:: pair: typedef; te_ring .. _doxid-group__te__tools__te__ring_1ga02521a7b329fe8d8ef03557454a3e6e0: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_ring` te_ring Ring buffer structure. All the fields may be inspected but must never be directly modified by the user. Global Functions ---------------- .. index:: pair: function; te_ring_put .. _doxid-group__te__tools__te__ring_1ga92b515faaa65e1f2f208552dcc167d5b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_ring_put(:ref:`te_ring`* ring, const void* element) Put the content of ``element`` into the ``ring``. If the ring is already full, the oldest element is discarded. If the ring has non-null destructor, it is called for the discarded element. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - element - new data * - TE_ENOBUFS - The ring buffer has overflowed. It is not an error, but the caller may take some appropriate action if needed. .. rubric:: Returns: status code .. index:: pair: function; te_ring_get .. _doxid-group__te__tools__te__ring_1ga5f6d3f8be26679389d744db4fca4aca3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_ring_get(:ref:`te_ring`* ring, void* element) Get the oldest element from the ``ring``. The element is removed from the ring and the read pointer is moved to the next element. The data are put into ``element`` if it is not ``NULL``; otherwise the data are discared (the element destructor is called if it's non-null). If there is no data in ``ring``, ``element`` is not changed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - element - destination buffer (may be ``NULL``) * - TE_ENODATA - The ring is empty. .. rubric:: Returns: status code .. index:: pair: function; te_ring_peek .. _doxid-group__te__tools__te__ring_1gad94f0f1f1f8c8d1386fdfb6097db7124: .. ref-code-block:: cpp :class: doxyrest-title-code-block const void* te_ring_peek(const :ref:`te_ring`* ring) Get the oldest element from the ring ``keeping`` it. The pointer inside the ring itself is returned, the caller must treat it as a pointer to local storage. The read pointer is not moved. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer .. rubric:: Returns: the pointer to the data or ``NULL`` if the ring is empty .. index:: pair: function; te_ring_copy .. _doxid-group__te__tools__te__ring_1ga780b2a368daf41eaf1c4f31e57eefe22: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_ring_copy(const :ref:`te_ring`* ring, size_t count, :ref:`te_vec`* dest) Copy at most ``count`` oldest elements from ``ring`` to ``dest``. The read pointer is not moved. The data are appended to ``dest``. ``dest`` must have a null destructor. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - count - maximum number of elements to copy * - dest - destination vector .. rubric:: Returns: the number of elements actually copied (may be 0) .. index:: pair: function; te_ring_put_many .. _doxid-group__te__tools__te__ring_1gae656456a36d2e34ba48493a636d63e84: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_ring_put_many(:ref:`te_ring`* ring, size_t count, const void* elements) Put ``count`` items from ``elements`` to ``ring``. The ring is never overran, if there is not enough space in ``ring``, fewer elements are put. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - count - maximum number of elements to put * - elements - new data .. rubric:: Returns: the number of elements actually put (may be 0) .. index:: pair: function; te_ring_get_many .. _doxid-group__te__tools__te__ring_1ga1b045243b45a8f5c0aa1a7df0a84057b: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_ring_get_many(:ref:`te_ring`* ring, size_t count, :ref:`te_vec`* dest) Get at most ``count`` oldest elements from ``ring`` and put them to ``dest``. The elements are removed from the ring and the read pointer is moved as needed. The data are appended to ``dest``, if ``dest`` is not ``NULL``, otherwise the data are discarded (the element destructor is called if it's not null). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - count - maximum number of elements to put * - dest - destination vector (may be ``NULL``) .. rubric:: Returns: the number of elements actually got. .. index:: pair: function; te_ring_resize .. _doxid-group__te__tools__te__ring_1ga903caf2d4b769c3e50713d67c039fa0a: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_ring_resize(:ref:`te_ring`* ring, size_t new_ring_size) Change the size of ``ring`` to ``new_ring_size``. If ``new_ring_size`` is less than the current fill of the ring, oldest redundant items are discarded. In all other cases all the data are preserved, but the layout may change. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer * - new_ring_size - new size of the ring .. index:: pair: function; te_ring_free .. _doxid-group__te__tools__te__ring_1ga87af4ad4d97ee76064d4e13f1ed5df01: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_ring_free(:ref:`te_ring`* ring) Free any resources associated with ``ring``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ring - ring buffer Macros ------ .. index:: pair: define; TE_RING_INIT .. _doxid-group__te__tools__te__ring_1ga137dd0a9b95c3243cf5bf8cb28901992: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_RING_INIT(type_, destroy_, ring_size_) Initialize a ring to store objects of a given ``type_``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - type\_ - type of elements * - destroy\_ - element destructor * - ring_size\_ - initial ring size