Espressif ESP32-S2 Programming Manual page 977

Chapter 2. API Reference
BaseType_t xRingbufferSendAcquire(RingbufHandle_t
Acquire memory from the ring buffer to be written to by an external source and to be sent later.
Attempt to allocate buffer for an item to be sent into the ring buffer. This function will block until enough free
space is available or until it timesout.
The item, as well as the following items SendAcquire or Send after it, will not be able to be read from the
ring buffer until this item is actually sent into the ring buffer.
Note Only applicable for no-split ring buffers now, the actual size of memory that the item will occupy will be
rounded up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit
aligned fashion.
Return
• pdTRUE if succeeded
• pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
Parameters
• [in] xRingbuffer: Ring buffer to allocate the memory
• [out] ppvItem: Double pointer to memory acquired (set to NULL if no memory were retrieved)
• [in] xItemSize: Size of item to acquire.
• [in] xTicksToWait: Ticks to wait for room in the ring buffer.
BaseType_t xRingbufferSendComplete(RingbufHandle_t
Actually send an item into the ring buffer allocated before by xRingbufferSendAcquire.
Note Only applicable for no-split ring buffers. Only call for items allocated by xRingbufferSendAc-
quire.
Return
• pdTRUE if succeeded
• pdFALSE if fail for some reason.
Parameters
• [in] xRingbuffer: Ring buffer to insert the item into
• [in] pvItem: Pointer to item in allocated memory to insert.
void *xRingbufferReceive(RingbufHandle_t
Retrieve an item from the ring buffer.
Attempt to retrieve an item from the ring buffer. This function will block until an item is available or until it
times out.
Note A call to vRingbufferReturnItem() is required after this to free the item retrieved.
Return
• Pointer to the retrieved item on success; *pxItemSize filled with the length of the item.
• NULL on timeout, *pxItemSize is untouched in that case.
Parameters
• [in] xRingbuffer: Ring buffer to retrieve the item from
• [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written.
• [in] xTicksToWait: Ticks to wait for items in the ring buffer.
void *xRingbufferReceiveFromISR(RingbufHandle_t
Retrieve an item from the ring buffer in an ISR.
Attempt to retrieve an item from the ring buffer. This function returns immediately if there are no items
available for retrieval
Note A call to vRingbufferReturnItemFromISR() is required after this to free the item retrieved.
Note Byte buffers do not allow multiple retrievals before returning an item
Note Two calls to RingbufferReceiveFromISR() are required if the bytes wrap around the end of the ring
buffer.
Return
• Pointer to the retrieved item on success; *pxItemSize filled with the length of the item.
• NULL when the ring buffer is empty, *pxItemSize is untouched in that case.
Parameters
Espressif Systems
Size, TickType_t xTicksToWait)
xRingbuffer, size_t *pxItemSize, TickType_t xTick-
sToWait)
966
Submit Document Feedback
xRingbuffer, void **ppvItem, size_t xItem-
xRingbuffer, void *pvItem)
xRingbuffer, size_t *pxItemSize)
Release v4.4