diff --git a/docs/api/async-logger-state-type.md b/docs/api/async-logger-state-type.md new file mode 100644 index 0000000..d6d42d5 --- /dev/null +++ b/docs/api/async-logger-state-type.md @@ -0,0 +1,73 @@ +--- +name: async-logger-state-type +group: api +category: async +update-time: 20260613 +description: Public async logger state alias used for queue, lifecycle, and runtime diagnostics. +key-word: + - async + - logger + - state + - public +--- + +## Async-logger-state-type + +`AsyncLoggerState` is the public snapshot type used to describe an async logger's runtime status. It is a direct alias to the async logger state model returned by `AsyncLogger::state()` and used by async diagnostics serializers. + +### Interface + +```moonbit +pub type AsyncLoggerState = @utils.AsyncLoggerState +``` + +#### output + +- `AsyncLoggerState` - Public async logger snapshot containing `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a live logger handle. +- The `runtime` field embeds an `AsyncRuntimeState` snapshot. +- The remaining fields capture queue counts, lifecycle status, failure state, last error text, and active flush policy. +- `AsyncLogger::state()` returns this type directly, while `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` export the same data shape for diagnostics. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Snapshot For Async Diagnostics + +When application code should inspect async logger state before deciding how to report it: +```moonbit +let state : AsyncLoggerState = logger.state() +``` + +In this example, queue, lifecycle, and runtime information stay available as structured data. + +#### When Need To Branch On Failure Or Backlog + +When code should react to the current async logger condition: +```moonbit +let state = logger.state() +if state.has_failed || state.pending_count > 0 { + println(stringify_async_logger_state(state, pretty=true)) +} +``` + +In this example, the typed snapshot supports both logic and later export. + +### Error Case + +e.g.: +- `AsyncLoggerState` itself does not have a runtime failure mode. + +- `last_error` may be an empty string when no failure has occurred, which is normal and not a special error condition by itself. + +### Notes + +1. Use `AsyncLogger::state()` when you need a value of this type from one logger instance. + +2. Use `AsyncRuntimeState` when only backend-level capability information is needed and logger-instance state is unnecessary. diff --git a/docs/api/async-runtime-state-type.md b/docs/api/async-runtime-state-type.md new file mode 100644 index 0000000..f494ac9 --- /dev/null +++ b/docs/api/async-runtime-state-type.md @@ -0,0 +1,73 @@ +--- +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. +key-word: + - async + - runtime + - state + - public +--- + +## Async-runtime-state-type + +`AsyncRuntimeState` is the public snapshot type used to describe backend-level async runtime capability. It is a direct alias to the async runtime state model returned by `async_runtime_state()` and used by async diagnostics serializers. + +### Interface + +```moonbit +pub type AsyncRuntimeState = @utils.AsyncRuntimeState +``` + +#### output + +- `AsyncRuntimeState` - Public runtime snapshot containing `mode` and `background_worker`. + +### Explanation + +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_to_json(...)` and `stringify_async_runtime_state(...)` serialize the same snapshot shape for diagnostics. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Backend Capability Snapshot + +When startup or diagnostics code should keep the runtime state as structured data: +```moonbit +let runtime : AsyncRuntimeState = async_runtime_state() +``` + +In this example, the backend capability snapshot stays available as a typed value instead of only as printed text. + +#### When Need To Read Runtime Mode And Worker Support Together + +When code should inspect both async mode and worker availability from one object: +```moonbit +let runtime = async_runtime_state() +if runtime.background_worker { + println(async_runtime_mode_label(runtime.mode)) +} +``` + +In this example, both fields are consumed from the same public snapshot type. + +### Error Case + +e.g.: +- `AsyncRuntimeState` itself does not have a runtime failure mode. + +- 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. + +### 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. diff --git a/docs/api/index.md b/docs/api/index.md index bea3454..0fb6ba3 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -190,6 +190,7 @@ BitLogger API navigation. ## Async lifecycle and state +- [async-logger-state-type.md](./async-logger-state-type.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) @@ -208,6 +209,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-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)