naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-07-31 07:24:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 refine async run docs

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 00:50:55 +08:00
parent 5917256fda
commit 747f8e3d1b
2 changed files with 15 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/async-logger-is-closed.md
+7 -2
View File
@@ -2,8 +2,8 @@
name: async-logger-is-closed name: async-logger-is-closed
group: api group: api
category: async category: async
update-time: 20260512 update-time: 20260614
description: Read whether the async logger has been closed and should no longer accept normal new queue traffic. description: Read whether the async logger has entered closed lifecycle state and should no longer be treated as a normal active enqueue target.
key-word: key-word:
- async - async
- logger - logger
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
- `shutdown(...)` also results in a closed logger by the end of its lifecycle flow. - `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. - A closed logger should no longer be treated as a normal active enqueue target.
- This helper reflects lifecycle state only and does not indicate whether the worker is still draining. - 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.
### How to Use ### How to Use
@@ -70,8 +71,12 @@ e.g.:
- If callers need to know whether the worker is still active, they should also inspect `is_running()`. - If callers need to know whether the worker is still active, they should also inspect `is_running()`.
- 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.
### Notes ### Notes
1. Closed state and running state are related but not identical. 1. Closed state and running state are related but not identical.
2. Use this helper when lifecycle control matters more than queue counters. 2. Use this helper when lifecycle control matters more than queue counters.
3. Pair it with `pending_count()`, `is_running()`, or `state()` when you need to understand what closure means for remaining backlog on a live logger instance.
docs/api/async-logger-run.md
+8 -2
View File
@@ -2,8 +2,8 @@
name: async-logger-run name: async-logger-run
group: api group: api
category: async category: async
update-time: 20260512 update-time: 20260614
description: Start the async logger worker loop so queued records are drained to the underlying sink. description: Start the async logger worker loop so queued records are drained to the underlying sink while lifecycle and failure state are reset and updated around execution.
key-word: key-word:
- async - async
- logger - logger
@@ -35,7 +35,9 @@ Detailed rules explaining key parameters and behaviors
- `run()` sets `is_running` to `true` while the worker loop is active. - `run()` sets `is_running` to `true` while the worker loop is active.
- It clears previous failure state before worker execution begins. - It clears previous failure state before worker execution begins.
- It also resets `last_error()` to an empty string before worker execution begins.
- On failure, the logger records `has_failed=true` and stores the error text in `last_error`. - On failure, the logger records `has_failed=true` and stores the error text in `last_error`.
- On failure, `is_running` is cleared before the error is raised back out of `run()`.
- The worker exits when the queue is closed or when a failure aborts processing. - The worker exits when the queue is closed or when a failure aborts processing.
### How to Use ### How to Use
@@ -72,8 +74,12 @@ e.g.:
- If `run()` is never started, accepted records may remain queued and not reach the sink. - If `run()` is never started, accepted records may remain queued and not reach the sink.
- A later `run()` attempt starts from a fresh failure flag and empty `last_error()` string, even if an earlier run failed.
### Notes ### Notes
1. `async_logger(...)` only constructs the logger; `run()` is what activates queue draining. 1. `async_logger(...)` only constructs the logger; `run()` is what activates queue draining.
2. Pair this API with `shutdown()` for a complete worker lifecycle. 2. Pair this API with `shutdown()` for a complete worker lifecycle.
3. Pair it with `has_failed()`, `last_error()`, or `state()` when tests need to inspect how a worker exit affected logger health.