Struct DeferralQueue 

pub struct DeferralQueue { /* private fields */ }

In-memory deferral queue for TriggerOutcome::Defer.

Items are keyed by their scheduled fire instant in a BTreeMap, so drain_due pops the next-due slot in O(log n). The queue is drained by a per-Uni background tick task spawned at DB build time; firing happens on the tokio runtime.

v1 limitations (in-memory only):

• Restart drops queued items. A persistent queue (system-table or WAL extension) is TODO(M11-persist).
• No transactional guarantee that a deferred item eventually fires — if the process exits before the scheduled instant, the item is lost.
• Per-item retry is capped at DEFER_MAX_ATTEMPTS to prevent runaway re-deferral loops.

Implementations

impl DeferralQueue

pub fn new() -> Arc<Self>

Build a fresh empty queue.

pub fn with_persistence(data_path: PathBuf) -> Arc<Self>

Build a queue with JSON-sidecar persistence rooted at <data_path>/_system/deferred_triggers.json.

On startup the queue’s load method walks the sidecar and re-binds each row to its TriggerPlugin by qname via the supplied uni_plugin::PluginRegistry. Items whose plugin can no longer be resolved are dropped with a warn.

Persists on every push and after every drain_due (FU-5). I/O failures degrade to debug logs — in-memory queue state remains authoritative for the running process.

pub fn sidecar_path(&self) -> Option<PathBuf>

Borrow the sidecar path, if persistence is enabled.

pub fn load_from_sidecar( self: &Arc<Self>, registry: &Arc<PluginRegistry>, ) -> usize

Replay persisted items from the sidecar, re-binding each row’s trigger qname against the registry. Should be called once after Uni::build finishes wiring triggers but before the queue tick task starts. Idempotent.

Returns the number of items reloaded.

pub fn pending(&self) -> usize

Approximate pending count — for diagnostics / tests.

pub fn tick(self: &Arc<Self>)

Tick the queue once: drain due items, fire each. Items that re-defer are re-enqueued until DEFER_MAX_ATTEMPTS. Async because plugin fire may block the runtime; we re-enter the tokio executor between items via spawn_blocking – but since most triggers are CPU-light, the inline call here is fine for v1.

Trait Implementations

impl Debug for DeferralQueue

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

Formats the value using the given formatter.

impl Default for DeferralQueue

fn default() -> DeferralQueue

Returns the “default value” for a type.