From bbc9afbc474aa06e7979517b5f7bde09d0d51367 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 09:35:09 +0800 Subject: [PATCH] :memo: clarify library async shutdown failure retention --- docs/api/library-async-logger-shutdown.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api/library-async-logger-shutdown.md b/docs/api/library-async-logger-shutdown.md index 354cecc..d681151 100644 --- a/docs/api/library-async-logger-shutdown.md +++ b/docs/api/library-async-logger-shutdown.md @@ -44,6 +44,7 @@ Detailed rules explaining key parameters and behaviors - In runtimes where shutdown waits for workers, the method then waits until the worker is no longer running before returning. - After a worker-failure short-circuit, native-worker backends can still convert remaining backlog into dropped records, while compatibility backends skip that extra forced-clear step. - In the current direct facade coverage, the wrapped logger ends that path with `pending_count() == 0` and one more dropped item on native-worker runtimes, versus a still-nonzero pending count and no extra dropped cleanup on compatibility runtimes. +- Delegated shutdown also does not clear retained worker failure state by itself. If the wrapped logger had already recorded a worker error, later inspection through `to_async_logger()` can still show `has_failed=true` and the same `last_error()` string after shutdown completes. - The narrower library facade does not change any of these runtime-dependent shutdown rules; it only keeps the broader inspection helpers out of the direct public surface. - Inspecting the logger later through `to_async_logger()` reveals the same delegated shutdown result rather than a rebuilt or translated lifecycle snapshot. @@ -78,6 +79,8 @@ e.g.: - In compatibility-style runtimes without background-worker waiting, shutdown still closes the logger but may not perform the extra wait-for-worker phase described for native-worker runtimes. +- Even when delegated shutdown finishes with `is_closed=true`, callers can still observe retained `has_failed()` and `last_error()` on the unwrapped logger if the worker had already failed before shutdown cleanup completed. + - If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state. - If callers need to inspect `pending_count()`, `dropped_count()`, `is_running()`, or failure state during shutdown analysis, they must unwrap first with `to_async_logger()`.