Framework

The object model, the negotiation and the runtime. More...

Topics
	Bins
	An element that contains other elements.
	Buffers
	What carries the data, and who provides it.
	Capability Structure
	Fixed-size container describing one media capability.
	Dispatches
	Queries and events exchanged between elements.
	Elements
	The unit a pipeline is built from.
	Messages
	What an element reports back to the application.
	Objects
	The common base that gives every type an identity and properties.
	Pad
	The point where two elements meet.
	Parsers
	Elements that cut a formless byte stream into frames.
	Pipelines
	The top-level bin, and what actually runs a graph.
	Sinks
	Elements that consume buffers, and end the stream.
	Sources
	Elements that produce buffers, and drive the negotiation.
	Threads
	A k_thread whose stack comes from a pool and outlives it.
	Transforms
	Elements with an input and an output, and the middle of a negotiation.
	Value Container
	One typed scalar or range, the smallest piece of a capability.
	Workqueues
	Optional offload of an element's work onto shared worker threads.

Detailed Description

The object model, the negotiation and the runtime.

An application declares the elements it needs, links them into a graph, and drives that graph through a state machine. The framework is what negotiates the data format between neighbors, settles which pool provides the buffers, and moves those buffers from one element to the next.

Objects is the base every type embeds; Elements is what a graph is made of and Pad is where two elements meet; Capability Structure describes what crosses a link and Dispatches carries the negotiation; Pipelines runs the result.

No dynamic allocation

The framework allocates nothing. Buffers come from pools sized while leaving READY, and every type on the negotiation path is fixed-size and held by value, so a stream that runs for hours cannot fragment a heap it never touches and a negotiation cannot fail for memory. The cost lands on the stack instead, since a negotiation holds several capabilities live at once.

This is a property to preserve rather than an implementation detail: a change that reintroduces allocation on a negotiation path is wrong however clean it looks. An element needing scratch memory takes it from the application at init, the way pools and stacks are taken.

Pointer parameters

A pointer parameter must not be NULL unless its own documentation says what NULL means for it - "or NULL to reset to ANY", "or NULL if unused". Passing NULL anywhere else is a programming error, not a runtime condition: the caller is handing over an object it owns, so there is nothing to recover from and nothing useful to report. Those are trapped by an assertion, which costs nothing once CONFIG_ASSERT is off.

Values are different. Where an argument carries data rather than an object - a capability that may be empty, a property whose value the application chose - the API validates it and returns a negative errno, because a pipeline can report that and carry on.