Struct WaitContext
A 16-byte immutable value type that bundles a monotonic deadline with cooperative cancellation, passed by reference to all blocking synchronization primitives.
public readonly struct WaitContext- Inherited Members
Remarks
default(WaitContext) is already expired (fail-safe) — the deadline is expired and
any lock primitive will return false immediately.
For unbounded wait (infinite deadline, no cancellation), use ref Unsafe.NullRef<WaitContext>()
instead of constructing a WaitContext.
Fields
Deadline
Absolute monotonic deadline via GetTimestamp().
default = Zero (already expired).
Infinite = no timeout.
public readonly Deadline DeadlineField Value
Token
Cooperative cancellation token from session or application layer.
default = None (never cancelled).
public readonly CancellationToken TokenField Value
Properties
IsUnbounded
True if this WaitContext has an infinite deadline and no cancellation token. Such a context will never trigger ShouldStop on its own.
public bool IsUnbounded { get; }Property Value
Null
Returns a null reference to WaitContext for infinite wait scenarios.
Use this instead of Unsafe.NullRef<WaitContext>() for cleaner call sites.
public static ref WaitContext Null { get; }Property Value
Examples
// Instead of this (cluttered):
lock.EnterExclusiveAccess(ref Unsafe.NullRef<WaitContext>());
// Use this (clean):
lock.EnterExclusiveAccess(ref WaitContext.Null);Remaining
Remaining time until deadline, or InfiniteTimeSpan if infinite. Delegates to Remaining.
public TimeSpan Remaining { get; }Property Value
ShouldStop
True if the wait should stop: deadline expired OR cancellation requested. Called once per spin iteration in lock primitives.
public bool ShouldStop { get; }Property Value
Remarks
Cost per call: ~10-25ns for deadline check (one Stopwatch.GetTimestamp())
plus ~0-1 volatile read for cancellation (short-circuits for None).
Lock primitives check Unsafe.IsNullRef(ref ctx) once at entry and skip
this property entirely when NullRef is passed — the fastest possible spin path.
Methods
FromDeadline(Deadline)
Wrap an existing Deadline (no cancellation).
public static WaitContext FromDeadline(Deadline deadline)Parameters
deadlineDeadlineThe deadline to use.
Returns
FromTimeout(TimeSpan)
Create from relative timeout (no cancellation).
public static WaitContext FromTimeout(TimeSpan timeout)Parameters
timeoutTimeSpanRelative duration. Use InfiniteTimeSpan for no timeout. Zero or negative values produce an already-expired context.
Returns
FromTimeout(TimeSpan, CancellationToken)
Create from relative timeout + cancellation token.
public static WaitContext FromTimeout(TimeSpan timeout, CancellationToken token)Parameters
timeoutTimeSpanRelative duration. Use InfiniteTimeSpan for no timeout.
tokenCancellationTokenCancellation token from session or application layer.
Returns
FromToken(CancellationToken)
Create with cancellation only (infinite deadline).
public static WaitContext FromToken(CancellationToken token)Parameters
tokenCancellationTokenCancellation token from session or application layer.
Returns
FromUnitOfWorkContext(ref UnitOfWorkContext)
Create from an existing UnitOfWorkContext (reads embedded WaitContext).
public static WaitContext FromUnitOfWorkContext(ref UnitOfWorkContext ctx)Parameters
ctxUnitOfWorkContextThe execution context containing the embedded WaitContext.
Returns
ToString()
public override string ToString()