naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-08-01 16:04:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 clarify async state json snapshot semantics

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 10:07:33 +08:00
parent 93fc54226d
commit 97f6ae969d
1 changed files with 4 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/async-logger-state-to-json.md
+4
View File
@@ -41,6 +41,8 @@ Detailed rules explaining key parameters and behaviors
- It shares the same stable field names used by `stringify_async_logger_state(...)`. - It shares the same stable field names used by `stringify_async_logger_state(...)`.
- The state must already have been captured or constructed before serialization. - The state must already have been captured or constructed before serialization.
- Serialization preserves whatever snapshot combination it receives, including failure flags together with remaining backlog counts. - Serialization preserves whatever snapshot combination it receives, including failure flags together with remaining backlog counts.
- This helper never rereads a logger instance by itself. If callers pass an older or manually constructed `AsyncLoggerState`, the JSON reflects that provided value exactly rather than refreshing fields from live runtime state.
- It also does not normalize mixed diagnostic combinations. If the provided snapshot says `is_closed=true` together with retained `has_failed=true`, `last_error`, or non-zero backlog counters, those exact combinations are emitted unchanged.
### How to Use ### How to Use
@@ -74,6 +76,8 @@ e.g.:
- If `has_failed` is `true`, serialization does not force `pending_count` to `0` or clear `last_error`; it reports the snapshot exactly as provided. - If `has_failed` is `true`, serialization does not force `pending_count` to `0` or clear `last_error`; it reports the snapshot exactly as provided.
- If callers need newer logger data, they must capture a fresh `AsyncLogger::state()` first instead of expecting JSON conversion itself to refresh stale fields.
### Notes ### Notes
1. This helper preserves the nested runtime snapshot instead of flattening `mode` and `background_worker` onto the top level. 1. This helper preserves the nested runtime snapshot instead of flattening `mode` and `background_worker` onto the top level.