PeriodicalEcto (PeriodicalEcto v0.1.0)

Copy Markdown View Source

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()
end

and 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

claim(claim, options)

@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.

prune(options)

@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}

renew(claim, options)

@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.