View Source Membrane.Clock (Membrane Core v0.11.0)
Clock is a Membrane utility that allows elements to measure time according to a particular clock, which can be e.g. a soundcard hardware clock.
Internally, Clock is a GenServer process that can receive updates (see update_message_t/0),
which are messages containing amount of time until the next update.
For example, a sink playing audio to the sound card can send an update before
each write to the sound card buffer (for practical reasons that can be done every
100 or 1000 writes). Although it might be more intuitive to send updates with
the time passed, in practice the described approach turns out to be more convenient,
as it simplifies the first update.
Basing on updates, Clock calculates the ratio_t/0 of its time to the reference
time. The reference time can be configured with :time_provider option. The ratio
is broadcasted (see ratio_message_t/0) to subscribers (see subscribe/2)
- processes willing to synchronize to the custom clock. Subscribers can adjust
their timers according to received ratio - timers started with
Membrane.Element.Action.start_timer_t/0action in elements do it automatically. Initial ratio is equal to 1, which means that if no updates are received, Clock is synchronized to the reference time.
proxy-mode
Proxy mode
Clock can work in proxy mode, which means it cannot receive updates, but
it receives ratio from another clock instead, and forwards it to subscribers.
Proxy mode is enabled with proxy_for: pid or proxy: true (no initial proxy)
option, and the proxy is set/changed using proxy_for/2.
Link to this section Summary
Types
Options accepted by start_link/2 and start/2 functions.
Ratio message sent by the Clock to all its subscribers. It contains the ratio of the custom clock time to the reference time.
Ratio of the Clock time to the reference time.
Update message received by the Clock. It should contain the time till the next update.
Functions
Returns a specification to start this module under a supervisor.
Sets a new proxy clock to clock_to_proxy_for.
Subscribes pid for receiving ratio_message_t/0 messages from the clock.
Unsubscribes pid from receiving ratio_message_t/0 messages from the clock.
Link to this section Types
@type option_t() :: {:time_provider, (() -> Membrane.Time.t())} | {:proxy, boolean()} | {:proxy_for, pid() | nil}
Options accepted by start_link/2 and start/2 functions.
They are the following:
time_provider- function providing the reference time in millisecondsproxy- determines whether the Clock should work in proxy modeproxy_for- enables the proxy mode and sets proxied Clock to pid
Check the moduledoc for more details.
Ratio message sent by the Clock to all its subscribers. It contains the ratio of the custom clock time to the reference time.
@type ratio_t() :: Ratio.t() | non_neg_integer()
Ratio of the Clock time to the reference time.
@type t() :: pid()
@type update_message_t() :: {:membrane_clock_update, milliseconds :: non_neg_integer() | Ratio.t() | {numerator :: non_neg_integer(), denominator :: pos_integer()}}
Update message received by the Clock. It should contain the time till the next update.
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
Sets a new proxy clock to clock_to_proxy_for.
@spec start([option_t()], GenServer.options()) :: GenServer.on_start()
@spec start_link([option_t()], GenServer.options()) :: GenServer.on_start()
Subscribes pid for receiving ratio_message_t/0 messages from the clock.
This function can be called multiple times from the same process. To unsubscribe,
unsubscribe/2 should be called the same amount of times. The subscribed pid
always receives one message, regardless of how many times it called subscribe/2.
Unsubscribes pid from receiving ratio_message_t/0 messages from the clock.
For unsubscription to take effect, unsubscribe/2 should be called the same
amount of times as subscribe/2.