stream_buffer.h File Reference

Furi stream buffer primitive. More...

#include "base.h"

Go to the source code of this file.

Functions
FuriStreamBuffer *	furi_stream_buffer_alloc (size_t size, size_t trigger_level)
	Allocate stream buffer instance.
void	furi_stream_buffer_free (FuriStreamBuffer *stream_buffer)
	Free stream buffer instance.
bool	furi_stream_set_trigger_level (FuriStreamBuffer *stream_buffer, size_t trigger_level)
	Set trigger level for stream buffer.
size_t	furi_stream_buffer_send (FuriStreamBuffer *stream_buffer, const void *data, size_t length, uint32_t timeout)
	Sends bytes to a stream buffer.
size_t	furi_stream_buffer_receive (FuriStreamBuffer *stream_buffer, void *data, size_t length, uint32_t timeout)
	Receives bytes from a stream buffer.
size_t	furi_stream_buffer_bytes_available (FuriStreamBuffer *stream_buffer)
	Queries a stream buffer to see how much data it contains, which is equal to the number of bytes that can be read from the stream buffer before the stream buffer would be empty.
size_t	furi_stream_buffer_spaces_available (FuriStreamBuffer *stream_buffer)
	Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the stream buffer before it is full.
bool	furi_stream_buffer_is_full (FuriStreamBuffer *stream_buffer)
	Queries a stream buffer to see if it is full.
bool	furi_stream_buffer_is_empty (FuriStreamBuffer *stream_buffer)
	Queries a stream buffer to see if it is empty.
FuriStatus	furi_stream_buffer_reset (FuriStreamBuffer *stream_buffer)
	Resets a stream buffer to its initial, empty, state.

Detailed Description

Furi stream buffer primitive.

Stream buffers are used to send a continuous stream of data from one task or interrupt to another. Their implementation is light weight, making them particularly suited for interrupt to task and core to core communication scenarios.

NOTE: Stream buffer implementation assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader).

Function Documentation

furi_stream_buffer_alloc()

FuriStreamBuffer * furi_stream_buffer_alloc	(	size_t	size,
		size_t	trigger_level )

Allocate stream buffer instance.

Stream buffer implementation assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader).

Parameters

size	The total number of bytes the stream buffer will be able to hold at any one time.
trigger_level	The number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state.

Returns

The stream buffer instance.

furi_stream_buffer_bytes_available()

size_t furi_stream_buffer_bytes_available

(

FuriStreamBuffer *

stream_buffer

)

Queries a stream buffer to see how much data it contains, which is equal to the number of bytes that can be read from the stream buffer before the stream buffer would be empty.

Parameters

stream_buffer

The stream buffer instance.

Returns

The number of bytes that can be read from the stream buffer before the stream buffer would be empty.

furi_stream_buffer_free()

void furi_stream_buffer_free

(

FuriStreamBuffer *

stream_buffer

)

Free stream buffer instance.

Parameters

stream_buffer

The stream buffer instance.

furi_stream_buffer_is_empty()

bool furi_stream_buffer_is_empty

(

FuriStreamBuffer *

stream_buffer

)

Queries a stream buffer to see if it is empty.

Parameters

stream_buffer

The stream buffer instance.

Returns

true if the stream buffer is empty.

false if the stream buffer is not empty.

furi_stream_buffer_is_full()

bool furi_stream_buffer_is_full

(

FuriStreamBuffer *

stream_buffer

)

Queries a stream buffer to see if it is full.

Parameters

stream_buffer

stream buffer instance.

Returns

true if the stream buffer is full.

false if the stream buffer is not full.

furi_stream_buffer_receive()

size_t furi_stream_buffer_receive	(	FuriStreamBuffer *	stream_buffer,
		void *	data,
		size_t	length,
		uint32_t	timeout )

Receives bytes from a stream buffer.

Wakes up task waiting for space to become available if called from ISR.

Parameters

stream_buffer	The stream buffer instance.
data	A pointer to the buffer into which the received bytes will be copied.
length	The length of the buffer pointed to by the data parameter.
timeout	The maximum amount of time the task should remain in the Blocked state to wait for data to become available if the stream buffer is empty. Will return immediately if timeout is zero. Setting timeout to FuriWaitForever will cause the task to wait indefinitely. Ignored if called from ISR.

Returns

The number of bytes read from the stream buffer, if any.

furi_stream_buffer_reset()

FuriStatus furi_stream_buffer_reset

(

FuriStreamBuffer *

stream_buffer

)

Resets a stream buffer to its initial, empty, state.

Any data that was in the stream buffer is discarded. A stream buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer.

Parameters

stream_buffer

The stream buffer instance.

Returns

FuriStatusOk if the stream buffer is reset.

FuriStatusError if there was a task blocked waiting to send to or read from the stream buffer then the stream buffer is not reset.

furi_stream_buffer_send()

size_t furi_stream_buffer_send	(	FuriStreamBuffer *	stream_buffer,
		const void *	data,
		size_t	length,
		uint32_t	timeout )

Sends bytes to a stream buffer.

The bytes are copied into the stream buffer. Wakes up task waiting for data to become available if called from ISR.

Parameters

stream_buffer	The stream buffer instance.
data	A pointer to the data that is to be copied into the stream buffer.
length	The maximum number of bytes to copy from data into the stream buffer.
timeout	The maximum amount of time the task should remain in the Blocked state to wait for space to become available if the stream buffer is full. Will return immediately if timeout is zero. Setting timeout to FuriWaitForever will cause the task to wait indefinitely. Ignored if called from ISR.

Returns

The number of bytes actually written to the stream buffer.

furi_stream_buffer_spaces_available()

size_t furi_stream_buffer_spaces_available

(

FuriStreamBuffer *

stream_buffer

)

Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the stream buffer before it is full.

Parameters

stream_buffer

The stream buffer instance.

Returns

The number of bytes that can be written to the stream buffer before the stream buffer would be full.

furi_stream_set_trigger_level()

bool furi_stream_set_trigger_level	(	FuriStreamBuffer *	stream_buffer,
		size_t	trigger_level )

Set trigger level for stream buffer.

A stream buffer's trigger level is the number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state.

Parameters

stream_buffer	The stream buffer instance
trigger_level	The new trigger level for the stream buffer.

Returns

true if trigger level can be be updated (new trigger level was less than or equal to the stream buffer's length).

false if trigger level can't be be updated (new trigger level was greater than the stream buffer's length).