Schedulers & repeatable jobs

A one-shot delayed job is a member in the :delayed sorted set scored by its fire-time. It runs once and is gone. A scheduler adds three things on top: a cadence — a rule for "when next," a cron expression or a fixed interval, evaluated to a timestamp; a registry — a separate sorted set, scored by the next run time, holding one entry per recurring schedule; and an upsert — registering a schedule that already exists rewrites its single entry rather than appending a duplicate.

The score is still a future timestamp, exactly as in the delayed queue. The new idea is that the entry is rewritten each cycle instead of consumed once. The interactive below runs a fixed scheduler — an every-15-minute interval and a daily cron — and shows the single registry entry being rewritten across three fires, not appended.

There are two ways to name when next. A cron expression (0 9 * * *) names a wall-clock calendar position — every day at 09:00 — and the next run is the next calendar slot at or after now. A fixed interval (every: 900000 ms) names a gap — every fifteen minutes — and the next run is the previous run plus the gap.

Both reduce to a single millisecond timestamp, which is the score the registry stores. The registry does not record whether the next run came from a calendar match or a gap addition; it stores a sorted set of next-run times. The first dive computes the next run each way over a fixed clock.

The registry is a sorted set scored by the next run time. The member is the scheduler's own key; the score is the millisecond at which it next fires. EchoMQ builds this key with EchoMQ.Keys.repeat/1, which returns "#{base}:repeat". The behaviour is a sorted set: ZADD repeatKey nextMillis customKey to record, ZSCORE repeatKey customKey to read the prior next-run time.

Per-scheduler options — the name, the cron pattern, the interval, the timezone — live in a separate hash at repeatKey .. ":" .. customKey, written with HMSET; the registry sorted set carries only the next-run times.

A service that boots re-registers all its schedules. A naive add would push a second entry for a schedule that already exists, and the recurring job would fire twice. The upsert prevents that. Before adding, the script probes the registry: local prevMillis = rcall("ZSCORE", repeatKey, customKey). If a prior entry exists, the script reconciles the stale delayed entry instead of adding a second scheduler.

The store itself is rcall("ZADD", repeatKey, nextMillis, customKey), and re-adding the same member rewrites its score rather than appending a row. One scheduler key, one registry entry, across any number of boots. The second dive runs two boots over the same scheduler key and counts the entries.

The registry holds only the next run, never a queue of future runs. When a job is produced, the next run time is computed from the cadence and the registry's single entry is rewritten with the new score. The next run is measured start-to-start — from this run's scheduled time plus the interval — not start-to-finish. Measuring from the finish would let a slow job push every later run later and drift the schedule; measuring start-to-start keeps the cadence anchored to the clock.

When the next run is known, EchoMQ also writes the wake marker — ZADD markerKey nextTimestamp "1" — so a blocked worker wakes at the next run rather than on a poll tick. The third dive compares start-to-start against start-to-finish and shows the drift.

Each dive takes one layer of the scheduler, in source order: naming the cadence that produces the next run, the upsert that keeps the registry at one entry per scheduler key, and the start-to-start rewrite that holds the cadence to the clock. Read them in order — the cadence first, the upsert second, the rewrite third.

The Redis commands behind the registry and its upsert — the store, the idempotence probe, the sorted set underneath — the cron cadence spec, and where the scheduler subsystem that runs them is taught.