View Source Membrane.Bin behaviour (Membrane Core v1.1.2)
Bins, similarly to pipelines, are containers for elements. However, at the same time, they can be placed and linked within pipelines. Although bin is a separate Membrane entity, it can be perceived as a pipeline within an element. Bins can also be nested within one another.
There are two main reasons why bins are useful:
- they enable creating reusable element groups
- they allow managing their children, for instance by dynamically spawning or replacing them as the stream changes.
In order to create bin use Membrane.Bin in your callback module.
Link to this section Summary
Types
Type that defines a bin name by which it is identified.
Defines options that can be passed to start_link/3 and received
in handle_init/2 callback.
Callbacks
Callback invoked when a notification comes in from an element. By default, it ignores the received message.
Callback invoked when a child removes its pad.
Callback invoked when a child enters playing playback.
Callback invoked when a child complete its setup.
Callback invoked after a child terminates.
Callback invoked when crash of the crash group happens.
Callback invoked when a child element finishes processing stream via given pad.
Callback invoked when a child element starts processing stream via given pad. By default, it does nothing.
Callback invoked when bin receives a message that is not recognized as an internal membrane message.
Callback invoked on initialization of bin.
Callback that is called when new pad has been added to bin. Executed ONLY for dynamic pads.
Callback that is called when some pad of the bin has been removed. Executed ONLY for dynamic pads.
Callback invoked when a notification comes in from an parent. By default, it ignores the received message.
Callback invoked when bin switches the playback to :playing.
By default, it does nothing.
Callback invoked on bin startup, right after handle_init/2.
This callback is deprecated since v1.1.0.
A callback invoked when the bin is being removed by its parent.
Callback invoked upon each timer tick. A timer can be started with Membrane.Bin.Action.start_timer/0
action.
Functions
Brings all the stuff necessary to implement a bin.
Checks whether module is a bin.
Defines that bin exposes a clock which is a proxy to one of its children.
Macro that defines input pad for the bin.
Macro defining options that parametrize bin.
Macro that defines output pad for the bin.
Link to this section Types
@type callback_return() :: {[Membrane.Bin.Action.t()], state()}
Type that defines a bin name by which it is identified.
@type options() :: struct() | nil
Defines options that can be passed to start_link/3 and received
in handle_init/2 callback.
@type state() :: any()
Link to this section Callbacks
handle_child_notification(notification, element, context, state)
View Source (optional)@callback handle_child_notification( notification :: Membrane.ChildNotification.t(), element :: Membrane.Child.name(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when a notification comes in from an element. By default, it ignores the received message.
@callback handle_child_pad_removed( child :: Membrane.Child.name(), pad :: Membrane.Pad.ref(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when a child removes its pad.
The callback won't be invoked, when you have initiated the pad removal,
eg. when you have returned t:Membrane.Bin.Action.remove_link() action
which made one of your children's pads be removed.
By default, it does nothing.
@callback handle_child_playing( child :: Membrane.Child.name(), context :: Membrane.Bin.CallbackContext.t(), state() ) :: callback_return()
Callback invoked when a child enters playing playback.
By default, it does nothing.
@callback handle_child_setup_completed( child :: Membrane.Child.name(), context :: Membrane.Bin.CallbackContext.t(), state() ) :: callback_return()
Callback invoked when a child complete its setup.
By default, it does nothing.
@callback handle_child_terminated( child :: Membrane.Child.name(), context :: Membrane.Bin.CallbackContext.t(), state() ) :: callback_return()
Callback invoked after a child terminates.
Terminated child won't be present in the context of this callback. It is allowed to spawn a new child with the same name.
By default, it does nothing.
@callback handle_crash_group_down( group_name :: Membrane.Child.group(), context :: Membrane.Bin.CallbackContext.t(), state() ) :: callback_return()
Callback invoked when crash of the crash group happens.
Context passed to this callback contains 2 additional fields: :members and :crash_initiator.
handle_element_end_of_stream(child, pad, context, state)
View Source (optional)@callback handle_element_end_of_stream( child :: Membrane.Child.name(), pad :: Membrane.Pad.ref(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when a child element finishes processing stream via given pad.
By default, it does nothing.
handle_element_start_of_stream(child, pad, context, state)
View Source (optional)@callback handle_element_start_of_stream( child :: Membrane.Child.name(), pad :: Membrane.Pad.ref(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when a child element starts processing stream via given pad. By default, it does nothing.
@callback handle_info( message :: any(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when bin receives a message that is not recognized as an internal membrane message.
Can be used for receiving data from non-membrane processes. By default, it logs and ignores the received message.
@callback handle_init(context :: Membrane.Bin.CallbackContext.t(), options :: options()) :: callback_return()
Callback invoked on initialization of bin.
This callback is synchronous: the parent waits until it finishes. Also, any failures
that happen in this callback crash the parent as well, regardless of crash groups.
For these reasons, it's important to do any long-lasting or complex work in handle_setup/2,
while handle_init should be used for things like parsing options, initializing state or
spawning children.
By default, it converts the opts struct to a map and sets them as the bin's state.
@callback handle_pad_added( pad :: Membrane.Pad.ref(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback that is called when new pad has been added to bin. Executed ONLY for dynamic pads.
Context passed to this callback contains additional field :pad_options.
By default, it does nothing.
@callback handle_pad_removed( pad :: Membrane.Pad.ref(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback that is called when some pad of the bin has been removed. Executed ONLY for dynamic pads.
Context passed to this callback contains additional field :pad_options.
By default, it does nothing.
handle_parent_notification(notification, context, state)
View Source (optional)@callback handle_parent_notification( notification :: Membrane.ParentNotification.t(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when a notification comes in from an parent. By default, it ignores the received message.
@callback handle_playing( context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked when bin switches the playback to :playing.
By default, it does nothing.
@callback handle_setup( context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked on bin startup, right after handle_init/2.
Any long-lasting or complex initialization should happen here. By default, it does nothing.
@callback handle_spec_started( children :: [Membrane.Child.name()], context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
This callback is deprecated since v1.1.0.
Callback invoked when children of Membrane.ChildrenSpec are started.
It is invoked, only if pipeline module contains its definition. Otherwise, nothing happens.
@callback handle_terminate_request( context :: Membrane.Bin.CallbackContext.t(), state() ) :: callback_return()
A callback invoked when the bin is being removed by its parent.
By default, it returns Membrane.Bin.Action.terminate/0 with reason :normal.
@callback handle_tick( timer_id :: any(), context :: Membrane.Bin.CallbackContext.t(), state :: state() ) :: callback_return()
Callback invoked upon each timer tick. A timer can be started with Membrane.Bin.Action.start_timer/0
action.
Link to this section Functions
Brings all the stuff necessary to implement a bin.
Options:
:bring_spec?- if true (default) imports and aliasesMembrane.ChildrenSpec:bring_pad?- if true (default) requires and aliasesMembrane.Pad
Checks whether module is a bin.
Defines that bin exposes a clock which is a proxy to one of its children.
If this macro is not called, no ticks will be forwarded to parent, regardless of clock definitions in its children.
Macro that defines input pad for the bin.
It automatically generates documentation from the given definition and adds compile-time stream format specs validation.
The type Membrane.Pad.bin_spec/0 describes how the definition of pads should look.
Macro defining options that parametrize bin.
It automatically generates appropriate struct and documentation.
Options are defined by a keyword list, where each key is an option name and is described by another keyword list with following fields:
spec:typespec for value in structdefault:default value for option. If not present, value for this option will have to be provided each time options struct is createdinspector:function converting fields' value to a string. Used when creating documentation instead ofinspect/1, eg.inspector: &Membrane.Time.inspect/1description:string describing an option. It will be used for generating the docs
Macro that defines output pad for the bin.
It automatically generates documentation from the given definition and adds compile-time stream format specs validation.
The type Membrane.Pad.bin_spec/0 describes how the definition of pads should look.