📝 clarify async facade projection docs

This commit is contained in:
Nanaloveyuki
2026-06-14 07:09:31 +08:00
parent 1f3da3e6ba
commit 959e553648
3 changed files with 11 additions and 0 deletions
@@ -38,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
- Use this when code needs wider async logger APIs outside the library facade.
- This is the step required for helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, `last_error()`, or broader composition methods that are intentionally hidden by `LibraryAsyncLogger[S]`.
- It is also the step that exposes the real post-run or post-shutdown state after facade-level lifecycle calls, because those calls delegated to this same wrapped logger all along.
- That includes failure/backlog combinations and runtime-dependent shutdown results exactly as they accumulated behind the facade.
- If the wrapped sink type has richer helper APIs, unwrapping also restores access to that same sink helper surface through the original `AsyncLogger[S]` value.
### How to Use
@@ -73,6 +75,8 @@ e.g.:
- Recovering the full async logger does not clear queue contents or reset failure state.
- Unwrapping does not convert facade lifecycle history into a simplified snapshot; any retained `last_error()`, pending backlog, dropped counts, or sink runtime details stay exactly as they were on the wrapped logger.
### Notes
1. Use this only when the narrower async facade is no longer sufficient.