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

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

name	group	category	update-time	description	key-word
async-overflow-policy	api	async	20260613	Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.	async overflow alias public

Async-overflow-policy

AsyncOverflowPolicy is the public enum that controls what an AsyncLogger should do when its queue cannot accept a record immediately. It is a direct alias to the async model enum used by AsyncLoggerConfig and the runtime queue selection logic.

Interface

pub type AsyncOverflowPolicy = @utils.AsyncOverflowPolicy

output

• AsyncOverflowPolicy - Public async queue overflow enum with the variants Blocking, DropOldest, and DropNewest.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a type alias, not a separate runtime adapter.
• AsyncOverflowPolicy::Blocking waits for queue space when a non-blocking enqueue does not succeed.
• 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.

How to Use

Here are some specific examples provided.

When Need Backpressure Instead Of Silent Dropping

When producers should wait for queue space:

let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::Blocking)

In this example, logging pressure can slow producers instead of dropping data immediately.

When Need Bounded Async Logging With Drop Behavior

When async logging should keep moving under load without blocking callers:

let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::DropNewest)

In this example, the incoming record is dropped if the queue cannot accept it.

Error Case

e.g.:

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

• Under drop policies, sustained overload increases dropped_count() instead of guaranteeing delivery.

Notes

1. This policy applies to bitlogger_async, not synchronous QueuedSink.

2. Choose Blocking only when producer-side waiting is acceptable for the caller.