Module flash 

Structs

AmbientScope

No-op per-test ambient gate off the sim path (time is already real). The #[kithara::test] macro emits ambient_scope(..) into sync and wasm test bodies (async-native bodies carry with_ambient per-poll instead), so the guard must exist (as a ZST) in the off-feature + wasm configs. Under flash this is the engine’s AmbientScope / ambient_scope. !Send for auto-trait parity with the engine guard (see FlashScope).

Duration

A Duration type to represent a span of time, typically used for system timeouts.

FlashScope

No-op real-time scope off the sim path (time is already real). !Send (PhantomData<*mut ()>) for auto-trait PARITY with the engine guard: a consumer compiling against the inert form must not become Send-legal code that fails to compile under flash.

FlashYield

Inert mirror of the engine-backed yield future. Never produced by the inert yield_now (off the sim path the real arm is always taken); present so the surface matches the flash control surface 1:1.

Instant

A measurement of a monotonically nondecreasing clock. Opaque and useful only with Duration.

RealIoScope

Off the sim path a real I/O operation needs no pacing (time is already real), so the scope is a ZST no-op. Under flash it is the engine’s RealIoScope: while held, the virtual clock may not outrun real time, so virtual watchdogs/timeouts cannot fire spuriously ahead of bytes still on the wire.

Enums

Yield

Cooperative yield future (see yield_now). Mirrors the flash enum; the Yield::Flash variant is never constructed off the sim path.

Functions

ambient_scope

Set the per-test ambient gate. Off the sim path this is a ZST no-op (time is already real); under flash it is the engine’s ambient_scope.

ambient_snapshot

Snapshot the per-test ambient gate for spawn propagation. Off the sim path the gate does not exist and no test is flash-eligible, so the snapshot is always false (the engine’s default outside a flash test).

dynamic

Off the sim path: a prod #[kithara::flash(bool)] async region is an identity passthrough (no per-poll re-assert needed when time is already real). Under flash this is the engine’s dynamic.

enter_dynamic

Off the sim path: a prod #[kithara::flash(bool)] sync region’s RAII guard is a ZST no-op (time is already real), so an annotated fn compiles away to its bare body. Under flash this is the engine’s enter_dynamic.

flash_real

Enter a real-time scope. Off the sim path this is a ZST no-op; under flash it puts the current thread on real time for the guard’s lifetime.

hang_dump

No engine to report without the flash feature (or on wasm).

log_hang_dump

No engine to report without the flash feature (or on wasm).

participate

Off the sim path: spawning needs no quiescence bracket, so participate is an identity passthrough (the real clock already advances on its own). Under flash this is the engine’s participate, which wraps the future so it counts in the engine’s active_async while running. The loc spawn-site identity (used by the engine’s hang dump) is unused off the sim path.

real_io

Bracket ONE real I/O operation. Off the sim path this is a ZST no-op; under flash it paces the virtual clock to real time while held.

reset

No virtual timeline or quiescence engine to reset off the sim path (the clock is real), so this is a no-op.

set_ambient_for_spawn

Restore a snapshotted ambient on a spawned child. Off the sim path this is the ZST no-op guard (see ambient_scope); under flash it re-establishes the engine’s per-test gate for the child’s lifetime.

virtual_now

Off-feature real alias for the rewriter’s virtual Instant::now (see virtual_sleep).

virtual_park_timeout

Off-feature real alias for the rewriter’s virtual park_timeout (see virtual_sleep).

virtual_sleep

Off the sim path the lexical test rewriter’s virtual_* targets alias the REAL primitives, so a rewritten test body behaves identically to its unrewritten form (the rewrite is a no-op when flash is off). The #[kithara::test] macro emits these into EVERY test body, so they must resolve in the off-feature + wasm configs.

virtual_timeout

Off-feature real alias for the rewriter’s virtual timeout (see virtual_sleep).

with_ambient

Off the sim path: ambient does not exist, so re-asserting it per poll is an identity passthrough. Under flash this is the engine’s with_ambient, which re-establishes the snapshotted ambient around every poll so a future (e.g. the async test body) keeps its flash-eligibility across .await thread-hops instead of relying on a one-shot guard set on the first poll.

yield_now

Cooperative async yield. Off the sim path this always takes the real arm — the same semantics the engine build uses outside a flash-eligible test: hand control back to the scheduler once, then resolve.

Type Aliases

FlashDynamic

Off the sim path a prod async #[kithara::flash(bool)] region needs no per-poll mode re-assert: the wrapper is the future itself. Under flash this is the engine’s per-poll dynamic-flash wrapper.

Participating

Off the sim path a spawned task needs no quiescence accounting, so the participant wrapper is the future itself. Under flash this is the engine’s gate wrapper counted in active_async.

WithAmbient

Off the sim path ambient does not exist, so there is nothing to re-assert per poll: the wrapper is the future itself. Under flash this is the engine’s per-poll ambient re-assert wrapper.