BitLogger/docs/api/async-logger-flush-policy.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
async-logger-flush-policy	api	async	20260707	Read the async logger flush policy currently governing batch-end and shutdown-end flush-callback timing.	async logger flush public

Async-logger-flush-policy

Read the async logger flush policy. This helper exposes which flush mode currently controls batch and shutdown behavior.

Interface

pub fn[S] AsyncLogger::flush_policy(self : AsyncLogger[S]) -> AsyncFlushPolicy {}

input

• self : AsyncLogger[S] - Async logger whose flush policy should be inspected.

output

• AsyncFlushPolicy - Current flush policy used by the async worker logic.

Explanation

Detailed rules explaining key parameters and behaviors

• The returned value reflects the policy captured when the async logger was created.
• 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 progress count contract.
• The callback is now treated as an attempted flush action with optional failure, not as a meaningful returned item count.
• Builder routes that wrap RuntimeSink align with the sync/runtime facade by calling RuntimeSink::flush_progress() inside that callback and discarding the returned progress details.
• Text-specific async builder paths still 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

Here are some specific examples provided.

When Need To Inspect Runtime Flush Semantics

When diagnostics should show how the worker flushes:

ignore(logger.flush_policy())

In this example, the configured flush mode is exposed directly from the logger.

When Export Async Runtime Metadata

When code should include flush behavior in custom state reporting:

let flush = logger.flush_policy()

In this example, flush behavior can be surfaced without reading the full snapshot.

Error Case

e.g.:

• This helper does not expose a normal runtime error path; it returns the configured policy.

• If callers need the policy together with backlog and failure state, state() is usually the better API.

Notes

1. This helper exposes configuration-driven runtime behavior, not dynamic worker health.

2. Use state() when you want flush policy packaged with the rest of async logger diagnostics.