Ringbuffer - meaning of "retrieve" and "return"?

[Jeebus]

According to the documentation on ring buffers:

The ring buffer provides API to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, items are always retrieved from the ring buffer by reference. As a result, all retrieved items must also be returned to the ring buffer by using vRingbufferReturnItem() or vRingbufferReturnItemFromISR(), in order for them to be removed from the ring buffer completely.

"All retrieved items must also be returned to the ring buffer..."

What is the meaning of this? What is happening when we "retrieve" an item vs when we "return" it?

[ESP_Sprite]

The ringbuffer implementation tries to conserve memory as much as possible. Therefore if you 'retrieve' an item, you do not get a copy of the memory in the ringbuffer at the item (because a copy would require some memory to store the copy in). Instead, you get a pointer to the data that actually lives in the ringbuffer memory, so there's no need for copying or an extra buffer. The item gets marked as 'in use' when you do that, so newly added items to the ringbuffer won't overwrite the item while you're reading this. If you're done with the item, the 'in use' flag needs to be removed again, and that is what the 'return' operation does: you're telling the ringbuffer that you're done with the item and it can re-use it again.

[Jeebus]

Thanks for the speedy reply!

This concept is much clear to me now. One last thing though- when I return the item after I am done with it, does this tell the ring buffer to "clear" the data, or at least no longer regard it? I essentially want the data to be deleted after I'm done with it. Does returning it have the same effect?

[ESP_Sprite]

It doesn't clear the data bytes itself, it simply marks the region as free to use again in the metadata of the ringbuffer; when enough data is written to the ringbuffer for it to wrap around, the region will get overwritten with new data.