View Source Membrane.Pad (Membrane Core v1.0.1)

Pads are units defined by elements and bins, allowing them to be linked with their siblings. This module consists of pads typespecs and utils.

Each pad is described by its name, direction, availability, mode and possible stream format. For pads to be linkable, these properties have to be compatible. For more information on each of them, check appropriate type in this module.

Each link can only consist of exactly two pads.

Summary

Types

Describes pattern, that should be matched by stream format send by element on specific pad. Will not be evaluated during runtime, but used for matching struct passed in :stream_format action. Can be a module name, pattern describing struct, or call to any_of function, which arguments are such patterns or modules names. If a module name is passed to the :accepted_format option or is passed to any_of, it will be converted to the match on a struct defined in that module, eg. accepted_format: My.Format will have this same effect, as accepted_format: %My.Format{} and accepted_format: any_of(My.Format, %My.Another.Format{field: value} when value in [:some, :enumeration]) will have this same effect, as accepted_format: any_of(%My.Format{}, %My.Another.Format{field: value} when value in [:some, :enumeration])

Values used when defining pad availability

Type describing availability mode of a created pad

Describes how a pad should be declared inside a bin.

Type describing a pad. Contains data parsed from spec/0

Defines possible pad directions

Possible id of dynamic pad

Describes how a pad should be declared inside an element.

Describes how an element sends and receives data.

Defines the name of pad or group of dynamic pads

Defines the term by which the pad instance is identified.

Describes how a pad should be declared in element or bin.

Types

@type accepted_format() :: module() | (pattern :: term())

Describes pattern, that should be matched by stream format send by element on specific pad. Will not be evaluated during runtime, but used for matching struct passed in :stream_format action. Can be a module name, pattern describing struct, or call to any_of function, which arguments are such patterns or modules names. If a module name is passed to the :accepted_format option or is passed to any_of, it will be converted to the match on a struct defined in that module, eg. accepted_format: My.Format will have this same effect, as accepted_format: %My.Format{} and accepted_format: any_of(My.Format, %My.Another.Format{field: value} when value in [:some, :enumeration]) will have this same effect, as accepted_format: any_of(%My.Format{}, %My.Another.Format{field: value} when value in [:some, :enumeration])

@type availability() :: :always | :on_request

Values used when defining pad availability:

  • :always - a static pad, which can remain unlinked in stopped state only.
  • :on_request - a dynamic pad, instance of which is created every time it is linked to another pad. Thus linking the pad with k other pads, creates k instances of the pad, and links each with another pad.
@type availability_mode() :: :static | :dynamic

Type describing availability mode of a created pad:

  • :static - there always exist exactly one instance of such pad.
  • :dynamic - multiple instances of such pad may be created and removed (which entails executing handle_pad_added and handle_pad_removed callbacks, respectively).
@type bin_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   options: Keyword.t()}

Describes how a pad should be declared inside a bin.

Demand unit is derived from the first element inside the bin linked to the given input.

@type description() :: %{
  :availability => availability(),
  optional(:flow_control) => flow_control(),
  :name => name(),
  :accepted_formats_str => [String.t()],
  optional(:demand_unit) => Membrane.Buffer.Metric.unit() | nil,
  direction: direction(),
  options: nil | Keyword.t()
}

Type describing a pad. Contains data parsed from spec/0

@type direction() :: :output | :input

Defines possible pad directions:

  • :output - data can only be sent through such pad,
  • :input - data can only be received through such pad.

One cannot link two pads with the same direction.

@type dynamic_id() :: any()

Possible id of dynamic pad

@type element_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   flow_control: flow_control(),
   options: Keyword.t(),
   demand_unit: Membrane.Buffer.Metric.unit()}

Describes how a pad should be declared inside an element.

@type flow_control() :: :auto | :manual | :push

Describes how an element sends and receives data.

The available values for that field are:

  • :manual - meaning that the pad works in a pull mode and the demand is manually handled and requested. An element with output :manual pad can send data through such a pad only if it has already received demand on that pad. And element with input :manual pad receives data through such a pad only if it has been previously demanded, so that no undemanded data can arrive For more info, see Membrane.Element.Action.demand, Membrane.Element.Action.redemand and Membrane.Element.WithOutputPads.handle_demand/5.
  • :auto - meaning that the pad works in a pull mode and the demand is managed automatically: the core ensures that there's demand on each input pad (that has flow_control set to :auto) whenever there's demand on all output pads (that have flow_control set to :auto). Currently works for Membrane.Filters, Membrane.Endpoints and Membrane.Sinks.
  • :push - meaning that the pad works in a push mode. An element with a :push output pad can send data through that pad whenever it wants. An element with a :push input pad has to deal with data whenever it comes through such a pad - note, that it needs to be done fast enough so that not to let data accumulate, what may lead to overflow of element process erlang queue, which is highly unwanted.

Linking pads with different flow control is possible, but only in case of an output pad working in a push mode, and an input pad in pull mode (that is - with :manual or :auto flow control). In such case, however, an error will be raised whenever too many buffers accumulate on the input pad, waiting to be processed.

@type name() :: atom()

Defines the name of pad or group of dynamic pads

@type ref() :: name() | {Membrane.Pad, name(), dynamic_id()}

Defines the term by which the pad instance is identified.

@type spec() :: element_spec() | bin_spec()

Describes how a pad should be declared in element or bin.

Functions

@spec availability_mode(availability()) :: availability_mode()

Returns pad availability mode for given availability.

Link to this macro

is_availability(term)

View Source (macro)
Link to this macro

is_availability_dynamic(availability)

View Source (macro)
Link to this macro

is_availability_static(availability)

View Source (macro)
Link to this macro

is_dynamic_pad_ref(term)

View Source (macro)
Link to this macro

is_pad_name(term)

View Source (macro)
Link to this macro

is_pad_ref(term)

View Source (macro)
Link to this macro

is_static_pad_ref(term)

View Source (macro)
@spec name_by_ref(ref()) :: name()

Returns the name for the given pad reference

Link to this function

opposite_direction(atom)

View Source
@spec opposite_direction(direction()) :: direction()

Creates a static pad reference.

Creates a dynamic pad reference.