BitLogger/docs/api/async-logger-has-failed.md

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

name	group	category	update-time	description	key-word
async-logger-has-failed	api	async	20260707	Read whether the async logger worker has recorded a runtime failure after run() startup reset and drain execution.	async logger failure public

Async-logger-has-failed

Read whether the async logger worker has encountered a failure. This helper is a compact health signal for async delivery problems.

Interface

pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool {}

input

• self : AsyncLogger[S] - Async logger whose failure flag should be inspected.

output

• Bool - Whether the worker has failed.

Explanation

Detailed rules explaining key parameters and behaviors

• run() clears previous failure state at startup.
• run() also clears the stored last_error() string at startup before drain work begins.
• If the worker loop raises an error, the logger transitions its lifecycle phase to failed or closed_failed and exposes that failure through this flag.
• Once set by a failed run, the flag stays true until a later run() invocation actually starts and resets it.
• Failure-driven shutdown does not clear this flag by itself, so has_failed() can remain true even after the logger is already closed.
• This helper is intentionally compact and should usually be paired with last_error() for details.
• Failure state is about runtime drain execution, not whether records were dropped due to overflow policy.

How to Use

Here are some specific examples provided.

When Need A Fast Failure Signal

When runtime diagnostics should branch on worker health:

if logger.has_failed() {
  println(logger.last_error())
}

In this example, the code checks failure state first, then reads the error detail.

When Inspect Async Runtime State In Tests

When a test needs to confirm that drain execution stayed healthy:

ignore(logger.has_failed())

In this example, the helper exposes a simple pass-fail runtime indicator.

Error Case

e.g.:

• If has_failed() is false, queue pressure or dropped records may still exist for non-failure reasons.

• If has_failed() becomes true, wait_idle() may stop early while pending records still remain until a later close or clear path handles them.

• In the current regression coverage, that later handling can be an explicit close(clear=true) that resets pending backlog immediately or a shutdown(...) path that clears retained pending backlog into dropped records before returning.

• If has_failed() is still true after shutdown, that does not by itself mean cleanup failed; the logger may already be phase=closed_failed and terminal=true while the retained failure record is still intentionally visible.

• If has_failed() is true, callers should inspect last_error() or state() for more context.

• close() or shutdown() do not clear this flag by themselves; only a later run() that has already started resets it.

Notes

1. This helper reports worker failure, not general queue stress.

2. Pair it with last_error() when you need actionable detail.

3. Pair it with is_running() or state() when you also need to know whether the worker has already exited and whether backlog remains.