An embedded background job engine supporting persistent and volatile jobs. For persistent jobs, the append-only Store-v2 journal is authoritative and ETS indexes are disposable projections rebuilt during recovery. Volatile jobs use the same state machine and execution paths but exist only in RAM/ETS, never enter persistent storage, and disappear when the Engine's in-memory state is lost.
Start an Engine explicitly; application startup only validates configuration and starts an empty supervisor.
Tay supports selective-durability insertion, supervised multi-queue execution, scheduling, retries, revision-checked cancellation and manual retry, volatile queue controls, drain, and explicit fresh-generation stop/restart. Callback effects are at-least-once, not exactly-once. Cancellation durably fences future persistent outcomes before best-effort termination; volatile cancellation is enforced only by the current in-memory state. Neither can reverse external effects.
Physical framing validity is separate from Event support and state replay. Torn, corrupt or unsupported history preserves evidence and refuses writable activation; there is no automatic repair or partial-state publication. Submitted calls with lost replies can have unknown outcomes and are not automatically retried.
By default, initialize storage explicitly with Tay.Storage.initialize/1, then
supervise Tay.child_spec/1. Callers may opt into initialize: :if_missing
to initialize only a genuinely missing root before normal recovery. It is
never a repair or recovery fallback. Engine options are not :tay_core
application environment keys.
:sync requires an explicitly validated Linux filesystem; explicit :write
is a development mode and is never described as durable.
Summary
Functions
Durably cancels an eligible job. Options are :name, :timeout, and
:expected_revision (the opaque token from a job view). If the revision option
is omitted, lookup captures it once. A timeout after submission is an unknown
outcome carrying that exact token; reconcile explicitly before a new command.
Durably cancels a recurring schedule.
Builds a Store-v2 replacement in the background while ordinary admission and
execution continue, then performs a fenced epoch switch. Uses the Engine's
bounded terminal retention by default. Administrative
terminal_retention: :infinity retains all jobs; {:minutes, n} or
{:hours, n} overrides the bounded duration. Zero removes every terminal job
while preserving all active jobs. No override bypasses the
publication fence, headroom, or exact validation.
Returns the registered name used by Tay APIs when :name is omitted.
Rejects new inserts/claims and waits for durable settlement and local task death. Queued jobs need not execute. Timeout leaves the Engine draining. A submitted transport timeout is an unknown control outcome, never implicit resumption.
Enqueues a portable task for a currently configured Protocol v1 listener.
Returns a bounded, cursor-paginated page of public job views.
Stops new claims for a configured queue after the accepted barrier. Volatile.
Returns configured queues and their current volatile runtime state.
Explicitly replaces the execution generation using fresh full recovery and the original validated startup configuration. Never replays a pending client RPC. Options: name, timeout, force. Change configuration via host-child replacement.
Resumes a configured queue; it does not undo an Engine drain.
Expedites retryable work or starts a new cycle for discarded work, retaining
its immutable definition. Uses the same options and one-capture revision
semantics as cancel/2. Completed/cancelled/available/executing jobs conflict.
Returns all durable recurring schedules.
Returns an efficient count snapshot for every public job state.
Drains then stops the execution generation, retaining its host-supervised
lifecycle coordinator. force: true explicitly skips drain and revokes active
execution; it is not a successful drain. Options: name, timeout, force.
Returns bounded physical metadata and decoded inspection previews for one storage segment.
Functions
Durably cancels an eligible job. Options are :name, :timeout, and
:expected_revision (the opaque token from a job view). If the revision option
is omitted, lookup captures it once. A timeout after submission is an unknown
outcome carrying that exact token; reconcile explicitly before a new command.
Durably cancels a recurring schedule.
Builds a Store-v2 replacement in the background while ordinary admission and
execution continue, then performs a fenced epoch switch. Uses the Engine's
bounded terminal retention by default. Administrative
terminal_retention: :infinity retains all jobs; {:minutes, n} or
{:hours, n} overrides the bounded duration. Zero removes every terminal job
while preserving all active jobs. No override bypasses the
publication fence, headroom, or exact validation.
Returns the registered name used by Tay APIs when :name is omitted.
Rejects new inserts/claims and waits for durable settlement and local task death. Queued jobs need not execute. Timeout leaves the Engine draining. A submitted transport timeout is an unknown control outcome, never implicit resumption.
Enqueues a portable task for a currently configured Protocol v1 listener.
task is a stable UTF-8 capability name, not an Elixir module name. args
must be a JSON-compatible string-keyed map. A supplied 128-bit lowercase
hexadecimal :id is also the idempotency key: repeat the exact submission
after an unknown outcome rather than allocating another ID.
Returns a bounded, cursor-paginated page of public job views.
Stops new claims for a configured queue after the accepted barrier. Volatile.
Returns configured queues and their current volatile runtime state.
Explicitly replaces the execution generation using fresh full recovery and the original validated startup configuration. Never replays a pending client RPC. Options: name, timeout, force. Change configuration via host-child replacement.
Resumes a configured queue; it does not undo an Engine drain.
Expedites retryable work or starts a new cycle for discarded work, retaining
its immutable definition. Uses the same options and one-capture revision
semantics as cancel/2. Completed/cancelled/available/executing jobs conflict.
Returns all durable recurring schedules.
Returns an efficient count snapshot for every public job state.
Drains then stops the execution generation, retaining its host-supervised
lifecycle coordinator. force: true explicitly skips drain and revokes active
execution; it is not a successful drain. Options: name, timeout, force.
Returns bounded physical metadata and decoded inspection previews for one storage segment.