A Periodical.Coordinator that keeps claims in a database table through Ecto.
Every instance that shares a named Periodical schedule claims each run in one table, keyed on the schedule; the instance whose claim takes the row runs the callback. Leases are computed and compared by the database's clock, so the instances' own clock skew does not affect them.
Supported repositories: Ecto.Adapters.Postgres (PostgreSQL) and
Ecto.Adapters.MyXQL (MariaDB, MySQL).
Setup
Create the table with a migration:
defmodule MyApp.Repo.Migrations.AddPeriodicalClaims do
use Ecto.Migration
def up, do: PeriodicalEcto.Migration.up()
def down, do: PeriodicalEcto.Migration.down()
endand configure the coordinator:
config :periodical, Periodical.Config,
coordinator: {PeriodicalEcto, repo: MyApp.Repo}Options (the same for the migration where they apply):
:repo(required) — the Ecto repository.:table— the table name;"periodical_claims"by default.:prefix— the schema (PostgreSQL) or database (MariaDB/MySQL) the table lives in; the repository's default when omitted.
The repository must be started before Periodical fires its first
coordinated occurrence. A database that is unreachable makes claims fail
with an error, which Periodical's :coordinator_error policy handles.
How a claim decides
PostgreSQL decides in one statement: an INSERT … ON CONFLICT (key) DO UPDATE … WHERE expires_at <= now takes the row when it is free or its lease
has expired, and touches nothing otherwise; one affected row means the claim
won.
MariaDB/MySQL has no conditional upsert that reports the outcome reliably,
so a claim deletes the key's row if its lease has expired and then inserts
with INSERT IGNORE. Of concurrent claims, only one insert can succeed on
the primary key.
Expired rows
A row is replaced when its schedule is next claimed, so a table holds at
most one row per coordinated schedule. Rows of schedules that no longer
exist stay; prune/1 deletes every expired row, and can itself be a
Periodical schedule.
Summary
Functions
Claims the schedule's row for claim.ttl_ms.
Deletes every row whose lease has expired, returning how many.
Extends the lease to claim.ttl_ms from now while the row still holds this claim's token.
Functions
@spec claim(Periodical.Coordinator.Claim.t(), keyword()) :: :won | :lost | {:error, term()}
Claims the schedule's row for claim.ttl_ms.
Returns :won when this claim took the row, :lost when another claim's
lease is still running, and {:error, reason} when the database failed.
@spec prune(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}
Deletes every row whose lease has expired, returning how many.
Takes the same options as the coordinator:
PeriodicalEcto.prune(repo: MyApp.Repo)
#=> {:ok, 3}
@spec renew(Periodical.Coordinator.Claim.t(), keyword()) :: :ok | :lost | {:error, term()}
Extends the lease to claim.ttl_ms from now while the row still holds this claim's token.
Returns :lost when the lease expired or the row belongs to another claim.