From 674e949f96563c6459b36af9832e48b105fa8def Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 09:36:37 +0800 Subject: [PATCH] :memo: clarify library async unwrap preserved failure state --- docs/api/library-async-logger-to-async-logger.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api/library-async-logger-to-async-logger.md b/docs/api/library-async-logger-to-async-logger.md index 26657bf..65854d6 100644 --- a/docs/api/library-async-logger-to-async-logger.md +++ b/docs/api/library-async-logger-to-async-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - This is the step required for helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, `last_error()`, or broader composition methods that are intentionally hidden by `LibraryAsyncLogger[S]`. - It is also the step that exposes the real post-run or post-shutdown state after facade-level lifecycle calls, because those calls delegated to this same wrapped logger all along. - That includes failure/backlog combinations and runtime-dependent shutdown results exactly as they accumulated behind the facade. +- That also means the unwrapped logger can already be both `is_closed=true` and `has_failed=true`, with the same retained `last_error()` string and the same runtime-dependent pending-versus-dropped cleanup outcome that delegated shutdown left behind. - If the wrapped sink type has richer helper APIs, unwrapping also restores access to that same sink helper surface through the original `AsyncLogger[S]` value. - When the wrapped sink is `RuntimeSink`, that same unwrap also preserves queued runtime state and file-backed helper behavior exactly as they existed behind the facade, including runtime file state snapshots and file control methods. @@ -78,6 +79,8 @@ e.g.: - Unwrapping does not convert facade lifecycle history into a simplified snapshot; any retained `last_error()`, pending backlog, dropped counts, or sink runtime details stay exactly as they were on the wrapped logger. +- If facade-level `run()` or `shutdown()` already ended in a failure-retaining state, unwrapping can therefore expose combinations such as `is_closed=true` together with `has_failed=true`, the same `last_error()`, and runtime-dependent leftover backlog or dropped-count cleanup. + - Recovering the full async logger also does not translate runtime sink helper state into a simpler snapshot; queue counters, file availability, file failure counters, and runtime file controls stay exactly as they were on the wrapped logger. ### Notes