# `Membrane.Clock`
[🔗](https://github.com/membraneframework/membrane-core/blob/v1.3.0/lib/membrane/clock.ex#L1)

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 `t: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 `t:ratio/0` of its time to the reference
time. The reference time can be configured with `:time_provider` option. The ratio
is broadcasted (see `t: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
`t: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`.

# `option`

```elixir
@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.

# `ratio`

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

Ratio of the Clock time to the reference time.

# `ratio_message`

```elixir
@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.

# `t`

```elixir
@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 `t: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 `t:ratio/0` of its time to the reference
time. The reference time can be configured with `:time_provider` option. The ratio
is broadcasted (see `t: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
`t: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`.

# `update_message`

```elixir
@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.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `proxy_for`

```elixir
@spec proxy_for(t(), clock_to_proxy_for :: pid() | nil) :: :ok
```

Sets a new proxy clock to `clock_to_proxy_for`.

# `start`

```elixir
@spec start([option()], GenServer.options()) :: GenServer.on_start()
```

# `start_link`

```elixir
@spec start_link([option()], GenServer.options()) :: GenServer.on_start()
```

# `subscribe`

```elixir
@spec subscribe(t(), subscriber :: pid()) :: :ok
```

Subscribes `pid` for receiving `t: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`.

# `unsubscribe`

```elixir
@spec unsubscribe(t(), subscriber :: pid()) :: :ok
```

Unsubscribes `pid` from receiving `t: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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*