Overview

Periodical is a bounded, in-memory scheduler for recurring and one-time MFA callbacks in one BEAM instance. It owns schedule calculation, timers, callback isolation, overlap and misfire policy, cancellation, and telemetry. It is not a durable queue. Across several instances it can, optionally, run each named schedule on just one of them.

Responsibilities

Non-responsibilities

Features

Installation

def deps do
  [
    {:periodical, "~> 0.2"}
  ]
end

Periodical is an OTP application because it owns timers, scheduler state, and supervised callbacks. Adding it as a normal runtime dependency starts that runtime automatically.

First schedule

Callbacks are exported MFA functions and receive a Periodical.Trigger before the supplied arguments:

defmodule MyApp.Cleanup do
  def run(%Periodical.Trigger{} = trigger, scope) do
    MyApp.Log.cleanup_started(trigger.schedule_id, scope)
    :ok
  end
end

{:ok, schedule_id} =
  Periodical.every("FREQ=MINUTELY;INTERVAL=5", MyApp.Cleanup, :run, [:expired_sessions])

See Usage for policies and configuration and Examples for focused patterns.

Durability boundary

Schedules and pending triggers disappear when the local application stops. Without a coordinator, multiple replicas each run their own schedules. For durable or retryable work, make the Periodical callback publish an idempotent job to the application-owned queue or messaging library.

Cluster-wide coordination

When several instances register the same schedule and it should run on only one of them per occurrence, configure a coordinator and name the schedule:

# mix.exs
{:periodical_redis, "~> 0.1"}   # Redis or KeyDB
# or
{:periodical_ecto, "~> 0.1"}    # PostgreSQL or MariaDB/MySQL

# config/runtime.exs
config :periodical, Periodical.Config,
  coordinator: {PeriodicalRedis, connection: MyApp.Redix}

Periodical.every("FREQ=MINUTELY;INTERVAL=5", MyApp.Cleanup, :run, [], name: :cleanup)

Each instance claims the run in a shared store; the winner holds a lease that covers this occurrence on every instance, whatever their clock skew or registration times, and the others skip it. Periodical itself gains no dependency. See Usage and Periodical.Coordinator.

License

Apache License 2.0; see LICENSE.

Name origin

“Periodical” is a direct functional name: something that occurs at recurring intervals. It fits the library's responsibility for calculating and triggering local recurring work.