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

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:

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:

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.