mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 17:02:19 +00:00
Nanaloveyuki
71 lines
2.2 KiB
Markdown
71 lines
2.2 KiB
Markdown
---
|
|
name: queue-overflow-policy
|
|
group: api
|
|
category: sink
|
|
update-time: 20260613
|
|
description: Public overflow policy alias used by synchronous queued sinks and queue config.
|
|
key-word:
|
|
- 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
|
|
|
|
```moonbit
|
|
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:
|
|
```moonbit
|
|
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:
|
|
```moonbit
|
|
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.
|