Struct Cx

Source

pub struct Cx<Caps: SubsetOf<All> = FullCaps> { /* private fields */ }

Expand description

Capability context passed through all effectful operations.

Carries tracing identifiers (trace_id, decision_id, policy_id) that propagate through all context derivations (clone, restrict, scope, child). A value of 0 means “unset / not assigned”.

Implementations§

Source §

pub fn trace_id(&self) -> u64

The trace ID for this context (0 = unset).

Source

pub fn decision_id(&self) -> u64

The decision ID for this context (0 = unset).

Source

pub fn policy_id(&self) -> u64

The policy ID for this context (0 = unset).

Source

pub fn with_trace_context( self, trace_id: u64, decision_id: u64, policy_id: u64, ) -> Self

Set all three tracing identifiers at once.

Typically called once when a connection or request is initialized.

Source

pub fn with_decision_id(self, decision_id: u64) -> Self

Return a new context with only the decision_id changed.

Used when starting a new operation within the same trace.

Source

pub fn with_policy_id(self, policy_id: u64) -> Self

Return a new context with only the policy_id changed.

Source

pub fn scope_with_budget(&self, child: Budget) -> Self

Returns a view of this context with a tighter effective budget.

The effective budget is computed as self.budget.meet(child), so the child cannot loosen its parent’s constraints. Tracing IDs propagate unchanged.

Source

pub fn cleanup_scope(&self) -> Self

Returns a cleanup scope that uses Budget::MINIMAL.

Source

pub fn restrict<NewCaps>(&self) -> Cx<NewCaps>
where NewCaps: SubsetOf<All> + SubsetOf<Caps>,

Re-type this context to a narrower capability set.

This is zero-cost at runtime and shares cancellation state.

Source

pub fn is_cancel_requested(&self) -> bool

Source

pub fn wait_for_local_cancellation(&self) -> LocalCancellation<'_> ⓘ

Wait until local cancellation is observable at an unmasked boundary.

The returned future borrows this context’s existing cancellation node; it does not allocate a child context or attach a native runtime context. Dropping it removes any pending waker registration.

Source

pub fn wait_for_local_cancel_request(&self) -> LocalCancellation<'_> ⓘ

Wait until local cancellation has been requested, even while masked.

This is a raw wakeup primitive for cancellation-sensitive admission machinery that separately defines whether masked operation is legal. It does not transition cancellation state or inspect a native context.

Source

pub fn cancel(&self)

Request cancellation with the default reason (UserInterrupt).

Propagates to all child contexts per INV-CANCEL-PROPAGATES.

Source

pub fn cancel_with_reason(&self, reason: CancelReason)

Request cancellation with an explicit reason.

INV-CANCEL-IDEMPOTENT: the strongest reason wins; weaker reasons are ignored once a stronger one has been set.

INV-CANCEL-PROPAGATES: cancellation propagates to all descendants.

Source

pub fn cancel_state(&self) -> CancelState

Current state in the cancellation lifecycle.

Source

pub fn cancel_reason(&self) -> Option<CancelReason>

The strongest cancellation reason set so far, if any.

Source

pub fn transition_to_running(&self)

Transition from Created to Running.

Source

pub fn transition_to_finalizing(&self)

Transition from Cancelling to Finalizing.

Source

pub fn transition_to_completed(&self)

Transition to Completed (from Finalizing or Running).

Source

pub fn set_eprocess_oracle(&self, oracle: Arc<EProcessOracle>)

Attach an e-process oracle used by Self::checkpoint.

Source

pub fn clear_eprocess_oracle(&self)

Remove the currently attached e-process oracle.

Source

pub fn set_native_cx(&self, native_cx: NativeCx)

Attach a native asupersync context used by Self::checkpoint.

Source

pub fn attached_native_cx(&self) -> Option<NativeCx>

Return the attached native asupersync context, if one exists.

Source

pub fn native_spawn_budget(&self, native_cx: &NativeCx) -> NativeBudget

Compute the native runtime budget for a task spawned on native_cx.

FrankenSQLite deadlines are relative timeouts. They must be translated using the selected native context’s clock so production monotonic time and deterministic lab time stay in the same domain. Meeting the result with the native parent’s budget preserves every tighter parent bound, including the maximum scheduling priority.

Source

pub fn clear_native_cx(&self)

Remove the currently attached native asupersync context.

Source

pub fn mark_blocking_io_inline_safe(&self)

Mark this context as running on a dedicated engine OS thread where bounded blocking I/O may be issued inline (bd-bjm5d). Irreversible for the lifetime of this context; shared through Cx::clone and propagated to children by Cx::create_child.

Source

pub fn blocking_io_inline_safe(&self) -> bool

Whether bounded, page-sized positional I/O may be issued inline on the calling thread instead of via the blocking pool (bd-bjm5d).

Source

pub fn checkpoint(&self) -> Result<()>

Check for cancellation at a yield point.

Returns Ok(()) when not cancelled or when inside a masked section. When cancellation is observed, transitions state from CancelRequested to Cancelling.

Hot-path note: the cheap cancel_requested atomic load is consulted first, then mask_depth. Only if neither cheap signal proves we’re clear do we consult the e-process oracle and the native asupersync Cx::checkpoint(). Previously maybe_cancel_via_native_cx was evaluated unconditionally before the fast-path test — every checkpoint paid for the nested asupersync cancel machinery even when the cheap atomic said “not cancelled”. That showed up as 5.87% self-time on the 2026-04-23 post-bench-fix MT 8t capture (fsqlite-bench-fix-validation-194151).

Source

pub fn checkpoint_with(&self, msg: impl Into<String>) -> Result<()>

Check for cancellation and record a progress message.

Source

pub fn last_checkpoint_message(&self) -> Option<String>

Source

pub fn last_eprocess_decision(&self) -> Option<EProcessDecision>

Most recent e-process decision recorded during Self::checkpoint.

Source

pub fn last_eprocess_snapshot(&self) -> Option<EProcessSnapshot>

Snapshot portion of the most recent e-process decision.

Source

pub fn masked(&self) -> MaskGuard<'_>

Enter a masked section where checkpoint() returns Ok(()) even if cancellation is requested.

Returns a MaskGuard whose Drop restores the mask depth.

§Panics

Panics if nesting exceeds MAX_MASK_DEPTH (INV-MASK-BOUNDED).

Source

pub fn mask_depth(&self) -> u32

Current mask nesting depth.

Source

pub fn commit_section<R>( &self, poll_quota: u32, body: impl FnOnce(&CommitCtx) -> R, finalizer: impl FnOnce(), ) -> R

Execute a logically atomic commit section.

The section masks cancellation, enforces a poll quota bound, and guarantees the finalizer runs even on cancellation or panic.

Source

pub fn create_child(&self) -> Self

Create a child Cx that shares the parent’s budget but has independent cancellation state. Cancelling the parent propagates to this child. Tracing IDs propagate to the child.

Source

pub fn create_child_for_spawn(&self) -> Self

Create a child context that may be moved into a newly spawned task.

Cancellation lineage, budget, tracing metadata, e-process policy, and typed capabilities are inherited exactly as for Self::create_child. Task- and OS-thread-affine state is deliberately excluded: the child starts without an attached/fallback native context and without inline blocking-I/O permission. The spawned task must attach its own native context after it starts.

Source

pub fn create_child_with_local_cancel_relay(&self) -> (Self, LocalCancelRelay)

Create a child context plus narrowly scoped local cancellation authority.

The child inherits the same budget, tracing metadata, effect capabilities, and native I/O context as Self::create_child. The returned relay can only request local cancellation for that child subtree; it cannot access the context or cancel the inherited native context.

Source