Durable FIFO queue backed by the configured dgen backend.
Each dgen_server has its own queue keyed under Quid. Items are
ordered by versionstamps, guaranteeing strict FIFO across transactions.
Push and pop counts are tracked with atomic add operations for O(1) length.
Summary
Functions
Deletes the items returned by peek_k/3 and increments the pop counter.
Deletes the entire queue for the given Quid, including all items and counters.
Deletes a single dead-letter entry by its key.
Returns the number of entries currently in the dead-letter queue for Quid.
Returns the number of items currently in the queue (pushes minus pops).
Returns all entries in the dead-letter queue for Quid.
Reads up to K items from the queue without removing them.
Deletes all entries in the dead-letter queue for Quid.
Appends an entry to the dead-letter queue for Quid.
Pushes a list of items onto the queue atomically.
Moves a dead-letter entry back onto the main queue, resetting the attempt count to 0.
Overwrites the value at Key within an existing transaction.
Types
-type quid() :: tuple().
Functions
-spec consume_peeked(dgen_backend:tenant(), [{dgen_backend:key(), binary()}], quid()) -> ok.
Deletes the items returned by peek_k/3 and increments the pop counter.
Call this within the same transaction as peek_k/3 after the callback
succeeds to commit the consume.
-spec delete(dgen_backend:tenant(), quid()) -> ok.
Deletes the entire queue for the given Quid, including all items and counters.
-spec delete_dlq_entry(dgen_backend:tenant(), dgen_backend:key()) -> ok.
Deletes a single dead-letter entry by its key.
Key is the first element of a tuple returned by peek_dlq/2.
-spec dlq_length(dgen_backend:tenant(), quid()) -> non_neg_integer().
Returns the number of entries currently in the dead-letter queue for Quid.
-spec length(dgen_backend:tenant(), quid()) -> non_neg_integer().
Returns the number of items currently in the queue (pushes minus pops).
-spec peek_dlq(dgen_backend:tenant(), quid()) -> [{dgen_backend:key(), term(), non_neg_integer(), integer()}].
Returns all entries in the dead-letter queue for Quid.
Each entry is {Key, Envelope, AttemptCount, TimestampMs} where Key can be
passed to delete_dlq_entry/2 or requeue_dlq_entry/3.
-spec peek_k(dgen_backend:tenant(), pos_integer(), quid()) -> {ok, [{dgen_backend:key(), binary()}]} | {error, empty}.
Reads up to K items from the queue without removing them.
Returns {ok, [{RawKey, RawBin}]} where RawBin is the raw encoded value,
or {error, empty} when the queue is empty. The items remain in the queue
until consume_peeked/3 is called. On failure update_peeked/3 can overwrite a key
in-place within the same transaction to update the embedded attempt counter.
All three operations must be called within the same transaction so that the read, the callback invocation, and the delete-or-update are atomic.
-spec purge_dlq(dgen_backend:tenant(), quid()) -> ok.
Deletes all entries in the dead-letter queue for Quid.
-spec push_dlq(dgen_backend:tenant(), quid(), term(), non_neg_integer()) -> ok.
Appends an entry to the dead-letter queue for Quid.
Called when a message exceeds its dead-letter threshold. Stores the original envelope, attempt count, and a millisecond timestamp as a versionstamped entry under the DLQ subspace for the queue.
-spec push_k(dgen_backend:tenant(), quid(), [term()]) -> ok.
Pushes a list of items onto the queue atomically.
Each item is stored with a versionstamped key to ensure FIFO ordering.
-spec requeue_dlq_entry(dgen_backend:tenant(), quid(), dgen_backend:key()) -> ok | {error, not_found}.
Moves a dead-letter entry back onto the main queue, resetting the attempt count to 0.
Atomically reads the entry at Key, pushes its envelope back onto the main
queue with attempt count 0, and deletes the DLQ entry. Returns
{error, not_found} if the key no longer exists.
Key is the first element of a tuple returned by peek_dlq/2.
-spec update_peeked(dgen_backend:tenant(), dgen_backend:key(), term()) -> ok.
Overwrites the value at Key within an existing transaction.
Call this within the same transaction as peek_k/3 when the callback fails,
to update the embedded attempt counter before the transaction commits. The
updated message will be visible to the next consumer.