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.

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

components/audio_pipeline/include/ringbuf.h

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

提供有关此文档的反馈