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

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

name	group	category	update-time	description	key-word
async-flush-policy	api	async	20260613	Public flush policy alias used by AsyncLoggerConfig and async worker flushing.	async flush alias public

Async-flush-policy

AsyncFlushPolicy is the public enum that defines when an async logger should call its flush function. It is a direct alias to the async model enum used by AsyncLoggerConfig, worker execution, and async logger state reporting.

Interface

pub type AsyncFlushPolicy = @utils.AsyncFlushPolicy

output

• AsyncFlushPolicy - Public async flush enum with the variants Never, Batch, and Shutdown.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a type alias, not a separate lifecycle wrapper.
• AsyncFlushPolicy::Never skips explicit flush calls from the async worker.
• AsyncFlushPolicy::Batch calls the configured flush function after each processed batch.
• AsyncFlushPolicy::Shutdown calls the configured flush function once after the worker loop exits.
• The current flush policy is also exposed through AsyncLogger::flush_policy() and included in AsyncLoggerState.

How to Use

Here are some specific examples provided.

When Need Explicit Flush After Every Processed Batch

When buffered sinks should flush incrementally during worker execution:

let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Batch)

In this example, each batch run triggers the provided flush callback.

When Need One Final Flush During Shutdown

When sink flushing should be deferred until the worker finishes:

let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Shutdown)

In this example, flushing happens when the worker loop exits instead of after each batch.

Error Case

e.g.:

• If async config text uses unsupported flush policy text, async config parsing raises a failure.

• If a sink never needs explicit flushing, Batch or Shutdown can add unnecessary work without changing output.

Notes

1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.

2. AsyncFlushPolicy::Never is the default in AsyncLoggerConfig::new(...).