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.

Parameters

  • block_size – [in] Size of each block

  • n_blocks – [in] Number of blocks

Returns

ringbuf_handle_t

esp_err_t rb_destroy(ringbuf_handle_t rb)

Cleanup and free all memory created by ringbuf_handle_t.

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_abort(ringbuf_handle_t rb)

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

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_reset(ringbuf_handle_t rb)

Reset ringbuffer, clear all values as initial state.

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_reset_is_done_write(ringbuf_handle_t rb)

Reset is_done_write flag.

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

int rb_bytes_available(ringbuf_handle_t rb)

Get total bytes available of Ringbuffer.

Parameters

rb – [in] The Ringbuffer handle

Returns

total bytes available

int rb_bytes_filled(ringbuf_handle_t rb)

Get the number of bytes that have filled the ringbuffer.

Parameters

rb – [in] The Ringbuffer handle

Returns

The number of bytes that have filled the ringbuffer

int rb_get_size(ringbuf_handle_t rb)

Get total size of Ringbuffer (in bytes)

Parameters

rb – [in] The Ringbuffer handle

Returns

total size of Ringbuffer

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.

Parameters

  • rb – [in] The Ringbuffer handle

  • buf – The buffer pointer to read out data

  • len – [in] The length request

  • ticks_to_wait – [in] The ticks to wait

Returns

Number of bytes read

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

Parameters

  • rb – [in] The Ringbuffer handle

  • buf – The buffer

  • len – [in] The length

  • ticks_to_wait – [in] The ticks to wait

Returns

Number of bytes written

esp_err_t rb_done_write(ringbuf_handle_t rb)

Set status of writing to ringbuffer is done.

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_unblock_reader(ringbuf_handle_t rb)

Unblock from rb_read.

Parameters

rb – [in] The Ringbuffer handle

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_set_reader_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_read’.

Parameters

  • rb – [in] The Ringbuffer handle

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

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_get_reader_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_read’.

Parameters

  • rb – [in] The Ringbuffer handle

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

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_set_writer_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_write’.

Parameters

  • rb – [in] The Ringbuffer handle

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

Returns

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_get_writer_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_write’.

Parameters

  • rb – [in] The Ringbuffer handle

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

Returns

  • ESP_OK

  • ESP_FAIL

Macros

RB_OK
RB_FAIL
RB_DONE
RB_ABORT
RB_TIMEOUT

Type Definitions

typedef struct ringbuf *ringbuf_handle_t

Provide feedback about this document