From 5917256fda2f1dc594f0980f3e23fa9e91c3e9a4 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:48:44 +0800 Subject: [PATCH] :memo: refine async shutdown docs --- docs/api/async-logger-close.md | 9 +++++++-- docs/api/async-logger-shutdown.md | 5 +++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/api/async-logger-close.md b/docs/api/async-logger-close.md index 5853ab9..ca96bb7 100644 --- a/docs/api/async-logger-close.md +++ b/docs/api/async-logger-close.md @@ -2,8 +2,8 @@ name: async-logger-close group: api category: async -update-time: 20260512 -description: Close the async logger queue and optionally clear pending records immediately. +update-time: 20260614 +description: Close the async logger queue immediately and optionally convert current pending backlog into dropped records before queue closure. key-word: - async - logger @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - `clear=false` closes the queue without explicitly abandoning pending records in the helper itself. - `clear=true` counts pending records as dropped and resets `pending_count` to `0` before closing the queue. - This helper does not itself wait for the worker to finish. +- Because this is a low-level close primitive, it does not first run `wait_idle()` or apply the runtime-dependent fallback logic used by `shutdown()`. ### How to Use @@ -66,6 +67,8 @@ In this example, queued backlog is counted as dropped instead of waiting for fur e.g.: - If `clear=true`, pending records are intentionally discarded and contribute to `dropped_count()`. +- If `clear=false`, pending records may still exist after closure until worker drain or later cleanup resolves them. + - If callers need graceful waiting for drain completion, `shutdown()` is usually the better API. ### Notes @@ -73,3 +76,5 @@ e.g.: 1. This is a low-level lifecycle helper; prefer `shutdown()` for normal graceful teardown. 2. Use `clear=true` only when backlog loss is an acceptable shutdown tradeoff. + +3. Pair it with `pending_count()`, `dropped_count()`, or `state()` when you need to observe what happened to existing backlog after closure. diff --git a/docs/api/async-logger-shutdown.md b/docs/api/async-logger-shutdown.md index 2bdcb77..83a2b03 100644 --- a/docs/api/async-logger-shutdown.md +++ b/docs/api/async-logger-shutdown.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - 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. - 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. ### How to Use @@ -66,6 +67,8 @@ In this example, pending work is abandoned intentionally so shutdown can complet e.g.: - If `clear=true`, pending records are intentionally dropped rather than drained. +- If `wait_idle()` returns early because the worker failed, shutdown behavior after that point still depends on the active runtime's fallback and worker-wait rules. + - 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 callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state. @@ -77,3 +80,5 @@ e.g.: 2. Exact post-close waiting behavior depends on the active async runtime mode. 3. Choose `clear=true` only when loss of queued records is acceptable. + +4. Pair it with `state()` or focused counters when tests need to assert whether shutdown drained backlog or converted it into dropped records.