📝 refine library async write docs

This commit is contained in:
Nanaloveyuki
2026-06-14 01:10:10 +08:00
parent be8b4f8626
commit f8ca093e95
4 changed files with 53 additions and 12 deletions
+10 -3
View File
@@ -3,7 +3,7 @@ name: library-async-logger-error
group: api
category: facade
update-time: 20260614
description: Enqueue an error-level record through a LibraryAsyncLogger facade using the highest built-in severity shortcut and the repo's direct async call style.
description: Enqueue an error-level record through a LibraryAsyncLogger facade by delegating to the wrapped async logger's error shortcut.
key-word:
- async
- library
@@ -39,10 +39,11 @@ pub async fn[S] LibraryAsyncLogger::error(
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Error, ...)` on the wrapped async logger.
- The record is still subject to patching, filtering, and overflow policy.
- This helper delegates to `error(...)` on the wrapped async logger, which in turn uses `log(Level::Error, ...)`.
- The record is still subject to stored shared context fields, patching, filtering, and overflow policy.
- Error records represent the highest built-in severity in this async facade API.
- Use this helper when a named error call is clearer than a raw `log(...)` call.
- Async state helpers remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first.
### How to Use
@@ -69,6 +70,8 @@ logger.error(
In this example, the error record carries structured context without falling back to the generic `log(...)` form.
And any shared context fields already stored on the facade are still prepended before these per-call fields.
### Error Case
e.g.:
@@ -76,8 +79,12 @@ e.g.:
- If callers need to inspect worker failure rather than emit an error record, `has_failed()` and `last_error()` are the relevant APIs on the full async logger.
- If callers need a per-call target override, they should use `log(...)` instead of this fixed-level shortcut.
### Notes
1. Use this helper for high-severity async application failures.
2. Emitting an error record is separate from the logger worker itself entering failure state.
3. Use `to_async_logger()` first when later code needs queue or failure inspection rather than another write shortcut.