From 96c4cc1f88ac766680e56dda96f03b73dcc8fc0e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 10:01:35 +0800 Subject: [PATCH] :memo: clarify async shutdown failure retention --- docs/api/async-logger-shutdown.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/api/async-logger-shutdown.md b/docs/api/async-logger-shutdown.md index cddf192..800eadc 100644 --- a/docs/api/async-logger-shutdown.md +++ b/docs/api/async-logger-shutdown.md @@ -36,11 +36,12 @@ Detailed rules explaining key parameters and behaviors - `clear=false` first waits for idle, then closes the logger. - In runtimes where shutdown clearing after idle is enabled, remaining backlog after `wait_idle()` triggers a fallback `close(clear=true)`. -- `clear=true` immediately closes and abandons pending records. +- `clear=true` immediately closes and abandons pending records, even if no worker was ever started for that logger. - In runtimes where shutdown waits for workers, the method then waits until `is_running()` becomes `false` before returning. - In the current backend split, native-worker runtimes enable both the post-`wait_idle()` clear fallback and the final wait-for-worker phase, while compatibility runtimes skip both extra steps. - That means a failure-short-circuited `wait_idle()` can still be followed by forced pending-to-dropped cleanup on native-worker runtimes, while compatibility runtimes close without that extra forced clear step. - In the current tested failure path, native-worker shutdown turns the leftover pending item into one more dropped record, while compatibility shutdown leaves that leftover closed-queue count in `pending_count()` instead. +- Shutdown itself does not clear retained worker failure state. If a previous `run()` already recorded `has_failed=true` and a non-empty `last_error()`, those diagnostics can remain visible after shutdown completes. - Because `clear=false` delegates to `wait_idle()` first, shutdown can also wait indefinitely when pending records exist but no worker is making progress and no failure flag is raised. ### How to Use @@ -75,6 +76,8 @@ e.g.: - After a worker failure, native-worker shutdown may convert the remaining backlog into dropped records, while compatibility shutdown can leave the pending counter reflecting that leftover closed queue state. - In the current direct regression coverage, that split appears as `pending_count() == 0` and `dropped_count()` increasing on native-worker runtimes, versus `pending_count() > 0` and no extra dropped cleanup on compatibility runtimes. +- Even after shutdown finishes with `is_closed=true`, callers can still observe retained `has_failed()` and `last_error()` from an earlier worker failure. + - 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. - If pending work exists but no worker was started, `shutdown(clear=false)` may never reach its later close step because it is still waiting inside `wait_idle()`.