Group SDS_Buffer

sds_buffer.h : SDS circular buffer handling for data streamsMore...

Modules

Type	Name
module	Event Codes SDS Buffer Event Codes.
module	Function Return Codes SDS Buffer Function Return Codes.

Public Types

Type	Name
typedef void(*	sdsBufferEvent_t Callback function for SDS circular buffer event handling.
typedef void *	sdsBufferId_t Handle to SDS circular buffer.

Public Functions

Type	Name
int32_t	sdsBufferClear (sdsBufferId_t id) Clear SDS buffer stream data.
int32_t	sdsBufferClose (sdsBufferId_t id) Close SDS buffer stream.
int32_t	sdsBufferGetCount (sdsBufferId_t id) Get data count in SDS buffer stream.
sdsBufferId_t	sdsBufferOpen (void * buf, uint32_t buf_size, uint32_t threshold_low, uint32_t threshold_high) Open SDS buffer stream.
int32_t	sdsBufferRead (sdsBufferId_t id, void * buf, uint32_t buf_size) Read data from SDS buffer stream.
int32_t	sdsBufferRegisterEvents (sdsBufferId_t id, sdsBufferEvent_t event_cb, uint32_t event_mask, void * event_arg) Register SDS buffer stream event callback function.
int32_t	sdsBufferWrite (sdsBufferId_t id, const void * buf, uint32_t buf_size) Write data to SDS buffer stream.

Detailed Description

The SDS circular Buffer provides an interface for managing circular buffer streams used for efficient data transfer between software components. It includes functions for opening, closing, reading, writing, clearing, and monitoring buffer states using event callbacks.

Each buffer stream is represented by an identifier of type sdsBufferId_t, which is obtained via sdsBufferOpen() and used in subsequent API calls to refer to the corresponding buffer instance.

The buffer operates as a circular FIFO (first-in, first-out) queue. Data written to the buffer via sdsBufferWrite() is stored until read by sdsBufferRead() or until the buffer is cleared or closed. The buffer supports thresholds (threshold_low and threshold_high) for monitoring usage levels and triggering user-defined events.

Thread Safety

The SDS Buffer API is partially thread-safe, with the following constraints:

Thread-safe operations:

These functions may be safely called concurrently, provided they operate on the same buffer instance (sdsBufferId_t). This allows safe producer-consumer models where one thread writes and another reads from the same buffer.

Non-thread-safe operations:

These functions must not be called concurrently with each other or with sdsBufferRead() or sdsBufferWrite() for the same buffer. Doing so can lead to undefined behavior or data corruption.

Public Types Documentation

typedef sdsBufferEvent_t

Callback function for SDS circular buffer event handling.

typedef void(* sdsBufferEvent_t) (sdsBufferId_t id, uint32_t event, void *arg);

This function is registered by passing a pointer to it as a parameter to the sdsBufferRegisterEvents function. It is invoked when the circular buffer either reaches or exceeds the high data threshold or falls to or below the low data threshold. The high and low data thresholds are configured using the sdsBufferOpen function.

Parameters:

id sdsBufferId_t handle to SDS buffer stream
event event code (see Event Codes)
arg pointer to argument registered with sdsBufferRegisterEvents

typedef sdsBufferId_t

Handle to SDS circular buffer.

typedef void* sdsBufferId_t;

This pointer defines the handle to SDS circular buffer. It is used to identify a circular buffer across the different functions.

Public Functions Documentation

function sdsBufferClear

Clear SDS buffer stream data.

int32_t sdsBufferClear (
    sdsBufferId_t id
)

Clears any data from the SDS circular buffer and resets the circular buffer to empty state.

Parameters:

id sdsBufferId_t handle to SDS buffer stream

Returns:

SDS_BUFFER_OK on success or a negative value on error (see Function Return Codes)

function sdsBufferClose

Close SDS buffer stream.

int32_t sdsBufferClose (
    sdsBufferId_t id
)

Closes the SDS circular buffer when read or write operations are no longer required.

Parameters:

id sdsBufferId_t handle to SDS buffer stream

Returns:

SDS_BUFFER_OK on success or a negative value on error (see Function Return Codes)

function sdsBufferGetCount

Get data count in SDS buffer stream.

int32_t sdsBufferGetCount (
    sdsBufferId_t id
)

Retrieves the number of data bytes currently available in the SDS circular buffer.

Parameters:

id sdsBufferId_t handle to SDS buffer stream

Returns:

number of data bytes available in buffer stream or a negative value on error (see Function Return Codes)

function sdsBufferOpen

Open SDS buffer stream.

sdsBufferId_t sdsBufferOpen (
    void * buf,
    uint32_t buf_size,
    uint32_t threshold_low,
    uint32_t threshold_high
)

Opens the SDS circular buffer for read or write operations. The function returns the handle to the SDS buffer stream; if the buffer could not be opened, it returns NULL.

Parameters:

buf pointer to buffer for stream
buf_size buffer size in bytes
threshold_low data low threshold in bytes
threshold_high data high threshold in bytes

Returns:

sdsBufferId_t Handle to SDS buffer stream, or NULL if operation failed

function sdsBufferRead

Read data from SDS buffer stream.

int32_t sdsBufferRead (
    sdsBufferId_t id,
    void * buf,
    uint32_t buf_size
)

Attempts to read up to buf_size bytes of data from the SDS circular buffer into a buf. If sufficient data is available, the requested number of bytes will be read. If only partial data is available, only the available bytes will be read. On success, the function returns the number of bytes actually read or 0 if SDS circular buffer is empty.

Parameters:

id sdsBufferId_t handle to SDS buffer stream
buf pointer to buffer for data to read
buf_size buffer size in bytes

Returns:

number of data bytes successfully read or a negative value on error (see Function Return Codes)

function sdsBufferRegisterEvents

Register SDS buffer stream event callback function.

int32_t sdsBufferRegisterEvents (
    sdsBufferId_t id,
    sdsBufferEvent_t event_cb,
    uint32_t event_mask,
    void * event_arg
)

Registers a sdsBufferEvent_t callback function to handle threshold events for the specified SDS buffer.

The event_mask parameter specifies which buffer events should trigger the callback. It is a bitmask composed of values from the Event Codes enumeration:

When an event matching the mask occurs, the registered event_cb function is invoked with event_arg as its context.

If event_cb is NULL, any previously registered callback for the specified buffer is unregistered.

Parameters:

id sdsBufferId_t handle to SDS buffer stream
event_cb pointer to sdsBufferEvent_t callback function, NULL to un-register
event_mask event mask
event_arg pointer to event argument

Returns:

SDS_BUFFER_OK on success or a negative value on error (see Function Return Codes)

function sdsBufferWrite

Write data to SDS buffer stream.

int32_t sdsBufferWrite (
    sdsBufferId_t id,
    const void * buf,
    uint32_t buf_size
)

Attempts to write up to buf_size bytes of data from buf to the SDS circular buffer. If sufficient space is available in the buffer, all data will be written. If only partial space is available, only the number of bytes that fit will be written. No data is overwritten. On success, the function returns the number of bytes actually written.

Parameters:

id sdsBufferId_t handle to SDS buffer stream
buf pointer to buffer with data to write
buf_size buffer size in bytes

Returns:

number of data bytes successfully written or a negative value on error (see Function Return Codes)