Ring Buffer

Ringbuffer is designed in addition to use as a data buffer, also used to connect Audio Elements. Each Element that requests data from the Ringbuffer will block the task until the data is available. Or block the task when writing data and the Buffer is full. Of course, we can stop this block at any time.

Ring Buffer used in Audio Pipeline

Application Example

In most of ESP-ADF examples connecting of Elements with Ringbuffers is done “behind the scenes” by a function audio_pipeline_link(). To see this operation exposed check player/pipeline_sdcard_mp3_control example.

API Reference

Header File

Functions

ringbuf_handle_t rb_create(int block_size, int n_blocks)

Create ringbuffer with total size = block_size * n_blocks.

Return

ringbuf_handle_t

Parameters

  • [in] block_size: Size of each block

  • [in] n_blocks: Number of blocks

esp_err_t rb_destroy(ringbuf_handle_t rb)

Cleanup and free all memory created by ringbuf_handle_t.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

esp_err_t rb_abort(ringbuf_handle_t rb)

Abort waiting until there is space for reading or writing of the ringbuffer.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

esp_err_t rb_reset(ringbuf_handle_t rb)

Reset ringbuffer, clear all values as initial state.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

esp_err_t rb_reset_is_done_write(ringbuf_handle_t rb)

Reset is_done_write flag.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

int rb_bytes_available(ringbuf_handle_t rb)

Get total bytes available of Ringbuffer.

Return

total bytes available

Parameters

  • [in] rb: The Ringbuffer handle

int rb_bytes_filled(ringbuf_handle_t rb)

Get the number of bytes that have filled the ringbuffer.

Return

The number of bytes that have filled the ringbuffer

Parameters

  • [in] rb: The Ringbuffer handle

int rb_get_size(ringbuf_handle_t rb)

Get total size of Ringbuffer (in bytes)

Return

total size of Ringbuffer

Parameters

  • [in] rb: The Ringbuffer handle

int rb_read(ringbuf_handle_t rb, char *buf, int len, TickType_t ticks_to_wait)

Read from Ringbuffer to buf with len and wait tick_to_wait ticks until enough bytes to read if the ringbuffer bytes available is less than len. If buf argument provided is NULL, then ringbuffer do pseudo reads by simply advancing pointers.

Return

Number of bytes read

Parameters

  • [in] rb: The Ringbuffer handle

  • buf: The buffer pointer to read out data

  • [in] len: The length request

  • [in] ticks_to_wait: The ticks to wait

int rb_write(ringbuf_handle_t rb, char *buf, int len, TickType_t ticks_to_wait)

Write to Ringbuffer from buf with len and wait tick_to_wait ticks until enough space to write if the ringbuffer space available is less than len

Return

Number of bytes written

Parameters

  • [in] rb: The Ringbuffer handle

  • buf: The buffer

  • [in] len: The length

  • [in] ticks_to_wait: The ticks to wait

esp_err_t rb_done_write(ringbuf_handle_t rb)

Set status of writing to ringbuffer is done.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

esp_err_t rb_unblock_reader(ringbuf_handle_t rb)

Unblock from rb_read.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

esp_err_t rb_set_reader_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_read’.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

  • [in] holder: The owner of the ‘rb_read’

esp_err_t rb_get_reader_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_read’.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

  • [out] holder: The owner of the ‘rb_read’

esp_err_t rb_set_writer_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_write’.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

  • [in] holder: The owner of the ‘rb_write’

esp_err_t rb_get_writer_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_write’.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] rb: The Ringbuffer handle

  • [out] holder: The owner of the ‘rb_write’

Macros

RB_OK
RB_FAIL
RB_DONE
RB_ABORT
RB_TIMEOUT

Type Definitions

typedef struct ringbuf *ringbuf_handle_t

Provide feedback about this document