Byte stream communication primitives. More...

Collaboration diagram for Stream:

Functions
int	ove_stream_init (ove_stream_t stream, ove_stream_storage_t storage, void *buffer, size_t size, size_t trigger)
	Initialise a stream using caller-provided static storage.

void	ove_stream_deinit (ove_stream_t stream)
	Deinitialise a statically-allocated stream.

int	ove_stream_create (ove_stream_t *stream, size_t size, size_t trigger)
	Allocate and initialise a heap-backed stream.

void	ove_stream_destroy (ove_stream_t stream)
	Destroy a heap-allocated stream.

int	ove_stream_send (ove_stream_t stream, const void data, size_t len, uint64_t timeout_ns, size_t bytes_sent)
	Send bytes into the stream from task context.

static int	ove_stream_send_until (ove_stream_t stream, const void data, size_t len, uint64_t deadline_ns, size_t bytes_sent)
	Deadline-based variant of ove_stream_send.

int	ove_stream_receive (ove_stream_t stream, void buf, size_t len, uint64_t timeout_ns, size_t bytes_received)
	Receive bytes from the stream in task context.

static int	ove_stream_receive_until (ove_stream_t stream, void buf, size_t len, uint64_t deadline_ns, size_t bytes_received)
	Deadline-based variant of ove_stream_receive.

int	ove_stream_send_from_isr (ove_stream_t stream, const void data, size_t len, size_t bytes_sent)
	Send bytes into the stream from an ISR.

int	ove_stream_receive_from_isr (ove_stream_t stream, void buf, size_t len, size_t bytes_received)
	Receive bytes from the stream from an ISR.

int	ove_stream_reset (ove_stream_t stream)
	Discard all bytes currently held in the stream.

size_t	ove_stream_bytes_available (ove_stream_t stream)
	Query the number of bytes currently available in the stream.

int	ove_stream_set_notify (ove_stream_t stream, ove_notify_cb cb, void *user_data)
	Register a notify callback fired after every successful send.

Detailed Description

Byte stream communication primitives.

Provides a FIFO byte-stream channel suitable for producer/consumer communication between tasks or between an ISR and a task. Streams are trigger-aware: a receive unblocks only when at least trigger bytes are available, enabling efficient framing without spin-waiting.

Two allocation strategies are supported:

_create() / _destroy() — heap-allocated. Available only when OVE_HEAP_STREAM is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
_init() / _deinit() — caller-supplied storage and buffer. Available in both modes. See OVE_STREAM_DEFINE_STATIC for a one-step static helper.

Note: Requires CONFIG_OVE_STREAM.

Function Documentation

◆ ove_stream_init()

int ove_stream_init	(	ove_stream_t *	stream,
		ove_stream_storage_t *	storage,
		void *	buffer,
		size_t	size,
		size_t	trigger
	)

Initialise a stream using caller-provided static storage.

Constructs a stream object in storage and associates the raw byte buffer buffer of size bytes with it. The stream will not unblock a waiting receiver until at least trigger bytes are present.

Parameters

[out]	stream	Receives the initialised stream handle.
[in]	storage	Pointer to statically-allocated stream storage.
[in]	buffer	Pointer to the backing byte buffer.
[in]	size	Size of `buffer` in bytes.
[in]	trigger	Minimum bytes available before a blocked receiver wakes. A value of 0 is treated as 1 by every backend.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_STREAM.

◆ ove_stream_deinit()

void ove_stream_deinit ( ove_stream_t stream )

Deinitialise a statically-allocated stream.

Releases all RTOS resources associated with stream. The caller is responsible for freeing any backing buffer that was passed to ove_stream_init.

Parameters

[in] stream Stream handle returned by ove_stream_init.

Note: Requires CONFIG_OVE_STREAM.

◆ ove_stream_create()

int ove_stream_create	(	ove_stream_t *	stream,
		size_t	size,
		size_t	trigger
	)

Allocate and initialise a heap-backed stream.

Allocates both the stream control structure and the internal byte buffer from the heap. The stream will not wake a blocked receiver until at least trigger bytes are available.

Parameters

[out]	stream	Receives the created stream handle.
[in]	size	Capacity of the stream buffer in bytes.
[in]	trigger	Minimum bytes available before a blocked receiver wakes. A value of 0 is treated as 1 by every backend.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_STREAM and OVE_HEAP_STREAM.

◆ ove_stream_destroy()

void ove_stream_destroy ( ove_stream_t stream )

Destroy a heap-allocated stream.

Frees the stream control structure and its internal buffer. Must only be called on handles obtained from ove_stream_create.

Parameters

[in] stream Stream handle returned by ove_stream_create.

Note: Requires CONFIG_OVE_STREAM and OVE_HEAP_STREAM.

◆ ove_stream_send()

int ove_stream_send	(	ove_stream_t	stream,
		const void *	data,
		size_t	len,
		uint64_t	timeout_ns,
		size_t *	bytes_sent
	)

Send bytes into the stream from task context.

Copies up to len bytes from data into the stream. Blocks for at most timeout_ns nanoseconds if the stream has insufficient space. The actual number of bytes accepted is written to bytes_sent when not NULL.

Parameters

[in]	stream	Stream handle.
[in]	data	Pointer to the data to send.
[in]	len	Number of bytes to send.
[in]	timeout_ns	Maximum wait time in nanoseconds; 0 for non-blocking.
[out]	bytes_sent	Receives the number of bytes actually written, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure or timeout.

Note: Must not be called from an ISR; use ove_stream_send_from_isr instead.

◆ ove_stream_send_until()

static int ove_stream_send_until	(	ove_stream_t	stream,
		const void *	data,
		size_t	len,
		uint64_t	deadline_ns,
		size_t *	bytes_sent
	)

inlinestatic

Deadline-based variant of ove_stream_send.

Equivalent to calling ove_stream_send with the time remaining until deadline_ns (a steady-clock value from ove_time_now_steady_ns). Pass OVE_WAIT_FOREVER for an indefinite block.

Parameters

[in]	stream	Stream handle.
[in]	data	Pointer to the data to send.
[in]	len	Number of bytes to send.
[in]	deadline_ns	Absolute deadline against ove_time_now_steady_ns, or `OVE_WAIT_FOREVER`.
[out]	bytes_sent	Receives the number of bytes actually written, or `NULL`.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_receive()

int ove_stream_receive	(	ove_stream_t	stream,
		void *	buf,
		size_t	len,
		uint64_t	timeout_ns,
		size_t *	bytes_received
	)

Receive bytes from the stream in task context.

Copies up to len bytes from the stream into buf. Blocks for at most timeout_ns nanoseconds until the stream's trigger threshold is satisfied. The actual number of bytes read is written to bytes_received when not NULL.

Parameters

[in]	stream	Stream handle.
[out]	buf	Buffer to receive data.
[in]	len	Maximum number of bytes to read.
[in]	timeout_ns	Maximum wait time in nanoseconds; 0 for non-blocking.
[out]	bytes_received	Receives the number of bytes actually read, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure or timeout.

Note: Must not be called from an ISR; use ove_stream_receive_from_isr instead.

◆ ove_stream_receive_until()

static int ove_stream_receive_until	(	ove_stream_t	stream,
		void *	buf,
		size_t	len,
		uint64_t	deadline_ns,
		size_t *	bytes_received
	)

inlinestatic

Deadline-based variant of ove_stream_receive.

Equivalent to calling ove_stream_receive with the time remaining until deadline_ns (a steady-clock value from ove_time_now_steady_ns). Pass OVE_WAIT_FOREVER for an indefinite block.

Parameters

[in]	stream	Stream handle.
[out]	buf	Buffer to receive data.
[in]	len	Maximum number of bytes to read.
[in]	deadline_ns	Absolute deadline against ove_time_now_steady_ns, or `OVE_WAIT_FOREVER`.
[out]	bytes_received	Receives the number of bytes actually read, or `NULL`.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_send_from_isr()

int ove_stream_send_from_isr	(	ove_stream_t	stream,
		const void *	data,
		size_t	len,
		size_t *	bytes_sent
	)

Send bytes into the stream from an ISR.

ISR-safe variant of ove_stream_send. Never blocks; if the stream has insufficient space the call returns immediately with a partial or zero count.

Parameters

[in]	stream	Stream handle.
[in]	data	Pointer to the data to send.
[in]	len	Number of bytes to send.
[out]	bytes_sent	Receives the number of bytes actually written, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_receive_from_isr()

int ove_stream_receive_from_isr	(	ove_stream_t	stream,
		void *	buf,
		size_t	len,
		size_t *	bytes_received
	)

Receive bytes from the stream from an ISR.

ISR-safe variant of ove_stream_receive. Never blocks; returns only the bytes that are immediately available.

Parameters

[in]	stream	Stream handle.
[out]	buf	Buffer to receive data.
[in]	len	Maximum number of bytes to read.
[out]	bytes_received	Receives the number of bytes actually read, or `NULL` if the caller does not need this value.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_reset()

int ove_stream_reset ( ove_stream_t stream )

Discard all bytes currently held in the stream.

Resets the stream to the empty state without deallocating resources. Any task blocked in ove_stream_receive may remain blocked after this call until new data is written.

Parameters

[in] stream Stream handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_stream_bytes_available()

size_t ove_stream_bytes_available ( ove_stream_t stream )

Query the number of bytes currently available in the stream.

Returns the count of bytes that can be read without blocking.

Parameters

[in] stream Stream handle.

Returns: Number of bytes available; 0 if the stream is empty or invalid.

◆ ove_stream_set_notify()

int ove_stream_set_notify	(	ove_stream_t	stream,
		ove_notify_cb	cb,
		void *	user_data
	)

Register a notify callback fired after every successful send.

The callback is invoked at the tail of ove_stream_send and ove_stream_send_from_isr — once data has actually been deposited. Only one callback slot per stream; a later call replaces an earlier registration. Pass cb=NULL to clear.

Designed for higher-level async runtimes that need a wake hook: the Rust binding registers a callback that calls AtomicWaker::wake on a task suspended on Stream::recv_async.

The callback runs in whatever context the originating send used (thread or ISR). Implementations must therefore be ISR-safe and non-blocking — typically a single store + waker poke.

Parameters

[in]	stream	Stream handle.
[in]	cb	Callback to invoke after successful sends, or `NULL` to clear.
[in]	user_data	Opaque pointer forwarded to `cb`.

Returns: OVE_OK on success, negative error code on failure.

Functions

Detailed Description

Function Documentation

◆ ove_stream_init()

◆ ove_stream_deinit()

◆ ove_stream_create()

◆ ove_stream_destroy()

◆ ove_stream_send()

◆ ove_stream_send_until()

◆ ove_stream_receive()

◆ ove_stream_receive_until()

◆ ove_stream_send_from_isr()

◆ ove_stream_receive_from_isr()

◆ ove_stream_reset()

◆ ove_stream_bytes_available()

◆ ove_stream_set_notify()