View Source Membrane.Bin behaviour (Membrane Core v0.10.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/1 callback.
Callbacks
Callback invoked when a child element finishes processing stream via given pad.
Callback invoked when a child element starts processing stream via given pad.
Callback invoked on initialization of bin process. It should parse options
and initialize bin's internal state. Internally it is invoked inside
GenServer.init/1 callback.
Callback invoked when a notification comes in from an element.
Callback invoked when bin receives a message that is not recognized as an internal membrane message.
Callback that is called when new pad has beed added to bin. Executed ONLY for dynamic pads.
Callback that is called when some pad of the bin has beed removed. Executed ONLY for dynamic pads.
Callback invoked when bin transition from :playing to :prepared state has finished,
that is all of its children are prepared to be stopped.
Callback invoked when bin is in :playing state, i.e. all its children
are in this state.
Callback invoked when bin is in :playing state, i.e. all its children
are in this state.
Callback invoked when bin is shutting down.
Internally called in GenServer.terminate/2 callback.
Callback invoked when Membrane.ParentSpec is linked and in the same playback
state as bin.
Callback invoked when bin transition from :stopped to :prepared state has finished,
that is all of its children are prepared to enter :playing state.
Callback invoked when bin is in :terminating state, i.e. all its children
are in this state.
Callback invoked upon each timer tick. A timer can be started with Membrane.Bin.Action.start_timer_t/0
action.
Enables to check whether module is membrane bin.
Automatically implemented callback used to determine whether bin exports clock.
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_t() :: {:ok | {:ok, [Membrane.Bin.Action.t()]} | {:error, any()}, state_t()} | {:error, any()}
@type name_t() :: any()
Type that defines a bin name by which it is identified.
@type options_t() :: struct() | nil
Defines options that can be passed to start_link/3 and received
in handle_init/1 callback.
Link to this section Callbacks
@callback handle_element_end_of_stream( {Membrane.Child.name_t(), Membrane.Pad.ref_t()}, context :: Membrane.Bin.CallbackContext.StreamManagement.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when a child element finishes processing stream via given pad.
@callback handle_element_start_of_stream( {Membrane.Child.name_t(), Membrane.Pad.ref_t()}, context :: Membrane.Bin.CallbackContext.StreamManagement.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when a child element starts processing stream via given pad.
@callback handle_init(options :: options_t()) :: callback_return_t()
Callback invoked on initialization of bin process. It should parse options
and initialize bin's internal state. Internally it is invoked inside
GenServer.init/1 callback.
handle_notification( notification, element, context, state )
View Source (optional)@callback handle_notification( notification :: Membrane.Notification.t(), element :: Membrane.Child.name_t(), context :: Membrane.Bin.CallbackContext.Notification.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when a notification comes in from an element.
@callback handle_other( message :: any(), context :: Membrane.Bin.CallbackContext.Other.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin receives a message that is not recognized as an internal membrane message.
Useful for receiving data sent from NIFs or other stuff.
@callback handle_pad_added( pad :: Membrane.Pad.ref_t(), context :: Membrane.Bin.CallbackContext.PadAdded.t(), state :: state_t() ) :: callback_return_t()
Callback that is called when new pad has beed added to bin. Executed ONLY for dynamic pads.
@callback handle_pad_removed( pad :: Membrane.Pad.ref_t(), context :: Membrane.Bin.CallbackContext.PadRemoved.t(), state :: state_t() ) :: callback_return_t()
Callback that is called when some pad of the bin has beed removed. Executed ONLY for dynamic pads.
@callback handle_playing_to_prepared( context :: Membrane.Bin.CallbackContext.PlaybackChange.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin transition from :playing to :prepared state has finished,
that is all of its children are prepared to be stopped.
@callback handle_prepared_to_playing( context :: Membrane.Bin.CallbackContext.PlaybackChange.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin is in :playing state, i.e. all its children
are in this state.
@callback handle_prepared_to_stopped( context :: Membrane.Bin.CallbackContext.PlaybackChange.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin is in :playing state, i.e. all its children
are in this state.
@callback handle_shutdown(reason, state :: state_t()) :: :ok when reason: :normal | :shutdown | {:shutdown, any()} | term()
Callback invoked when bin is shutting down.
Internally called in GenServer.terminate/2 callback.
Useful for any cleanup required.
@callback handle_spec_started( children :: [Membrane.Child.name_t()], context :: Membrane.Bin.CallbackContext.SpecStarted.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when Membrane.ParentSpec is linked and in the same playback
state as bin.
This callback can be started from handle_init/1 callback or as
Membrane.Bin.Action.spec_t/0 action.
@callback handle_stopped_to_prepared( context :: Membrane.Bin.CallbackContext.PlaybackChange.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin transition from :stopped to :prepared state has finished,
that is all of its children are prepared to enter :playing state.
@callback handle_stopped_to_terminating( context :: Membrane.Bin.CallbackContext.PlaybackChange.t(), state :: state_t() ) :: callback_return_t()
Callback invoked when bin is in :terminating state, i.e. all its children
are in this state.
@callback handle_tick( timer_id :: any(), context :: Membrane.Bin.CallbackContext.Tick.t(), state :: state_t() ) :: callback_return_t()
Callback invoked upon each timer tick. A timer can be started with Membrane.Bin.Action.start_timer_t/0
action.
@callback membrane_bin?() :: true
Enables to check whether module is membrane bin.
@callback membrane_clock?() :: boolean()
Automatically implemented callback used to determine whether bin exports clock.
Link to this section Functions
Brings all the stuff necessary to implement a bin.
Options:
:bring_spec?- if true (default) imports and aliasesMembrane.ParentSpec: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.
Allows to use one_of/1 and range/2 functions from Membrane.Caps.Matcher
without module prefix.
It automatically generates documentation from the given definition and adds compile-time caps specs validation.
The type Membrane.Pad.bin_spec_t/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:
type:atom, used for parsingspec:typespec for value in struct. If ommitted, for types:[:atom, :boolean, :caps, :keyword, :string, :struct, :time]the default typespec is provided, for others typespec is set toany/0default: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/1description:string describing an option. It will be used for generating the docs
Macro that defines output pad for the bin.
Allows to use one_of/1 and range/2 functions from Membrane.Caps.Matcher
without module prefix.
It automatically generates documentation from the given definition and adds compile-time caps specs validation.
The type Membrane.Pad.bin_spec_t/0 describes how the definition of pads should look.