# `Periodical`
[🔗](https://github.com/joetjen/periodical/blob/main/lib/periodical.ex#L1)

Runs bounded local recurring and one-time schedules.

Schedule state is in memory and local to one BEAM instance. Periodical does
not provide durable triggering or retries. A callback that requires durable
execution should explicitly publish to a durable queue at its
application-owned boundary.

Every instance that registers a schedule runs it, unless a
`Periodical.Coordinator` is configured: then the instances sharing a named
schedule claim each run and only the winner executes it.

# `schedule_id`

```elixir
@type schedule_id() :: pos_integer()
```

A schedule identifier local to one scheduler-process lifetime.

# `schedule_name`

```elixir
@type schedule_name() :: atom() | tuple()
```

A unique optional schedule name.

# `schedule_reference`

```elixir
@type schedule_reference() :: schedule_id() | schedule_name()
```

A schedule identifier or unique name.

# `cancel`

```elixir
@spec cancel(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
```

Cancels a schedule and any pending or running local occurrences.

# `drain`

```elixir
@spec drain(pos_integer()) :: :ok | {:error, Periodical.Error.t()}
```

Stops new registration and waits up to `timeout_ms` for active callbacks.

Pending occurrences and registered schedules are not dispatched after drain
begins. Periodical keeps them only in memory, so they are discarded when the
owning application subsequently stops.

# `every`

```elixir
@spec every(
  Periodical.Recurrence.t() | String.t(),
  module(),
  atom(),
  list(),
  keyword()
) ::
  {:ok, schedule_id()} | {:error, Periodical.Error.t()}
```

Registers a recurring MFA callback from a recurrence struct or expression.

# `once`

```elixir
@spec once(DateTime.t(), module(), atom(), list(), keyword()) ::
  {:ok, schedule_id()} | {:error, Periodical.Error.t()}
```

Registers a one-time MFA callback at an explicit future DateTime.

# `pause`

```elixir
@spec pause(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
```

Pauses future and pending occurrences without terminating an active callback.

# `resume`

```elixir
@spec resume(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
```

Resumes a paused schedule from the current explicit clock instant.

# `stats`

```elixir
@spec stats() :: Periodical.Stats.t()
```

Returns bounded count-only scheduler utilization.

---

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