Struct Dlq 

pub struct Dlq { /* private fields */ }

Available on crate feature dlq only.

Unified DLQ. Caller queues entries from any task; the orchestrator drains them off-runtime via the configured backends.

Clone is cheap (mpsc::Sender clone). The single-owner shutdown handle stays inside Arc<AsyncMutex<Option<...>>> so Dlq itself is Clone.

Implementations

impl Dlq

pub fn disabled() -> Self

Build a disabled DLQ. All send / try_send calls succeed as no-ops.

pub fn spawn( config: &DlqConfig, service_name: &str, _kafka_config: Option<&()>, shutdown: CancellationToken, ) -> Result<Self, DlqError>

Spawn the DLQ with whatever backends the config enables.

kafka_config is required if the config has kafka.enabled = true (or the mode demands Kafka). Pass None if the service has no Kafka transport – Kafka mode/enabled flags are honoured where possible and a clear Err(DlqError::NotConfigured) is returned if Kafka is required but unavailable.

Errors

Returns Err if any enabled backend fails to initialise.

pub fn is_enabled(&self) -> bool

Whether the DLQ is accepting entries.

pub fn mode(&self) -> DlqMode

Configured routing mode (informational).

pub fn pending(&self) -> usize

Approximate queue depth (drain may be mid-recv).

pub fn dropped(&self) -> u64

Total entries dropped due to overflow since spawn.

pub fn try_send(&self, entry: DlqEntry) -> Result<(), DlqError>

Sync-shaped queue submission. Returns immediately. On a full queue, returns Err(DlqError::QueueFull) and increments the drop counter – caller decides whether to log, escalate, or proceed.

Errors

QueueFull if the in-memory queue is full. Closed if the drain has exited.

pub async fn send(&self, entry: DlqEntry) -> Result<(), DlqError>

Async submission that awaits queue space.

Successful return means the entry is queued, NOT that it is durably written. Use Self::flush for that.

Errors

Closed if the drain has exited.

pub async fn send_batch(&self, entries: Vec<DlqEntry>) -> Result<(), DlqError>

Async batch submission. Each entry is queued individually; the drain decides how to coalesce.

Errors

Closed if the drain has exited mid-batch.

pub async fn flush(&self) -> Result<(), DlqError>

Block until every entry queued before this call is durably written by the drain.

Errors

Closed if the drain has exited before this barrier was processed.

pub async fn shutdown(&self) -> Result<(), DlqError>

Initiate shutdown and await graceful drain exit.

Cancels the internal child token (drain observes the cancellation in its next select!, flushes its remaining batch, and exits), then awaits the drain task. This is the canonical “stop the DLQ and wait for it” call – the previous version only awaited the join and would hang forever unless the caller had separately cancelled the token passed to spawn.

Idempotent: safe to call from many clones; the join happens once. Subsequent calls observe an empty join slot and return Ok.

Errors

Returns Err(DlqError::Closed) if the drain task panicked.

Trait Implementations

impl Clone for Dlq

fn clone(&self) -> Dlq

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dlq

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.