From 8dab08b85d1503457f75773b618934a958473c9d Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 10:22:10 +0800 Subject: [PATCH] :memo: clarify async state alias provenance --- docs/api/async-logger-state-type.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api/async-logger-state-type.md b/docs/api/async-logger-state-type.md index 3f91f4b..a8e25c5 100644 --- a/docs/api/async-logger-state-type.md +++ b/docs/api/async-logger-state-type.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `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. +- The type itself does not distinguish live logger snapshots from hand-built ones; callers must track whether a given `AsyncLoggerState` value came from `AsyncLogger::state()` or from manual construction. - When a live snapshot is taken after worker failure, `has_failed=true`, a retained `last_error`, and non-zero `pending_count` may legitimately coexist until later cleanup or restart. ### How to Use @@ -72,6 +73,8 @@ e.g.: - Because this is just a data shape, manual construction can represent combinations that do not come from a live logger at one exact instant. +- Receiving an `AsyncLoggerState` value alone does not prove it came from one current logger read rather than from a synthetic constructor path. + - This type does not imply cleanup semantics by itself; values only report the supplied or captured fields and do not drain backlog or clear recorded failure state. ### Notes