Struct AmbientState 

pub struct AmbientState { /* private fields */ }

A thread’s ambient state, captured and declared, ready to travel.

The field list is exhaustive on purpose; see the module documentation.

Implementations

impl AmbientState

pub fn capture(set: CaptureSet) -> Result<Self, CaptureError>

Capture the aspects set names from the calling thread.

Aspects outside set are Captured::NotCaptured, which leaves the target thread’s own value alone when the state is later applied – a different thing from an aspect that was captured and found empty.

Declared aspects are not touched here; attach them with with_declared.

Errors

Returns CaptureError, naming the aspect that failed. Any aspect captured before the failure is released rather than leaked, so a failed capture holds nothing.

pub fn with_declared(self, declared: Declared) -> Self

Attach declared aspects, replacing any already attached.

pub fn captured_set(&self) -> CaptureSet

What was actually collected.

Derived from the aspects themselves rather than recorded separately, so it cannot disagree with what the state holds.

pub const fn impersonation(&self) -> &Captured<ImpersonationToken>

The captured impersonation context.

pub const fn error_mode(&self) -> &Captured<ThreadErrorMode>

The captured thread error mode.

pub const fn transaction(&self) -> &Captured<TransactionContext>

The captured transaction.

pub const fn declared(&self) -> &Declared

The declared aspects.

pub fn with_applied<F, T>(&self, operation: F) -> Result<Applied<T>, ApplyError>

where F: FnOnce() -> T,

Run operation with this state installed on the calling thread.

Order

Guards are applied outermost-first and released in exact reverse, so the thread passes back through each intermediate state:

1. thread error mode – outermost, so hard-error suppression is already in force while everything else is being applied;
2. declared aspects (background mode, memory priority, redirection);
3. TxF transaction;
4. impersonation – innermost, because its window is the narrowest and its restoration is the one that must not be delayed.

Applying a subset stays expressible: an aspect that is Captured::NotCaptured or unspecified is skipped entirely, leaving the running thread’s own value alone.

Overriding rather than transplanting the error mode

This applies the error mode it captured. A consumer that wants to impose its own – forcing the dialog-suppressing bits on a shared worker, say – should leave CaptureSet::ERROR_MODE out of its capture set and wrap this call in its own ThreadErrorMode::apply guard, which then sits outermost, exactly where the order above puts it. Capturing and overriding would install the captured value inside the override.

Errors

Returns ApplyError if an aspect could not be installed, in which case operation did not run and every already-installed aspect is released first.

A failure to restore is different, and does not fail the call: the operation ran and its value is kept, with the failures reported through Applied::restore. Discarding a successful operation’s value because a priority could not be put back would lose more than it protects.

Panics

Panics if the impersonation context cannot be restored. That semantics is inherited from windows_impersonation_token_sys, not chosen here: returning a shared worker to a pool under an unknown identity is a process-wide security failure, which is a different order of hazard from the other aspects.

Trait Implementations

impl Debug for AmbientState

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

Formats the value using the given formatter.