📝 clarify async policy docs

This commit is contained in:
Nanaloveyuki
2026-06-14 01:56:44 +08:00
parent c911ad8345
commit 034bd8fc99
2 changed files with 6 additions and 0 deletions
+3
View File
@@ -34,6 +34,7 @@ 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`.
- The canonical labels `Blocking`, `DropOldest`, and `DropNewest` are also the labels emitted again by async config serializers, so export and parse stay aligned around one public vocabulary.
- 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.
@@ -64,6 +65,8 @@ In this example, the incoming record is dropped if the queue cannot accept it.
e.g.:
- If async config text uses unsupported overflow text, async config parsing raises a failure.
- The parser error path for unsupported overflow text is the same `Failure` surface used by the async config utilities.
- 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.