From f1250512eb10329ef4f26520c382c089a36b29a8 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 02:11:26 +0800 Subject: [PATCH] :memo: clarify async status helper docs --- docs/api/async-logger-has-failed.md | 3 +++ docs/api/async-logger-is-closed.md | 3 +++ docs/api/async-logger-is-running.md | 3 +++ docs/api/async-logger-last-error.md | 3 +++ 4 files changed, 12 insertions(+) diff --git a/docs/api/async-logger-has-failed.md b/docs/api/async-logger-has-failed.md index 0ff6f0b..9a04f7d 100644 --- a/docs/api/async-logger-has-failed.md +++ b/docs/api/async-logger-has-failed.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `run()` clears previous failure state at startup. - `run()` also clears the stored `last_error()` string at startup before drain work begins. - If the worker loop raises an error, the logger records that failure and exposes it through this flag. +- Once set by a failed run, the flag stays `true` until a later `run()` start resets it. - This helper is intentionally compact and should usually be paired with `last_error()` for details. - Failure state is about runtime drain execution, not whether records were dropped due to overflow policy. @@ -72,6 +73,8 @@ e.g.: - If `has_failed()` is `true`, callers should inspect `last_error()` or `state()` for more context. +- `close()` or `shutdown()` do not clear this flag by themselves; only a later `run()` start resets it. + ### Notes 1. This helper reports worker failure, not general queue stress. diff --git a/docs/api/async-logger-is-closed.md b/docs/api/async-logger-is-closed.md index 5fd4780..6cda9a9 100644 --- a/docs/api/async-logger-is-closed.md +++ b/docs/api/async-logger-is-closed.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `close(...)` sets the closed state immediately. - `shutdown(...)` also results in a closed logger by the end of its lifecycle flow. - A closed logger should no longer be treated as a normal active enqueue target. +- This helper is only a direct read of the current `is_closed` ref; it does not wait for drain completion or clear any other state. - This helper reflects lifecycle state only and does not indicate whether the worker is still draining. - Exact post-close logging behavior is runtime-dependent, so `is_closed()` should be read as a lifecycle signal rather than a full enqueue-policy contract. @@ -73,6 +74,8 @@ e.g.: - If callers need to know whether closure also prevented later log attempts on the current backend, they must interpret this together with the active runtime behavior rather than this flag alone. +- Closing a logger does not by itself reset `has_failed()` or `last_error()`. + ### Notes 1. Closed state and running state are related but not identical. diff --git a/docs/api/async-logger-is-running.md b/docs/api/async-logger-is-running.md index 17cfb18..b406f32 100644 --- a/docs/api/async-logger-is-running.md +++ b/docs/api/async-logger-is-running.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `run()` sets the running state while the worker loop is active. - The flag is cleared when the worker exits normally or after failure handling finishes. - A logger may be closed while still running briefly during final drain or shutdown processing. +- This helper is only a direct read of the current `is_running` ref; it does not wait, synchronize, or infer why the value is what it is. - This helper focuses on worker activity rather than queue size or failure details. - `is_running()` can be `false` even when `pending_count()` is still nonzero, for example if the worker was never started or if it exited after a recorded failure. @@ -72,6 +73,8 @@ e.g.: - If `is_running()` is `true`, that still does not guarantee healthy drain progress; callers may need `has_failed()` or `state()` for failure context. +- Under concurrent activity, the returned value may change immediately after it is read. + ### Notes 1. Use this helper for worker activity checks, not as a complete health signal. diff --git a/docs/api/async-logger-last-error.md b/docs/api/async-logger-last-error.md index 4706cce..a0fc26f 100644 --- a/docs/api/async-logger-last-error.md +++ b/docs/api/async-logger-last-error.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `run()` resets the stored error string when the worker starts. - If the worker loop fails, the error text is captured from the raised exception. - An empty string normally means no failure has been recorded. +- Once a failure string is recorded, it stays in place until a later `run()` start clears it. - This helper reports worker execution errors, not ordinary overflow or backpressure conditions. - A new successful `run()` attempt clears any previously stored error text before drain work begins again. @@ -72,6 +73,8 @@ e.g.: - If callers need broader context than just the error text, they should use `state()`. +- `close()` or `shutdown()` do not clear a previously recorded error string by themselves. + ### Notes 1. Read this helper together with `has_failed()` when interpreting worker health.