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.

参数
  • block_size[in] Size of each block

  • n_blocks[in] Number of blocks

返回

ringbuf_handle_t

esp_err_t rb_destroy(ringbuf_handle_t rb)

Cleanup and free all memory created by ringbuf_handle_t.

参数

rb[in] The Ringbuffer handle

返回

  • 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.

参数

rb[in] The Ringbuffer handle

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_reset(ringbuf_handle_t rb)

Reset ringbuffer, clear all values as initial state.

参数

rb[in] The Ringbuffer handle

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_reset_is_done_write(ringbuf_handle_t rb)

Reset is_done_write flag.

参数

rb[in] The Ringbuffer handle

返回

  • ESP_OK

  • ESP_FAIL

int rb_bytes_available(ringbuf_handle_t rb)

Get total bytes available of Ringbuffer.

参数

rb[in] The Ringbuffer handle

返回

total bytes available

int rb_bytes_filled(ringbuf_handle_t rb)

Get the number of bytes that have filled the ringbuffer.

参数

rb[in] The Ringbuffer handle

返回

The number of bytes that have filled the ringbuffer

int rb_get_size(ringbuf_handle_t rb)

Get total size of Ringbuffer (in bytes)

参数

rb[in] The Ringbuffer handle

返回

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.

参数
  • 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

返回

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

参数
  • rb[in] The Ringbuffer handle

  • buf – The buffer

  • len[in] The length

  • ticks_to_wait[in] The ticks to wait

返回

Number of bytes written

esp_err_t rb_done_write(ringbuf_handle_t rb)

Set status of writing to ringbuffer is done.

参数

rb[in] The Ringbuffer handle

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_unblock_reader(ringbuf_handle_t rb)

Unblock from rb_read.

参数

rb[in] The Ringbuffer handle

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_set_reader_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_read’.

参数
  • rb[in] The Ringbuffer handle

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

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_get_reader_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_read’.

参数
  • rb[in] The Ringbuffer handle

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

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_set_writer_holder(ringbuf_handle_t rb, void *holder)

Set the owner of the ‘rb_write’.

参数
  • rb[in] The Ringbuffer handle

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

返回

  • ESP_OK

  • ESP_FAIL

esp_err_t rb_get_writer_holder(ringbuf_handle_t rb, void **holder)

Get the owner of the ‘rb_write’.

参数
  • rb[in] The Ringbuffer handle

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

返回

  • ESP_OK

  • ESP_FAIL

Macros

RB_OK
RB_FAIL
RB_DONE
RB_ABORT
RB_TIMEOUT

Type Definitions

typedef struct ringbuf *ringbuf_handle_t