Bins

An element that contains other elements. More...

Files
file	mpipe_bin.h
	Bin: an element that contains other elements.

Data Structures
struct	mpipe_bin
	Bin structure. More...

Functions
int	mpipe_bin_init (struct mpipe_bin *bin, uint8_t id)
	Initialize a bin.
int	mpipe_bin_set_bus_validator (struct mpipe_bin *bin, zbus_validator bus_validator, void *user_data)
	Install a validator and user data on the bin's bus.
int	mpipe_bin_add (struct mpipe_bin *bin, struct mpipe_element *element,...)
	Add elements to a bin.
int	mpipe_bin_change_state_func (struct mpipe_element *element, enum mpipe_state_change transition)
	Bin state change function.

Detailed Description

An element that contains other elements.

A bin is itself an Elements, so a graph can be treated as one element from the outside. Its job is to hold children and to forward a state change to them in an order that is safe.

That order is not the order they were added. The bin sorts its children topologically by their links and walks them from the sink towards the source when the transition goes up, so a downstream element is ready before anything is pushed into it, and from the source towards the sink when it goes down, so nothing keeps producing into an element that has already been torn down. CONFIG_MPIPE_BIN_MAX_CHILDREN bounds the arrays that sort uses.

A bin also owns the message channel its children report on, which is how a failure deep in a graph reaches the application. See Messages.

Function Documentation

mpipe_bin_add()

int mpipe_bin_add	(	struct mpipe_bin *	bin,
		struct mpipe_element *	element,
			... )

#include <mpipe_bin.h>

Add elements to a bin.

Adds the given element(s) to the bin.

An element can only be added to one bin. Element ids must be unique within the bin.

The function accepts a variable number of elements, terminated by NULL.

Adding an element leaves its pads alone, so elements may be added before or after they are linked.

Parameters

bin	Pointer to the Bins to add elements to
element	First Elements to add
...	Additional mpipe_element pointers, terminated by NULL

Returns

0 on success, negative errno on failure

mpipe_bin_change_state_func()

int mpipe_bin_change_state_func	(	struct mpipe_element *	element,
		enum mpipe_state_change	transition )

#include <mpipe_bin.h>

Bin state change function.

Handles state changes for the bin by propagating the state change to all child elements in the appropriate order. The bin manages the topology and ensures proper sequencing of state changes.

Parameters

element	Pointer to the Elements (bin) changing state
transition	The state transition being performed

Returns

0 on success, else the errno of the child that refused

Return values

-ENOSPC	The bin holds more children than fit
-EINVAL	Children cannot be ordered

mpipe_bin_init()

int mpipe_bin_init	(	struct mpipe_bin *	bin,
		uint8_t	id )

#include <mpipe_bin.h>

Initialize a bin.

Initializes the bin structure and sets up the necessary function pointers and data structures.

Parameters

bin	Pointer to the Bins to initialize.
id	Unique element identifier.

Returns

0 on success, negative errno otherwise.

mpipe_bin_set_bus_validator()

int mpipe_bin_set_bus_validator	(	struct mpipe_bin *	bin,
		zbus_validator	bus_validator,
		void *	user_data )

#include <mpipe_bin.h>

Install a validator and user data on the bin's bus.

mpipe_bin_init brings the channel up with no validator, since a bin has no opinion on the messages passing through it. An element wrapping a bin (a pipeline, say) uses this to install its own.

Only those two fields change, under the channel's own lock. Observers already attached stay attached, and may be attached before or after this call.

Parameters

bin	Pointer to the Bins.
bus_validator	Message validator to install, or NULL for no validation.
user_data	User data associated with the bus, retrievable from the validator/observers via zbus_chan_user_data(), or NULL if unused.

Returns

0 on success, negative errno on failure