Chapter 2. API Reference
Fig. 36: Retrieving/Returning items in No-Split and Allow-Split ring buffers
Referring to the diagram above, the 16, 20, and 8 byte items are retrieved in FIFO order. However, the items are
not returned in the order they were retrieved. First, the 20 byte item is returned followed by the 8 byte and the 16
byte items. The space is not freed until the first item, i.e., the 16 byte item is returned.
Fig. 37: Retrieving/Returning data in byte buffers
Byte buffers do not allow multiple retrievals before returning (every retrieval must be followed by a return
before another retrieval is permitted). When using xRingbufferReceive() or xRingbufferReceive-
FromISR(), all continuous stored data will be retrieved. xRingbufferReceiveUpTo() or xRingbuf-
ferReceiveUpToFromISR() can be used to restrict the maximum number of bytes retrieved. Since every
retrieval must be followed by a return, the space will be freed as soon as the data is returned.
Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved, returned,
and freed. The next call to xRingbufferReceive() or xRingbufferReceiveFromISR() then wraps
around and does the same to the 30 bytes of continuous stored data at the head of the buffer.
Ring Buffers with Queue Sets Ring buffers can be added to FreeRTOS queue sets using xRingbufferAd-
dToQueueSetRead() such that every time a ring buffer receives an item or data, the queue set is notified. Once
added to a queue set, every attempt to retrieve an item from a ring buffer should be preceded by a call to xQueue-
SelectFromSet(). To check whether the selected queue set member is the ring buffer, call xRingbuffer-
CanRead().
The following example demonstrates queue set usage with ring buffers.
#include "freertos/queue.h"
#include "freertos/ringbuf.h"
...
//Create ring buffer and queue set
RingbufHandle_t buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
(continues on next page)
Espressif Systems 961
Submit Document Feedback
Release v4.4
To Next Page
Loading...