diff --git a/docs/api/async-logger-state-new.md b/docs/api/async-logger-state-new.md new file mode 100644 index 0000000..2a82dc4 --- /dev/null +++ b/docs/api/async-logger-state-new.md @@ -0,0 +1,108 @@ +--- +name: async-logger-state-new +group: api +category: async +update-time: 20260613 +description: Construct an AsyncLoggerState snapshot from explicit runtime, queue, lifecycle, and failure values. +key-word: + - async + - logger + - state + - public +--- + +## Async-logger-state-new + +Construct an `AsyncLoggerState` snapshot from explicit runtime, queue, lifecycle, and failure values. This is the low-level constructor behind the public async logger state shape used in diagnostics. + +### Interface + +```moonbit +pub fn AsyncLoggerState::new( + runtime : AsyncRuntimeState, + pending_count : Int, + dropped_count : Int, + is_closed : Bool, + is_running : Bool, + has_failed : Bool, + last_error : String, + flush_policy : AsyncFlushPolicy, +) -> AsyncLoggerState { +``` + +#### input + +- `runtime : AsyncRuntimeState` - Embedded backend-level runtime snapshot. +- `pending_count : Int` - Current async queue backlog. +- `dropped_count : Int` - Current dropped-record count. +- `is_closed : Bool` - Whether the logger has been closed. +- `is_running : Bool` - Whether the logger worker loop is currently running. +- `has_failed : Bool` - Whether the logger has recorded a runtime failure state. +- `last_error : String` - Latest error text, or an empty string when no failure has been recorded. +- `flush_policy : AsyncFlushPolicy` - Active async flush policy for the logger. + +#### output + +- `AsyncLoggerState` - Full async logger snapshot containing the supplied runtime, queue, lifecycle, and failure values. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This constructor simply packages the supplied fields into one public snapshot value. +- It does not inspect a live logger instance by itself. +- `AsyncLogger::state()` is the higher-level API that reads these values from a concrete logger. +- The constructed value matches the same public shape used by async logger serializers. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Hand-built Async Logger Snapshot + +When tests or adapters should construct a full async logger state explicitly: +```moonbit +let state = AsyncLoggerState::new( + runtime=AsyncRuntimeState::new(AsyncRuntimeMode::Compatibility, false), + pending_count=0, + dropped_count=0, + is_closed=false, + is_running=true, + has_failed=false, + last_error="", + flush_policy=AsyncFlushPolicy::Never, +) +``` + +In this example, a complete async logger snapshot is assembled directly without querying a live logger instance. + +#### When Need Structured Diagnostics Input Before Serialization + +When code should prepare a typed logger state value for later export: +```moonbit +let state = AsyncLoggerState::new( + runtime=async_runtime_state(), + pending_count=logger.pending_count(), + dropped_count=logger.dropped_count(), + is_closed=logger.is_closed(), + is_running=logger.is_running(), + has_failed=logger.has_failed(), + last_error=logger.last_error(), + flush_policy=logger.flush_policy(), +) +``` + +In this example, callers still use the direct constructor while making each diagnostic input explicit. + +### Error Case + +e.g.: +- This constructor itself does not have a normal failure mode; it only packages the provided values. + +- If callers want a snapshot directly from one live logger instance, `AsyncLogger::state()` is the simpler API. + +### Notes + +1. Use this helper when code should construct an `AsyncLoggerState` value explicitly. + +2. Pair it with `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when the snapshot should be exported. diff --git a/docs/api/async-runtime-state-new.md b/docs/api/async-runtime-state-new.md new file mode 100644 index 0000000..d04cb60 --- /dev/null +++ b/docs/api/async-runtime-state-new.md @@ -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. diff --git a/docs/api/index.md b/docs/api/index.md index 861d7b0..e3179ec 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -264,6 +264,7 @@ BitLogger API navigation. ## Async lifecycle and state - [async-logger-state-type.md](./async-logger-state-type.md) +- [async-logger-state-new.md](./async-logger-state-new.md) - [async-logger-pending-count.md](./async-logger-pending-count.md) - [async-logger-dropped-count.md](./async-logger-dropped-count.md) - [async-logger-is-closed.md](./async-logger-is-closed.md) @@ -283,6 +284,7 @@ BitLogger API navigation. - [async-overflow-policy.md](./async-overflow-policy.md) - [async-flush-policy.md](./async-flush-policy.md) - [async-runtime-state-type.md](./async-runtime-state-type.md) +- [async-runtime-state-new.md](./async-runtime-state-new.md) - [async-runtime-mode.md](./async-runtime-mode.md) - [async-runtime-mode-label.md](./async-runtime-mode-label.md) - [async-runtime-supports-background-worker.md](./async-runtime-supports-background-worker.md)