📝 refine async policy docs

This commit is contained in:
Nanaloveyuki
2026-06-14 00:33:59 +08:00
parent 7207c07cbf
commit 2845076b27
3 changed files with 20 additions and 8 deletions
+8 -2
View File
@@ -2,8 +2,8 @@
name: async-overflow-policy
group: api
category: async
update-time: 20260613
description: Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.
update-time: 20260614
description: Public overflow policy alias used by AsyncLoggerConfig, async parser labels, and runtime queue behavior.
key-word:
- async
- overflow
@@ -34,6 +34,8 @@ Detailed rules explaining key parameters and behaviors
- `AsyncOverflowPolicy::DropOldest` lets the underlying async queue discard older pending records when capacity is limited.
- `AsyncOverflowPolicy::DropNewest` discards the incoming record instead of blocking.
- The same enum is used by `AsyncLoggerConfig::new(...)`, async config parsing, and the queue-kind mapping inside `AsyncLogger`.
- Async config parsing accepts the canonical label `DropNewest` and also the compatibility alias `DropLatest`, both mapping to the same public enum variant.
- When `try_put(...)` reports that a record was not accepted under a drop policy, `dropped_count()` increases for that rejected enqueue.
### How to Use
@@ -64,8 +66,12 @@ e.g.:
- Under drop policies, sustained overload increases `dropped_count()` instead of guaranteeing delivery.
- The precise record discarded by the underlying queue behavior depends on the selected policy and queue implementation, so callers should not assume `dropped_count()` alone identifies which message was lost.
### Notes
1. This policy applies to `bitlogger_async`, not synchronous `QueuedSink`.
2. Choose `Blocking` only when producer-side waiting is acceptable for the caller.
3. Serialized config uses the canonical `DropNewest` label even though the parser also accepts `DropLatest`.