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.
Summary
Types
A schedule identifier local to one scheduler-process lifetime.
A unique optional schedule name.
A schedule identifier or unique name.
Functions
Cancels a schedule and any pending or running local occurrences.
Stops new registration and waits up to timeout_ms for active callbacks.
Registers a recurring MFA callback from a recurrence struct or expression.
Registers a one-time MFA callback at an explicit future DateTime.
Pauses future and pending occurrences without terminating an active callback.
Resumes a paused schedule from the current explicit clock instant.
Returns bounded count-only scheduler utilization.
Types
@type schedule_id() :: pos_integer()
A schedule identifier local to one scheduler-process lifetime.
A unique optional schedule name.
@type schedule_reference() :: schedule_id() | schedule_name()
A schedule identifier or unique name.
Functions
@spec cancel(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
Cancels a schedule and any pending or running local occurrences.
@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.
@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.
@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.
@spec pause(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
Pauses future and pending occurrences without terminating an active callback.
@spec resume(schedule_reference()) :: :ok | {:error, Periodical.Error.t()}
Resumes a paused schedule from the current explicit clock instant.
@spec stats() :: Periodical.Stats.t()
Returns bounded count-only scheduler utilization.