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

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

name	group	category	update-time	description	key-word
queue-overflow-policy	api	sink	20260613	Public overflow policy alias used by synchronous queued sinks and queue config.	queue overflow alias public

Queue-overflow-policy

QueueOverflowPolicy is the public enum that defines what a synchronous queue should do when it reaches max_pending. It is a direct alias to the queue model enum used by both QueuedSink and QueueConfig.

Interface

pub type QueueOverflowPolicy = @utils.QueueOverflowPolicy

output

• QueueOverflowPolicy - Public synchronous queue overflow enum with the variants DropNewest and DropOldest.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a type alias, not a separate policy wrapper.
• QueueOverflowPolicy::DropNewest keeps the existing queued records and drops the incoming one when the queue is full.
• QueueOverflowPolicy::DropOldest removes one pending record and enqueues the new record instead.
• The same enum is used by code-side queue composition through queued_sink(...) and config-driven queue composition through QueueConfig::new(...).

How to Use

Here are some specific examples provided.

When Need A Bounded Queue That Prefers Older Pending Records

When the oldest pending records should be preserved and new bursts can be dropped:

let sink = queued_sink(console_sink(), max_pending=32, overflow=QueueOverflowPolicy::DropNewest)

In this example, new records are discarded once the queue is full.

When Need To Prefer Fresh Records Over Old Pending Work

When backlog should make room for newer records:

let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)

In this example, the oldest pending record is removed when the queue overflows.

Error Case

e.g.:

• If a queue is unbounded or never reaches capacity, the overflow policy has no effect.

• If parsed JSON uses unsupported overflow text, config parsing raises ConfigError.

Notes

1. This policy belongs to synchronous queue wrappers, not bitlogger_async.

2. Use AsyncOverflowPolicy for the async logger queue behavior.