Membrane Core v0.5.0 Membrane.Bin behaviour View Source

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

state_t()

Functions

__using__(options)

Brings all the stuff necessary to implement a pipeline.

bin?(module)

Checks whether module is a bin.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

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_output_pad(name, spec)

Macro that defines output pad for the bin.

start_link(my_name, module, bin_options \\ nil, process_options \\ [])

Starts the Bin based on given module and links it to the current process.

stop_and_terminate(bin)

Changes bin's playback state to :stopped and terminates its process

Callbacks

handle_init(options)

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_pad_added(pad, context, state)

Callback that is called when new pad has beed 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 beed removed. Executed ONLY for dynamic pads.

membrane_bin?()

Enables to check whether module is membrane bin.

membrane_clock?()

Automatically implemented callback used to determine whether bin exports clock.

Link to this section Types

callback_return_t()

callback_return_t() ::
  {:ok | {:ok, [Membrane.Parent.Action.t()]} | {:error, any()}, state_t()}
  | {:error, any()}

name_t()

name_t() :: any()

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

options_t()

options_t() :: struct() | nil

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

state_t()

state_t() :: Membrane.Core.Bin.State.t()

Link to this section Functions

using(options)

(macro)

Brings all the stuff necessary to implement a pipeline.

Options:

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

bin?(module)

bin?(module()) :: boolean()

Checks whether module is a bin.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

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.

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.

def_output_pad(name, spec)

(macro)

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.

start_link(my_name, module, bin_options \\ nil, process_options \\ [])

start_link(
  atom(),
  module(),
  bin_options :: options_t(),
  process_options :: GenServer.options()
) :: GenServer.on_start()

Starts the Bin based on given module and links it to the current process.

Bin options are passed to module's handle_init/1 callback.

Process options are internally passed to GenServer.start_link/3.

Returns the same values as GenServer.start_link/3.

stop_and_terminate(bin)

stop_and_terminate(bin :: pid()) :: :ok

Changes bin's playback state to :stopped and terminates its process

Link to this section Callbacks

handle_init(options)

handle_init(options :: options_t()) ::
  {{:ok, Membrane.ParentSpec.t()}, Membrane.Core.Bin.State.internal_state_t()}
  | {:error, any()}

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_pad_added(pad, context, state)

handle_pad_added(
  pad :: Membrane.Pad.ref_t(),
  context :: Membrane.Bin.CallbackContext.PadAdded.t(),
  state :: Membrane.Core.Bin.State.internal_state_t()
) :: callback_return_t()

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

handle_pad_removed(pad, context, state)

handle_pad_removed(
  pad :: Membrane.Pad.ref_t(),
  context :: Membrane.Bin.CallbackContext.PadRemoved.t(),
  state :: Membrane.Core.Bin.State.internal_state_t()
) :: callback_return_t()

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

membrane_bin?()

membrane_bin?() :: true

Enables to check whether module is membrane bin.

membrane_clock?()

membrane_clock?() :: boolean()

Automatically implemented callback used to determine whether bin exports clock.