Periodical (Periodical v0.2.0)

Copy Markdown View Source

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

schedule_id()

@type schedule_id() :: pos_integer()

A schedule identifier local to one scheduler-process lifetime.

schedule_name()

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

A unique optional schedule name.

schedule_reference()

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

A schedule identifier or unique name.

Functions

cancel(reference)

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

Cancels a schedule and any pending or running local occurrences.

drain(timeout_ms \\ shutdown_timeout_ms())

@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(recurrence, module, function, args \\ [], options \\ [])

@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(datetime, module, function, args \\ [], options \\ [])

@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(reference)

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

Pauses future and pending occurrences without terminating an active callback.

resume(reference)

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

Resumes a paused schedule from the current explicit clock instant.

stats()

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

Returns bounded count-only scheduler utilization.