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	20260614	Public flush policy alias used by AsyncLoggerConfig, async parser labels, 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.
• Async config parsing accepts the canonical label Never and also the compatibility alias None, both mapping to the same public enum variant.
• Batch flushing happens after the worker finishes one drained batch, not after every individual record write.

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.

• If the configured flush callback raises, the worker records failure state and stops instead of silently hiding the error.

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(...).

3. Serialized config uses the canonical Never label even though the parser also accepts None.