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.
Functions
Returns pad availability mode for given availability.
Returns the name for the given pad reference
Creates a static pad reference.
Creates a dynamic pad reference.
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])
@type availability() :: :always | :on_request
Values used when defining pad availability:
:always
- a static pad, which can remain unlinked instopped
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 executinghandle_pad_added
andhandle_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, seeMembrane.Element.Action.demand
,Membrane.Element.Action.redemand
andMembrane.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 hasflow_control
set to:auto
) whenever there's demand on all output pads (that haveflow_control
set to:auto
). Currently works forMembrane.Filter
s,Membrane.Endpoint
s andMembrane.Sink
s.: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.
Returns the name for the given pad reference
Creates a static pad reference.
Creates a dynamic pad reference.