basic_meta

The Basic-engine queue-meta lifecycle (basic.ex init / put_meta / check_meta / refresh / shutdown), shared by the in-memory and Postgres engines — both are Basic-identical here. A Smart-style engine substitutes its own implementations in its Engine record; this module is that extension point, not public API.

Divergence (parity §9): put_meta write-through persists the signalled component (limit or paused, each independently) to the peer/cell persistent_term overlay, and init_queue merges it back — so a runtime pause/scale survives a producer crash-restart, where Elixir’s Basic engine loses it (only Pro’s Smart engine persists producer meta). The components are persisted separately so a Scale arriving mid-drain never captures shutdown_meta’s transient pause. The cell’s rare-write constraint holds: writes happen only on pause/resume/scale signals, reads only at producer init and on those same signals.

Values

check_meta

</>

pub fn check_meta(
  meta: engine.QueueMeta,
  running: List(Int),
) -> engine.QueueState

Project the meta + executing job ids into the Oban.queue_state shape (basic.ex check_meta).

clear_overlay

</>

pub fn clear_overlay(
  instance_name instance_name: String,
  queue queue: String,
) -> Nil

Drop the persisted overlay so an explicitly (re)started queue gets fresh options — only crash-restarts inherit. Cleared by the midwife on start_queue/stop_queue signals and by mule.start for every configured queue (the overlay is VM-global, so without the boot-time clear a paused queue would stay paused across a whole instance stop/start); tests use it for hygiene.

fetch_jobs

</>

pub fn fetch_jobs(
  claim claim: fn(String, Int, String) -> Result(
    List(job.Job),
    engine.EngineError,
  ),
) -> fn(engine.QueueMeta, List(Int)) -> Result(
  #(engine.QueueMeta, List(job.Job)),
  engine.EngineError,
)

Build the meta-shaped fetch_jobs from an engine’s raw claim function (queue, demand, node). Mirrors basic.ex’s three clauses: paused and at-limit metas claim nothing without touching storage; otherwise the demand is limit - length(running).

init_queue

</>

pub fn init_queue(
  queue_init: engine.QueueInit,
) -> Result(engine.QueueMeta, engine.EngineError)

Build a producer’s starting meta (basic.ex init): validate the limit (the validate_meta_opt analog), default the refresh interval to 30s, stamp started_at/updated_at — then merge the persisted pause/scale overlay so a crash-restarted producer resumes with the limits it was last signalled to.

put_meta

</>

pub fn put_meta(
  meta: engine.QueueMeta,
  update: engine.MetaUpdate,
) -> engine.QueueMeta

Apply one signal-driven update (basic.ex put_meta is a bare Map.put) and persist ONLY the signalled component to the overlay (divergence note in the module doc): a Scale during a drain must not persist shutdown_meta’s transient pause, and a Pause must not pin the limit.

refresh

</>

pub fn refresh(meta: engine.QueueMeta) -> engine.QueueMeta

Stamp the meta as still alive (basic.ex refresh). Not persisted — the overlay carries only the signal-mutable keys, keeping cell writes rare.

shutdown_meta

</>

pub fn shutdown_meta(meta: engine.QueueMeta) -> engine.QueueMeta

Pause and mark the shutdown start (basic.ex shutdown). The pause is NOT persisted: a restarted queue must not inherit its predecessor’s drain state.