pub enum Captured<T> {
NotCaptured,
Absent,
Present(T),
}Expand description
What a capture produced for one aspect.
§Why this is not Option
Not captured and captured, and the thread had none are different facts with the same observable outcome, and only one of them is a decision.
Take impersonation. If the aspect was left out of the capture set, the worker
runs under the process identity. If it was captured and the calling thread
had no token, the worker also runs under the process identity. A caller
reading back an Option::None cannot tell which happened – so an omission
becomes indistinguishable from a deliberate statement about what the work
should run as, and nobody can later reconstruct which one it was.
The shape is uniform across aspects even where Absent is
unreachable, because a per-aspect shape would make every consumer remember
which aspects can be absent.
§Example
use windows_thread_ambient_sys::Captured;
let omitted: Captured<u32> = Captured::NotCaptured;
let asked_and_empty: Captured<u32> = Captured::Absent;
// Both yield nothing, which is what `Option` would collapse them to...
assert_eq!(omitted.present(), None);
assert_eq!(asked_and_empty.present(), None);
// ...but only one of them is a decision, and that stays recoverable.
assert!(!omitted.was_captured());
assert!(asked_and_empty.was_captured());Variants§
NotCaptured
The aspect was not in the capture set, so nothing was read and the target thread’s own value is left alone.
Absent
The aspect was captured, and the calling thread had no value for it.
Present(T)
The aspect was captured.