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

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

callback_return_t()

name_t()

Type that defines a bin name by which it is identified.

options_t()

Defines options that can be passed to start_link/3 and received in handle_init/2 callback.

state_t()

Callbacks

handle_child_notification(notification, element, context, state)

Callback invoked when a notification comes in from an element.

handle_element_end_of_stream(child, pad, context, state)

Callback invoked when a child element finishes processing stream via given pad.

handle_element_start_of_stream(child, pad, context, state)

Callback invoked when a child element starts processing stream via given pad.

handle_info(message, context, state)

Callback invoked when bin receives a message that is not recognized as an internal membrane message.

handle_init(context, options)

Callback invoked on initialization of bin.

handle_pad_added(pad, context, state)

Callback that is called when new pad has been added to bin. Executed ONLY for dynamic pads.

handle_pad_removed(pad, context, state)

Callback that is called when some pad of the bin has been removed. Executed ONLY for dynamic pads.

handle_parent_notification(notification, context, state)

Callback invoked when a notification comes in from an parent.

handle_playing(context, state)

Callback invoked when bin switches the playback to :playing.

handle_setup(context, state)

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

handle_spec_started(children, context, state)

Callback invoked when children of Membrane.ChildrenSpec are started.

handle_terminate_request(context, state_t)

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

handle_tick(timer_id, context, state)

Callback invoked upon each timer tick. A timer can be started with Membrane.Bin.Action.start_timer_t/0 action.

Functions

__using__(options)

Brings all the stuff necessary to implement a bin.

bin?(module)

Checks whether module is a bin.

def_clock(doc \\ "")

Defines that bin exposes a clock which is a proxy to one of its children.

def_input_pad(name, spec)

Macro that defines input pad for the bin.

def_options(options)

Macro defining options that parametrize bin.

def_output_pad(name, spec)

Macro that defines output pad for the bin.

is_bin_name?(arg)

Link to this section Types

callback_return_t()

@type callback_return_t() :: {[Membrane.Bin.Action.t()], state_t()}

name_t()

@type name_t() :: tuple() | atom()

Type that defines a bin name by which it is identified.

options_t()

@type options_t() :: struct() | nil

Defines options that can be passed to start_link/3 and received in handle_init/2 callback.

state_t()

@type state_t() :: any()

Link to this section Callbacks

handle_child_notification(notification, element, context, state)

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

handle_element_end_of_stream(child, pad, context, state)

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

handle_element_start_of_stream(child, pad, context, state)

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

handle_info(message, context, state)

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

handle_init(context, options)

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

handle_pad_added(pad, context, state)

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

handle_pad_removed(pad, context, state)

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

handle_parent_notification(notification, context, state)

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

handle_playing(context, state)

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

handle_setup(context, state)

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

handle_spec_started(children, context, state)

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

handle_terminate_request(context, state_t)

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

handle_tick(timer_id, context, state)

(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

using(options)

(macro)

Brings all the stuff necessary to implement a bin.

Options:

:bring_spec? - if true (default) imports and aliases Membrane.ChildrenSpec
:bring_pad? - if true (default) requires and aliases Membrane.Pad

bin?(module)

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

Checks whether module is a bin.

def_clock(doc \\ "")

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

def_input_pad(name, spec)

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

def_options(options)

(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

def_output_pad(name, spec)

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

is_bin_name?(arg)

(macro)

Settings View Source Membrane.Bin behaviour (Membrane Core v0.11.0)

Link to this section Summary

Types

Callbacks

Functions

Link to this section Types

callback_return_t()

name_t()

options_t()

state_t()

Link to this section Callbacks

handle_child_notification(notification, element, context, state)

handle_element_end_of_stream(child, pad, context, state)

handle_element_start_of_stream(child, pad, context, state)

handle_info(message, context, state)

handle_init(context, options)

handle_pad_added(pad, context, state)

handle_pad_removed(pad, context, state)

handle_parent_notification(notification, context, state)

handle_playing(context, state)

handle_setup(context, state)

handle_spec_started(children, context, state)

handle_terminate_request(context, state_t)

handle_tick(timer_id, context, state)

Link to this section Functions

__using__(options)

bin?(module)

def_clock(doc \\ "")

def_input_pad(name, spec)

def_options(options)

def_output_pad(name, spec)

is_bin_name?(arg)

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

using(options)