📝 document async state constructors

2026-07-26 09:52:31 +00:00 · 2026-06-13 22:46:47 +08:00
parent 45a596cce1
commit e1ba2fb835
3 changed files with 190 additions and 0 deletions
@@ -0,0 +1,80 @@
+---
+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.
+key-word:
+    - async
+    - runtime
+    - state
+    - public
+---
+
+## Async-runtime-state-new
+
+Construct an `AsyncRuntimeState` snapshot from explicit runtime mode and worker-support values. This is the low-level constructor behind the public async runtime state shape used in diagnostics.
+
+### Interface
+
+```moonbit
+pub fn AsyncRuntimeState::new(
+  mode : AsyncRuntimeMode,
+  background_worker : Bool,
+) -> AsyncRuntimeState {
+```
+
+#### input
+
+- `mode : AsyncRuntimeMode` - Backend-specific async runtime mode such as `NativeWorker` or `Compatibility`.
+- `background_worker : Bool` - Whether native-style background-worker support is available.
+
+#### output
+
+- `AsyncRuntimeState` - Runtime state snapshot containing the supplied mode and worker-support flag.
+
+### Explanation
+
+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.
+- The constructed value matches the same public shape used by async runtime serializers.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Hand-built Runtime Snapshot
+
+When tests or adapters should construct a runtime state explicitly:
+```moonbit
+let runtime = AsyncRuntimeState::new(
+  AsyncRuntimeMode::Compatibility,
+  false,
+)
+```
+
+In this example, the runtime snapshot is built directly without probing the active backend.
+
+#### When Need Structured Runtime Diagnostics Input
+
+When code should prepare a runtime state value before serialization:
+```moonbit
+let runtime = AsyncRuntimeState::new(async_runtime_mode(), async_runtime_supports_background_worker())
+```
+In this example, callers still use the direct constructor while keeping the data source explicit.
+
+### Error Case
+
+e.g.:
+- This constructor itself does not have a normal failure mode; it only packages the provided values.
+
+- If callers want the current backend snapshot directly, `async_runtime_state()` is the simpler API.
+
+### 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.