# `Rheo.Clock.Frozen`
[🔗](https://github.com/thanos/rheo/blob/v1.0.0/lib/rheo/clock/frozen.ex#L1)

Controllable clock for tests and demos.

Configure `config :rheo, clock: Rheo.Clock.Frozen` then call `set/1` or
`advance/1` to simulate lease expiry without sleeping.

# `advance`

```elixir
@spec advance(non_neg_integer()) :: :ok
```

Advances the frozen clock by `ms` milliseconds.

## Examples

    iex> Rheo.Clock.Frozen.set(~U[2026-01-15 12:00:00.000Z])
    :ok
    iex> Rheo.Clock.Frozen.advance(1_500)
    :ok
    iex> Rheo.Clock.Frozen.utc_now()
    ~U[2026-01-15 12:00:01.500Z]

## Arguments

  * `ms` — non-negative integer milliseconds

## Returns

`:ok`

## Errors

Raises `FunctionClauseError` when `ms` is negative or not an integer.

# `reset`

```elixir
@spec reset() :: :ok
```

Clears the frozen value so `utc_now/0` uses the wall clock again.

## Examples

    iex> Rheo.Clock.Frozen.set(~U[2026-01-15 12:00:00.000Z])
    :ok
    iex> Rheo.Clock.Frozen.reset()
    :ok
    iex> match?(%DateTime{}, Rheo.Clock.Frozen.utc_now())
    true

## Returns

`:ok`

# `set`

```elixir
@spec set(DateTime.t()) :: :ok
```

Sets the frozen clock to a specific `DateTime`.

## Examples

    iex> Rheo.Clock.Frozen.set(~U[2026-06-01 08:30:00.000Z])
    :ok
    iex> Rheo.Clock.Frozen.utc_now()
    ~U[2026-06-01 08:30:00.000Z]

## Arguments

  * `dt` — UTC `DateTime.t()`; truncated to milliseconds

## Returns

`:ok`

# `utc_now`

```elixir
@spec utc_now() :: DateTime.t()
```

Returns the frozen clock's current time.

When unset, falls back to the real wall clock.

## Examples

    iex> Rheo.Clock.Frozen.set(~U[2026-01-15 12:00:00.000Z])
    :ok
    iex> Rheo.Clock.Frozen.utc_now()
    ~U[2026-01-15 12:00:00.000Z]

## Returns

A `DateTime.t()`.

---

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