From 26de2e81d677646256abcea0af7138b05517276f Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 02:09:29 +0800 Subject: [PATCH] :memo: refine async state snapshot docs --- docs/api/async-logger-state-new.md | 1 + docs/api/async-logger-state-to-json.md | 8 ++++---- docs/api/async-logger-state-type.md | 1 + docs/api/async-logger-state.md | 7 ++++++- docs/api/stringify-async-logger-state.md | 7 +++++-- 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/api/async-logger-state-new.md b/docs/api/async-logger-state-new.md index 4f5fce1..b93ce67 100644 --- a/docs/api/async-logger-state-new.md +++ b/docs/api/async-logger-state-new.md @@ -55,6 +55,7 @@ Detailed rules explaining key parameters and behaviors - It also does not validate whether the supplied fields represent a combination that could come from one real logger instant. - The constructed value matches the same public shape used by async logger serializers. - Because `AsyncLoggerState` is only a data snapshot type, this constructor is mainly useful for tests, adapters, and synthetic diagnostics rather than ordinary logger inspection. +- Serialization helpers accept any `AsyncLoggerState` value, including hand-built ones from this constructor. ### How to Use diff --git a/docs/api/async-logger-state-to-json.md b/docs/api/async-logger-state-to-json.md index cac8a28..8de2ee3 100644 --- a/docs/api/async-logger-state-to-json.md +++ b/docs/api/async-logger-state-to-json.md @@ -13,7 +13,7 @@ key-word: ## Async-logger-state-to-json -Convert `AsyncLoggerState` into a `JsonValue`. This helper is the structured export path for async logger runtime snapshots when callers want machine-readable diagnostics instead of a plain string. +Convert `AsyncLoggerState` into a `JsonValue`. This helper is the structured export path for async logger runtime snapshots or manually constructed state values when callers want machine-readable diagnostics instead of a plain string. ### Interface @@ -23,7 +23,7 @@ pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.Json #### input -- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`. +- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()` or any manually constructed `AsyncLoggerState` value. #### output @@ -39,7 +39,7 @@ Detailed rules explaining key parameters and behaviors - The public helper returns the same internal JSON snapshot shape used by `stringify_async_logger_state(...)`, so both export paths stay aligned without duplicate field assembly logic. - This helper is suitable for health endpoints, diagnostics payloads, and custom serialization flows. - It shares the same stable field names used by `stringify_async_logger_state(...)`. -- The state must already have been captured before serialization. +- The state must already have been captured or constructed before serialization. ### How to Use @@ -79,5 +79,5 @@ e.g.: 3. Use this API when downstream code wants a JSON value rather than a ready-made string. -4. Pair it with `AsyncLogger::state()` to capture the snapshot first. +4. Pair it with `AsyncLogger::state()` when you want current logger data, or with `AsyncLoggerState::new(...)` when tests or adapters are exporting a synthetic snapshot. diff --git a/docs/api/async-logger-state-type.md b/docs/api/async-logger-state-type.md index 06d9c13..17b6726 100644 --- a/docs/api/async-logger-state-type.md +++ b/docs/api/async-logger-state-type.md @@ -34,6 +34,7 @@ Detailed rules explaining key parameters and behaviors - 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. - `AsyncLogger::state()` currently builds this snapshot from `async_runtime_state()` plus the logger's current counters, lifecycle flags, last error, and flush policy. +- When the value comes from `AsyncLogger::state()`, the fields are read one by one rather than through a transactional snapshot primitive. - `AsyncLoggerState::new(...)` can also construct this type manually, but manual construction is synthetic snapshot data and does not read one live logger instant by itself. ### How to Use diff --git a/docs/api/async-logger-state.md b/docs/api/async-logger-state.md index 5c9a63b..5d6d408 100644 --- a/docs/api/async-logger-state.md +++ b/docs/api/async-logger-state.md @@ -34,11 +34,12 @@ pub fn[S] AsyncLogger::state(self : AsyncLogger[S]) -> AsyncLoggerState {} Detailed rules explaining key parameters and behaviors - `AsyncLoggerState` includes `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`. -- `state()` returns a point-in-time snapshot rather than a live handle. +- `state()` returns a value snapshot rather than a live handle. - This helper is equivalent to `AsyncLoggerState::new(async_runtime_state(), self.pending_count(), self.dropped_count(), self.is_closed(), self.is_running(), self.has_failed(), self.last_error(), self.flush_policy())`. - `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` convert the snapshot to stable diagnostic output. - `runtime` embeds the result of `async_runtime_state()` so callers do not need to join separate helpers manually. - Because the snapshot is assembled field by field when `state()` is called, later logger changes require calling `state()` again rather than reusing an older `AsyncLoggerState` value as if it refreshed itself. +- That field-by-field assembly also means this helper is not an atomic freeze across all refs; under concurrent logger activity, neighboring fields can reflect slightly different instants. ### How to Use @@ -77,6 +78,8 @@ e.g.: - `flush_policy` reports the logger's configured async flush mode, not whether a flush has already happened. +- If concurrent logger activity is still changing counters or flags while `state()` runs, the returned value is still useful for diagnostics but should not be treated as a transactional snapshot. + ### Notes 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers. @@ -84,3 +87,5 @@ e.g.: 2. Use `pretty=true` when emitting logs for humans and the compact form for machine-oriented payloads. 3. Use `AsyncLoggerState::new(...)` only when tests or adapters need to construct a manual snapshot instead of reading one directly from a logger instance. + +4. If consumers need stronger cross-field consistency than a diagnostic snapshot, they should not assume `state()` provides an atomic read barrier. diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md index 0aa9742..5b77712 100644 --- a/docs/api/stringify-async-logger-state.md +++ b/docs/api/stringify-async-logger-state.md @@ -13,7 +13,7 @@ key-word: ## Stringify-async-logger-state -Serialize `AsyncLoggerState` into JSON text. This is the highest-level diagnostic export helper for async logger snapshots when callers want immediate text output. +Serialize `AsyncLoggerState` into JSON text. This is the highest-level diagnostic export helper for async logger snapshots or manually constructed state values when callers want immediate text output. ### Interface @@ -26,7 +26,7 @@ pub fn stringify_async_logger_state( #### input -- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`. +- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()` or any manually constructed `AsyncLoggerState` value. - `pretty : Bool` - Whether JSON should be pretty-printed. #### output @@ -43,6 +43,7 @@ Detailed rules explaining key parameters and behaviors - Internally it stringifies the same JSON snapshot shape returned by the public export helper, using `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`. - The compact form matches snapshots such as `{"runtime":{"mode":"native_worker","background_worker":true},"pending_count":0,...}`. - String output is convenient for logs, CLI output, and startup diagnostics. +- The serializer does not care whether the input came from a live logger read or a synthetic `AsyncLoggerState::new(...)` call. ### How to Use @@ -81,3 +82,5 @@ e.g.: 3. Use `async_logger_state_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. +4. Pair it with `AsyncLogger::state()` for current logger diagnostics, or with `AsyncLoggerState::new(...)` when exporting a manual snapshot built by tests or adapters. +