stream.h File Reference

Bounded caller-owned blocks with explicit producer/consumer loans. More...

#include "nexus/core/status.h"

Go to the source code of this file.

Data Structures
struct	nx_stream_slot_t
	Caller-owned block metadata; initialize data and capacity only. More...
struct	nx_stream_t
	Caller-owned stream control, initialized before publication. More...
struct	nx_stream_fill_t
	Mutable producer loan; hardware must stop before abort or publish. More...
struct	nx_stream_producer_t
	Optional caller-owned preposted producer; no default cost. More...
struct	nx_stream_block_t
	Immutable consumer loan, valid until matching release succeeds. More...

Macros
#define	NX_STREAM_BOUNDARY_IDLE   1U
#define	NX_STREAM_BOUNDARY_TRIGGER   2U
#define	NX_STREAM_BOUNDARY_LOSS   4U
#define	NX_STREAM_BOUNDARY_ERROR   8U

Enumerations
enum	nx_stream_slot_state_t { NX_STREAM_SLOT_FREE , NX_STREAM_SLOT_FILLING , NX_STREAM_SLOT_READY , NX_STREAM_SLOT_BORROWED }

Functions
nx_result_t	nx_stream_initialize (nx_stream_t *stream, nx_stream_slot_t *slots, size_t count)
	Initialize an unborrowed stream and exact supplied block array.
nx_result_t	nx_stream_reserve (nx_stream_t *stream, nx_stream_fill_t *fill)
	Reserve the next free block for one serialized producer.
bool	nx_stream_can_reserve (const nx_stream_t *stream)
	Query the next physical slot without creating a loan or loss.
void	nx_stream_note_loss (nx_stream_t *stream, uint32_t count)
	Latch explicitly observed dropped producer boundaries.
nx_result_t	nx_stream_publish (nx_stream_t *stream, const nx_stream_fill_t *fill, size_t length, uint32_t flags)
	Publish a complete block after all hardware writes detached.
nx_result_t	nx_stream_acquire (nx_stream_t *stream, nx_stream_block_t *block)
	Acquire the next ready block for one serialized consumer.
nx_result_t	nx_stream_release (nx_stream_t *stream, const nx_stream_block_t *block)
	Release only the matching consumer incarnation after final use.
nx_result_t	nx_stream_abort (nx_stream_t *stream, const nx_stream_fill_t *fill, bool memory_quiesced)
	Abort a producer loan only after memory write sources detach.
nx_result_t	nx_stream_stop (nx_stream_t *stream)
	Close producer admission while retaining every outstanding loan.
nx_result_t	nx_stream_post_initialize (nx_stream_producer_t *producer, nx_stream_t *stream)
	Bind a posted producer to a quiescent initialized stream.
bool	nx_stream_post_can_reserve (const nx_stream_producer_t *producer)
	Query the next preposted slot without a loan or guessed loss.
nx_result_t	nx_stream_post_reserve (nx_stream_producer_t *producer, nx_stream_fill_t *fill)
	Reserve a future fill without making earlier blocks ready.
nx_result_t	nx_stream_post_publish (nx_stream_producer_t *producer, const nx_stream_fill_t *fill, size_t length, uint32_t flags)
	Publish only the oldest pending detached producer loan.
nx_result_t	nx_stream_post_abort (nx_stream_producer_t *producer, const nx_stream_fill_t *fill, bool memory_quiesced)
	Cancel the newest pending fill after proof of memory drain.

Detailed Description

Bounded caller-owned blocks with explicit producer/consumer loans.

Author

Nexus Team

Definition in file stream.h.

Macro Definition Documentation

NX_STREAM_BOUNDARY_ERROR

#define NX_STREAM_BOUNDARY_ERROR   8U

Definition at line 21 of file stream.h.

NX_STREAM_BOUNDARY_IDLE

#define NX_STREAM_BOUNDARY_IDLE   1U

Definition at line 18 of file stream.h.

NX_STREAM_BOUNDARY_LOSS

#define NX_STREAM_BOUNDARY_LOSS   4U

Definition at line 20 of file stream.h.

NX_STREAM_BOUNDARY_TRIGGER

#define NX_STREAM_BOUNDARY_TRIGGER   2U

Definition at line 19 of file stream.h.

Enumeration Type Documentation

nx_stream_slot_state_t

enum nx_stream_slot_state_t

Enumerator
NX_STREAM_SLOT_FREE
NX_STREAM_SLOT_FILLING
NX_STREAM_SLOT_READY
NX_STREAM_SLOT_BORROWED

Definition at line 23 of file stream.h.

Function Documentation

nx_stream_abort()

nx_result_t nx_stream_abort	(	nx_stream_t *	stream,
		const nx_stream_fill_t *	fill,
		bool	memory_quiesced )

Abort a producer loan only after memory write sources detach.

Parameters

[in,out]	stream	Same producer owner as reserve.
[in]	fill	Current exact loan.
[in]	memory_quiesced	True only after provider proves DMA/IRQ stopped.

Returns

Success, BUSY without proven drain, STATE for a stale token.

Note

Cancellation/deadline alone never establishes quiescence.

nx_stream_acquire()

nx_result_t nx_stream_acquire	(	nx_stream_t *	stream,
		nx_stream_block_t *	block )

Acquire the next ready block for one serialized consumer.

Parameters

[in,out]	stream	Live stream; consumer may drain during stop.
[out]	block	Immutable consumer loan with exact incarnation token.

Returns

Success, EMPTY or INVALID; empty creates no loan.

Note

Task/IRQ bounded metadata; consumer processing happens outside the mask. Release may occur out of order without overwrite.

nx_stream_can_reserve()

bool nx_stream_can_reserve

(

const nx_stream_t *

stream

)

Query the next physical slot without creating a loan or loss.

Parameters

[in]

stream

Live initialized stream with one serialized producer.

Returns

True only when admission is open and the next slot is free.

Note

Task/IRQ bounded hint. A producer still calls reserve before accessing payload; another context must not race admission.

nx_stream_initialize()

nx_result_t nx_stream_initialize	(	nx_stream_t *	stream,
		nx_stream_slot_t *	slots,
		size_t	count )

Initialize an unborrowed stream and exact supplied block array.

Parameters

[out]	stream	Fresh storage, not visible to any producer/consumer.
[in,out]	slots	Buffers distinct from all control and slot metadata.
[in]	count	Positive exact block count, not a maximum pool size.

Returns

Success or INVALID; never allocates or retains bad inputs.

Note

Task-only cold assembly. This helper does not validate DMA domains; the hardware provider must validate every block.

nx_stream_note_loss()

void nx_stream_note_loss	(	nx_stream_t *	stream,
		uint32_t	count )

Latch explicitly observed dropped producer boundaries.

Parameters

[in,out]	stream	Live stream controlled by the serialized producer.
[in]	count	Positive lost block/boundary count, never guessed bytes.

Note

Task/IRQ bounded. Saturates at UINT32_MAX; the next published block carries LOSS independently of its useful payload length.

nx_stream_post_abort()

nx_result_t nx_stream_post_abort	(	nx_stream_producer_t *	producer,
		const nx_stream_fill_t *	fill,
		bool	memory_quiesced )

Cancel the newest pending fill after proof of memory drain.

Parameters

[in,out]	producer	Same producer; rollback is strictly LIFO
[in]	fill	Exact newest pending token
[in]	memory_quiesced	Source detached, no remaining writes

Returns

SUCCESS, BUSY, STATE or INVALID; failure retains the loan

Note

O(1) task/IRQ. Does not advance consumer or published cursor; no FREE hole appears ahead of future publication. Stopping closes admission but still permits proved tail rollback.

nx_stream_post_can_reserve()

bool nx_stream_post_can_reserve

(

const nx_stream_producer_t *

producer

)

Query the next preposted slot without a loan or guessed loss.

Parameters

[in]

producer

Same exclusive serialized producer

Returns

True when the next reservation can succeed

Note

Bounded task/IRQ hint; still reserve before writing payload.

nx_stream_post_initialize()

nx_result_t nx_stream_post_initialize	(	nx_stream_producer_t *	producer,
		nx_stream_t *	stream )

Bind a posted producer to a quiescent initialized stream.

Parameters

[out]	producer	Separate caller control, not aliased with buffers
[in,out]	stream	Admission open, no outstanding producer/consumer loans

Returns

SUCCESS, INVALID, BUSY or STATE; rejected output is untouched

Note

Task-only cold binding. Caller owns exclusive producer rights and retains control until all pending fills and IRQs drain.

nx_stream_post_publish()

nx_result_t nx_stream_post_publish	(	nx_stream_producer_t *	producer,
		const nx_stream_fill_t *	fill,
		size_t	length,
		uint32_t	flags )

Publish only the oldest pending detached producer loan.

Parameters

[in,out]	producer	Same exclusive producer as reserve
[in]	fill	Exact oldest token, absent from every hardware target
[in]	length	Positive valid bytes at most the block capacity
[in]	flags	Observed IDLE/TRIGGER/ERROR boundary facts

Returns

SUCCESS, INVALID or STATE; rejection retains the loan

Note

O(1) task/IRQ. Consumer acquire/release use the original stream.

nx_stream_post_reserve()

nx_result_t nx_stream_post_reserve	(	nx_stream_producer_t *	producer,
		nx_stream_fill_t *	fill )

Reserve a future fill without making earlier blocks ready.

Parameters

[in,out]	producer	Live posted producer
[out]	fill	Exact pending loan until FIFO publish or LIFO abort

Returns

SUCCESS, OVERFLOW, STATE, EXHAUSTED or INVALID

Note

O(1) task/IRQ. Failure leaves output and loss counters intact; only explicitly observed boundaries justify note_loss.

nx_stream_publish()

nx_result_t nx_stream_publish	(	nx_stream_t *	stream,
		const nx_stream_fill_t *	fill,
		size_t	length,
		uint32_t	flags )

Publish a complete block after all hardware writes detached.

Parameters

[in,out]	stream	Same serialized producer as reserve.
[in]	fill	Current producer loan, not retained after publication.
[in]	length	Positive produced bytes within the reserved capacity.
[in]	flags	IDLE/TRIGGER boundaries observed by the provider.

Returns

Success, INVALID or STATE; failure retains producer ownership.

Note

Task/IRQ bounded. A DMA half/full flag is insufficient if the engine can still write the published block. Consumer-visible block bytes stay immutable until the consumer releases them.

nx_stream_release()

nx_result_t nx_stream_release	(	nx_stream_t *	stream,
		const nx_stream_block_t *	block )

Release only the matching consumer incarnation after final use.

Parameters

[in,out]	stream	Same consumer owner; no remaining observers of block.
[in]	block	Exact acquired token, never a reconstructed pointer.

Returns

Success, STATE for stale/double release or INVALID.

Note

Task/IRQ bounded; release is the consumer's final block access.

nx_stream_reserve()

nx_result_t nx_stream_reserve	(	nx_stream_t *	stream,
		nx_stream_fill_t *	fill )

Reserve the next free block for one serialized producer.

Parameters

[in,out]	stream	Live initialized stream with one producer.
[out]	fill	Producer loan valid until publish or proved abort.

Returns

Success, OVERFLOW without overwrite, STATE while stopping or EXHAUSTED when the monotonic loan identity cannot advance.

Note

Bounded task/IRQ metadata operation; payload writes occur outside the short interrupt mask, within the returned loan.

nx_stream_stop()

nx_result_t nx_stream_stop

(

nx_stream_t *

stream

)

Close producer admission while retaining every outstanding loan.

Parameters

[in,out]

stream

Live control kept alive until final successful stop.

Returns

Success only when all blocks are free, BUSY until producers detach and consumers drain/release, INVALID for bad control.

Note

Task/IRQ constant metadata work independent of block count. This operation does not stop hardware or revoke loans.