Struct EventCtx 

pub struct EventCtx<'inv, B = ()> { /* private fields */ }

Per-event decision point handed to handle_persistent.

Generic over the handler’s Batch accumulator B (defaulting to () for handlers that never collect). See the module docs for the semantics of the three entry verbs.

Presence contract

A singleton subscriber is always on, and that presence is what licenses its ephemeral subscription: ephemeral events cannot be replayed, so only an always-present consumer may hear them. This ctx therefore has no pausing verb — no pause_until, no staged chain. Their absence is semantic, not an omission: a verb that suspends consumption would contradict the property that defines the mode.

use obix::{EventCtx, Handled};

fn pause_it<'inv>(ctx: EventCtx<'inv>) -> Handled<'inv> {
    // error[E0599]: no method named `pause_until` found for struct `EventCtx`
    //
    // A flow that pauses or stages is persistent-only by definition —
    // host it as a keyed subscriber; a single static key is legitimate.
    ctx.pause_until()
}

The control for the negative test above — same signature, with a verb a singleton ctx does have. If this stops compiling, the compile_fail above has started passing for the wrong reason:

use obix::{EventCtx, Handled};

fn resolve_it<'inv>(ctx: EventCtx<'inv>) -> Handled<'inv> {
    ctx.skip()
}

Implementations

impl<'inv, B> EventCtx<'inv, B>

pub fn skip(self) -> Handled<'inv>

This event is not for me — no transaction is opened, an open batch op is left untouched, and the checkpoint advances lazily (piggybacked on the next flush, or persisted on the configured checkpoint interval).

pub fn collect_with(self, f: impl FnOnce(&mut B)) -> Handled<'inv>

Contribute to the pending batch’s accumulator — a pure memory write: no transaction is opened and no statement is executed now. The runner hands the accumulated batch to the handler’s flush exactly once per batch landing, inside the transaction that commits the checkpoint.

Collected work shares fate with its neighbors and must tolerate whole-batch replay: on a failed flush the events replay and their items are re-collected.

For Vec and HashMap accumulators the collect sugar is usually more convenient.

pub async fn consume( self, ) -> Result<IsolatedOp<'inv>, Box<dyn Error + Send + Sync>>

where B: Default,

Land the pending batch first (its collected items and its checkpoint, at the last fully handled sequence), then hand back a fresh op: this event is its own atomic unit, sharing no fate with history — and none with the future either, since IsolatedOp only offers commit.

This is the failure-isolation fence: if this event’s work fails, only this event replays.

impl<'inv, T> EventCtx<'inv, Vec<T>>

pub fn collect(self, item: T) -> Handled<'inv>

collect_with sugar for Vec accumulators: append one item to the pending batch.

impl<'inv, K, V, S> EventCtx<'inv, HashMap<K, V, S>>

where K: Hash + Eq, S: BuildHasher,

pub fn collect(self, key: K, value: V) -> Handled<'inv>

collect_with sugar for HashMap accumulators: keyed last-write-wins insert. Persistent events arrive in ascending sequence, so within a batch this naturally keeps the newest item per key — the coalescing fold (N updates per key → 1 flushed entry).