The next wake

Polling an empty set on a fixed tick wastes work. Every tick the worker runs the due-range, gets nothing back, and sleeps a fixed interval — then repeats, whether or not anything has changed. The shorter the tick the more round trips wasted on an empty set; the longer the tick the later a due job is noticed. A fixed poll cadence cannot be both responsive and cheap.

The waste is not a job that runs slowly; it is a worker spending round trips to learn nothing. On an idle set, every poll returns the same empty due head, and the interval between polls is latency added to whatever job lands next.

The set already holds the answer. Its head is the earliest-due job, and its score is when that job is due.

ZRANGE delayed_queue 0 0 WITHSCORES   # the earliest task and its scheduled time

This returns the earliest task and its scheduled time in one command. When the head's time is at or below now, a job is due and the worker sweeps it. When the head is still in the future, the worker sleeps until that time, or a bounded maximum interval, whichever is sooner — and wakes with a job due, having spent no round trips in between. The sleep is computed from the head's score: next_wake = head_score - now. This replaces a fixed tick with a head-driven wait: an empty set sleeps the maximum interval, a job far out sleeps until that job is due, a job due now does not sleep at all. The polling overhead collapses toward zero when the set is idle or the next job is far off.

EchoMQ does not sleep-and-recompute. It carries the next fire-time on a marker so a worker blocked on the marker wakes at exactly the right time. A worker parks on BZPOPMIN on the marker set (the blocking pop covered in R3.05). For a plain job the producer rings the marker with a score of zero — ZADD markerKey 0 "0" — which wakes the worker now, because a plain job is due now. For a delayed job the marker carries the fire-time instead. addDelayMarkerIfNeeded reads the head of the delayed set, recovers its real time, and writes that time as the marker's score.

-- addDelayMarkerIfNeeded.lua (included by addDelayedJob-6) — carry the next fire-time on the marker (real)
local nextTimestamp = getNextDelayedTimestamp(delayedKey)   -- reads the head, returns headScore / 0x1000
if nextTimestamp ~= nil then
  rcall("ZADD", markerKey, nextTimestamp, "1")              -- marker score = the next fire-time (ms)
end

getNextDelayedTimestamp reads the delayed head and returns nextTimestamp / 0x1000 — it divides out the twelve-bit shift the fire-time score carries, recovering the real millisecond. That millisecond is written as the marker's score with ZADD markerKey nextTimestamp "1". A worker blocked on the marker wakes when the marker's lowest score becomes available, which the runtime schedules for the next fire-time — so the worker wakes exactly when the next delayed job is due, not on a poll tick. The marker's member is "1" for a delayed wake, distinct from the "0" of the base marker that wakes a worker for a plain job now.

The whole wake is real code in echo/apps/echomq, in addDelayedJob-6.lua. getNextDelayedTimestamp reads the head and returns nextTimestamp / 0x1000, dividing out the shift to recover the millisecond. addDelayMarkerIfNeeded writes that millisecond as the marker score with rcall("ZADD", markerKey, nextTimestamp, "1"). The base marker for a plain due-now job is ZADD markerKey 0 "0" instead — the same marker, a different score, so the worker wakes now for a plain job and at the fire-time for a delayed one.

The recovery is the linchpin. Because the fire-time score is ms × 0x1000, the head's raw score is not a time a worker can sleep to; dividing by 0x1000 recovers the real millisecond, and that millisecond is what the marker carries. The shift that packs the within-millisecond discriminator is divided back out exactly, so the wake time is precise.

The blocking pop the worker parks on to wake at the next fire-time, the ZADD that writes that time as the marker's score, the sorted set behind both, and the queue protocol EchoMQ ports.