diff --git a/docs/api/async-runtime-mode.md b/docs/api/async-runtime-mode.md index 3b1ad9e..5dcf683 100644 --- a/docs/api/async-runtime-mode.md +++ b/docs/api/async-runtime-mode.md @@ -2,8 +2,8 @@ name: async-runtime-mode group: api category: async -update-time: 20260512 -description: Read the current async runtime mode and distinguish native worker behavior from compatibility behavior. +update-time: 20260614 +description: Read the current async runtime mode and distinguish native-worker behavior from compatibility behavior using the same mode contract exposed through async runtime snapshots. key-word: - async - runtime @@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors - `NativeWorker` is the expected mode on native-style backends, while `Compatibility` is the expected mode on targets without native background-worker semantics. - `async_runtime_mode_label(...)` converts the enum into a stable string value. - `async_runtime_supports_background_worker()` is a narrower boolean probe built on the same idea. +- `async_runtime_state()` packages this mode together with the current background-worker capability into one `AsyncRuntimeState` snapshot. +- In the current backend implementations, `NativeWorker` pairs with `background_worker=true` and `Compatibility` pairs with `background_worker=false`. - This API is intentionally small and useful for lightweight branching. - The mode result describes runtime behavior only; it should not be read as proof that every backend has been equally re-verified in the current release cycle. @@ -78,6 +80,8 @@ e.g.: 2. Use `async_runtime_state()` when you also want worker support packaged into one object. -3. This mode distinction is about runtime behavior, not whether `src-async` itself is expected to compile for the target. +3. Use `async_runtime_mode_label(...)` when the result should leave enum space and become stable text such as `native_worker` or `compatibility`. -4. See [target-verification.md](./target-verification.md) for the current verification status of individual targets. +4. This mode distinction is about runtime behavior, not whether `src-async` itself is expected to compile for the target. + +5. See [target-verification.md](./target-verification.md) for the current verification status of individual targets. diff --git a/docs/api/async-runtime-state-new.md b/docs/api/async-runtime-state-new.md index d04cb60..602e453 100644 --- a/docs/api/async-runtime-state-new.md +++ b/docs/api/async-runtime-state-new.md @@ -2,8 +2,8 @@ name: async-runtime-state-new group: api category: async -update-time: 20260613 -description: Construct an AsyncRuntimeState snapshot from explicit runtime mode and worker-support values. +update-time: 20260614 +description: Construct an AsyncRuntimeState snapshot from explicit runtime mode and worker-support values without probing or validating the live backend. key-word: - async - runtime @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - This constructor simply packages `mode` and `background_worker` into one public snapshot value. - It does not query the current backend automatically. - `async_runtime_state()` is the higher-level API that reads these values from the live runtime environment. +- It also does not validate whether the supplied pair matches the current backend contract. - The constructed value matches the same public shape used by async runtime serializers. ### How to Use @@ -73,8 +74,12 @@ e.g.: - If callers want the current backend snapshot directly, `async_runtime_state()` is the simpler API. +- If callers manually pair `NativeWorker` with `false` or `Compatibility` with `true`, the constructor still accepts that snapshot because it does not enforce backend consistency. + ### Notes 1. Use this helper when code should construct an `AsyncRuntimeState` value explicitly. 2. Pair it with `AsyncLoggerState::new(...)` when assembling a full async logger snapshot by hand. + +3. Prefer `async_runtime_state()` when the goal is to report the actual current backend pair rather than an arbitrary constructed snapshot. diff --git a/docs/api/async-runtime-state-type.md b/docs/api/async-runtime-state-type.md index f494ac9..42d5ca4 100644 --- a/docs/api/async-runtime-state-type.md +++ b/docs/api/async-runtime-state-type.md @@ -2,8 +2,8 @@ name: async-runtime-state-type group: api category: async -update-time: 20260613 -description: Public async runtime state alias used for backend capability snapshots and diagnostics. +update-time: 20260614 +description: Public async runtime state alias used for backend capability snapshots and diagnostics, pairing runtime mode with background-worker support. key-word: - async - runtime @@ -32,6 +32,7 @@ Detailed rules explaining key parameters and behaviors - This is a type alias, not a live runtime controller. - The current fields are `mode : AsyncRuntimeMode` and `background_worker : Bool`. - `async_runtime_state()` returns this type directly as an environment-level snapshot. +- `async_runtime_state()` currently builds that snapshot from `async_runtime_mode()` and `async_runtime_supports_background_worker()`. - `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` serialize the same snapshot shape for diagnostics. ### How to Use @@ -66,8 +67,12 @@ e.g.: - The snapshot is point-in-time diagnostic data; it should not be treated as proof that every target was re-verified in the current release cycle. +- Because this is just a data shape, manual construction can represent combinations that do not come from the current backend probe. + ### Notes 1. Use `async_runtime_state()` when you need a value of this type from the current backend. 2. Use `AsyncLoggerState` when logger-instance queue and lifecycle information is also required. + +3. Use `async_runtime_mode_label(...)` when the `mode` field should be rendered as stable text such as `native_worker` or `compatibility`. diff --git a/docs/api/async-runtime-state.md b/docs/api/async-runtime-state.md index 50a959f..ceadee7 100644 --- a/docs/api/async-runtime-state.md +++ b/docs/api/async-runtime-state.md @@ -2,8 +2,8 @@ name: async-runtime-state group: api category: async -update-time: 20260512 -description: Read the current backend-specific async runtime mode and worker capability. +update-time: 20260614 +description: Read the current backend-specific async runtime snapshot as the paired result of runtime mode and background-worker capability. key-word: - async - runtime @@ -35,6 +35,8 @@ Detailed rules explaining key parameters and behaviors - `mode` is derived from the active backend implementation. - `background_worker` tells callers whether native worker semantics are available. +- This helper is equivalent to `AsyncRuntimeState::new(async_runtime_mode(), async_runtime_supports_background_worker())`. +- In the current backend implementations, the resulting pair is `NativeWorker + true` or `Compatibility + false`. - `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` serialize this state. - This API is environment-scoped and does not depend on a particular `AsyncLogger` instance. @@ -75,3 +77,5 @@ e.g.: 1. Use this API for environment-level diagnostics. 2. Use `AsyncLogger::state()` for logger-instance diagnostics. + +3. Use `AsyncRuntimeState::new(...)` only when code or tests need to construct a manual snapshot instead of probing the current backend.