mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
---
|
|
name: async-logger-pending-count
|
|
group: api
|
|
category: async
|
|
update-time: 20260614
|
|
description: Read the current number of queued records that have not yet been drained or cleared from the async logger pipeline.
|
|
key-word:
|
|
- async
|
|
- logger
|
|
- queue
|
|
- public
|
|
---
|
|
|
|
## Async-logger-pending-count
|
|
|
|
Read the current number of queued records that are still waiting to be processed. This API is the most direct backlog metric for an async logger instance.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn[S] AsyncLogger::pending_count(self : AsyncLogger[S]) -> Int {}
|
|
```
|
|
|
|
#### input
|
|
|
|
- `self : AsyncLogger[S]` - Async logger whose current backlog should be inspected.
|
|
|
|
#### output
|
|
|
|
- `Int` - Current number of pending records still in the async pipeline.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- The count increases when records are accepted into the queue.
|
|
- The count decreases as the worker drains records.
|
|
- The count is also reset to `0` when queued records are abandoned through clear-close paths such as `close(clear=true)`.
|
|
- Log attempts against a closed queue do not create new pending backlog.
|
|
- This is a point-in-time metric and may change immediately after it is read.
|
|
- Use this helper when a single backlog number is enough and a full `state()` snapshot is unnecessary.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Fast Backlog Check
|
|
|
|
When code should observe queue pressure directly:
|
|
```moonbit
|
|
let pending = logger.pending_count()
|
|
```
|
|
|
|
In this example, callers get the current queue backlog without building a full diagnostics snapshot.
|
|
|
|
#### When Wait For Near-idle Conditions
|
|
|
|
When operators or tests want to inspect drain progress:
|
|
```moonbit
|
|
if logger.pending_count() == 0 {
|
|
println("queue idle")
|
|
}
|
|
```
|
|
|
|
In this example, the queue backlog is checked directly.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If the worker is not running, `pending_count()` may stay above `0` until records are drained or cleared.
|
|
|
|
- If `wait_idle()` returns early because `has_failed()` became `true`, `pending_count()` may still be above `0` until later cleanup or clear-close handling runs.
|
|
- In the current tested split, that later cleanup can either force the leftover pending item into `dropped_count()` on native-worker shutdown paths or leave the closed-queue remainder visible in `pending_count()` on compatibility shutdown paths.
|
|
- That means `pending_count()` can still stay above `0` even after `is_closed=true` on compatibility-style shutdown paths, because closure there does not necessarily convert the leftover failed backlog into dropped records.
|
|
|
|
- A later restarted `run()` can still drain that retained backlog after failure-reset startup, so a nonzero pending count after failure is not necessarily a permanent terminal state.
|
|
|
|
- If the queue is empty, the method simply returns `0`.
|
|
|
|
### Notes
|
|
|
|
1. Use `state()` when you also need dropped counts, failure state, or runtime mode.
|
|
|
|
2. This helper is useful for lightweight health checks and tests.
|
|
|
|
3. Pair it with `is_running()` or `has_failed()` when backlog alone is not enough to explain whether the worker is actively draining, stopped, or failed.
|