From eb3ec42a59745a750ef80f508c63c71fc951e641 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 09:29:16 +0800 Subject: [PATCH] :memo: clarify async flush policy callback semantics --- docs/api/async-logger-flush-policy.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/api/async-logger-flush-policy.md b/docs/api/async-logger-flush-policy.md index 3343e08..7aabf00 100644 --- a/docs/api/async-logger-flush-policy.md +++ b/docs/api/async-logger-flush-policy.md @@ -34,9 +34,11 @@ pub fn[S] AsyncLogger::flush_policy(self : AsyncLogger[S]) -> AsyncFlushPolicy { Detailed rules explaining key parameters and behaviors - The returned value reflects the policy captured when the async logger was created. -- `Batch` causes explicit flush calls after each completed drained batch, not after every individual record write. -- `Shutdown` causes one explicit flush call after the worker loop exits. -- `Never` leaves flushing entirely to sink behavior or external control. +- `Batch` means the worker invokes the stored async flush callback after each completed drained batch, not after every individual record write. +- `Shutdown` means the worker invokes the stored async flush callback once after the worker loop exits. +- `Never` leaves that explicit callback path unused and relies entirely on sink behavior or external control. +- This helper reports callback timing policy, not a guarantee that a particular sink type has a meaningful built-in flush effect on every constructor path. +- In particular, text-specific async builder paths keep the default no-op flush callback even when the visible policy is `Batch` or `Shutdown`, so the reported policy can describe when the callback would run without implying extra sink work actually happens on that path. ### How to Use