View Source Membrane.Bin behaviour (Membrane Core v0.11.3)

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.

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 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.

Callback invoked when bin switches the playback to :playing.

Callback invoked on bin startup, right after handle_init/2.

Callback invoked when children of Membrane.ChildrenSpec are started.

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_t/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_t() :: {[Membrane.Bin.Action.t()], state_t()}
@type name_t() :: tuple() | atom()

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/2 callback.

@type state_t() :: any()

Link to this section Callbacks

Link to this callback

handle_child_notification(notification, element, context, state)

View Source (optional)
@callback handle_child_notification(
  notification :: Membrane.ChildNotification.t(),
  element :: Membrane.Child.name_t(),
  context :: Membrane.Bin.CallbackContext.ChildNotification.t(),
  state :: state_t()
) :: callback_return_t()

Callback invoked when a notification comes in from an element.

Link to this callback

handle_element_end_of_stream(child, pad, context, state)

View Source (optional)
@callback handle_element_end_of_stream(
  child :: Membrane.Child.name_t(),
  pad :: 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.

Link to this callback

handle_element_start_of_stream(child, pad, context, state)

View Source (optional)
@callback handle_element_start_of_stream(
  child :: Membrane.Child.name_t(),
  pad :: 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.

Link to this callback

handle_info(message, context, state)

View Source (optional)
@callback handle_info(
  message :: any(),
  context :: Membrane.Bin.CallbackContext.Info.t(),
  state :: state_t()
) :: callback_return_t()

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.

Link to this callback

handle_init(context, options)

View Source (optional)
@callback handle_init(
  context :: Membrane.Bin.CallbackContext.Init.t(),
  options :: options_t()
) ::
  callback_return_t()

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.

Link to this callback

handle_pad_added(pad, context, state)

View Source (optional)
@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 been added to bin. Executed ONLY for dynamic pads.

Link to this callback

handle_pad_removed(pad, context, state)

View Source (optional)
@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 been removed. Executed ONLY for dynamic pads.

Link to this callback

handle_parent_notification(notification, context, state)

View Source (optional)
@callback handle_parent_notification(
  notification :: Membrane.ParentNotification.t(),
  context :: Membrane.Bin.CallbackContext.ParentNotification.t(),
  state :: state_t()
) :: callback_return_t()

Callback invoked when a notification comes in from an parent.

Link to this callback

handle_playing(context, state)

View Source (optional)
@callback handle_playing(
  context :: Membrane.Bin.CallbackContext.Playing.t(),
  state :: state_t()
) :: callback_return_t()

Callback invoked when bin switches the playback to :playing.

Link to this callback

handle_setup(context, state)

View Source (optional)
@callback handle_setup(
  context :: Membrane.Bin.CallbackContext.Setup.t(),
  state :: state_t()
) :: callback_return_t()

Callback invoked on bin startup, right after handle_init/2.

Any long-lasting or complex initialization should happen here.

Link to this callback

handle_spec_started(children, context, state)

View Source (optional)
@callback handle_spec_started(
  children :: [Membrane.Child.name_t()],
  context :: Membrane.Bin.CallbackContext.SpecStarted.t(),
  state :: state_t()
) :: callback_return_t()

Callback invoked when children of Membrane.ChildrenSpec are started.

Link to this callback

handle_terminate_request(context, state_t)

View Source (optional)
@callback handle_terminate_request(
  context :: Membrane.Bin.CallbackContext.TerminateRequest.t(),
  state_t()
) ::
  callback_return_t()

A callback invoked when the bin is being removed by its parent.

By default it returns Membrane.Bin.Action.terminate_t/0 with reason :normal.

Link to this callback

handle_tick(timer_id, context, state)

View Source (optional)
@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.

Link to this section Functions

Link to this macro

__using__(options)

View Source (macro)

Brings all the stuff necessary to implement a bin.

Options:

@spec bin?(module()) :: boolean()

Checks whether module is a bin.

Link to this macro

def_clock(doc \\ "")

View Source (macro)

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.

Link to this macro

def_input_pad(name, spec)

View Source (macro)

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_t/0 describes how the definition of pads should look.

Link to this macro

def_options(options)

View Source (macro)

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 struct
  • default: default value for option. If not present, value for this option will have to be provided each time options struct is created
  • inspector: function converting fields' value to a string. Used when creating documentation instead of inspect/1, eg. inspector: &Membrane.Time.inspect/1
  • description: string describing an option. It will be used for generating the docs
Link to this macro

def_output_pad(name, spec)

View Source (macro)

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_t/0 describes how the definition of pads should look.

Link to this macro

is_bin_name?(arg)

View Source (macro)