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

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/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/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/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/0 action 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

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.

Summary

Types

Options accepted by start_link/2 and start/2 functions.

Ratio of the Clock time to the reference time.

Ratio message sent by the Clock to all its subscribers. It contains the ratio of the custom clock time to the reference time.

t()

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.

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/0 messages from the clock.

Unsubscribes pid from receiving ratio_message/0 messages from the clock.

Types

@type option() ::
  {: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 milliseconds
  • proxy - determines whether the Clock should work in proxy mode
  • proxy_for - enables the proxy mode and sets proxied Clock to pid

Check the moduledoc for more details.

@type ratio() :: Ratio.t()

Ratio of the Clock time to the reference time.

@type ratio_message() :: {:membrane_clock_ratio, clock :: pid(), ratio()}

Ratio message sent by the Clock to all its subscribers. It contains the ratio of the custom clock time to the reference time.

@type t() :: pid()

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/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/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/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/0 action 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

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.

@type update_message() ::
  {:membrane_clock_update,
   milliseconds ::
     non_neg_integer()
     | ratio()
     | {numerator :: non_neg_integer(), denominator :: pos_integer()}}

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.

See Supervisor.

Link to this function

proxy_for(clock, clock_to_proxy_for)

View Source
@spec proxy_for(t(), clock_to_proxy_for :: pid() | nil) :: :ok

Sets a new proxy clock to clock_to_proxy_for.

Link to this function

start(options \\ [], gen_server_options \\ [])

View Source
@spec start([option()], GenServer.options()) :: GenServer.on_start()
Link to this function

start_link(options \\ [], gen_server_options \\ [])

View Source
@spec start_link([option()], GenServer.options()) :: GenServer.on_start()
Link to this function

subscribe(clock, pid \\ self())

View Source
@spec subscribe(t(), subscriber :: pid()) :: :ok

Subscribes pid for receiving ratio_message/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.

Link to this function

unsubscribe(clock, pid \\ self())

View Source
@spec unsubscribe(t(), subscriber :: pid()) :: :ok

Unsubscribes pid from receiving ratio_message/0 messages from the clock.

For unsubscription to take effect, unsubscribe/2 should be called the same amount of times as subscribe/2.