BitLogger/docs/api/async-logger-close.md

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

name	group	category	update-time	description	key-word
async-logger-close	api	async	20260614	Close the async logger queue immediately and optionally convert current pending backlog into dropped records before queue closure.	async logger lifecycle public

Async-logger-close

Close the async logger queue and stop treating the logger as an active enqueue target. This API is the low-level lifecycle close primitive behind shutdown flows.

Interface

pub fn[S] AsyncLogger::close(self : AsyncLogger[S], clear? : Bool = false) -> Unit {}

input

• self : AsyncLogger[S] - Async logger that should be closed.
• clear : Bool - Whether pending records should be abandoned immediately instead of being left for drain behavior.

output

• Unit - No return value. The logger lifecycle state is updated in place.

Explanation

Detailed rules explaining key parameters and behaviors

• close(...) marks the logger as closed immediately.
• clear=false closes the queue without explicitly abandoning pending records in the helper itself.
• clear=true counts pending records as dropped and resets pending_count to 0 before closing the queue.
• This helper does not itself wait for the worker to finish.
• close(...) also does not change has_failed() or last_error(); it is a closure primitive, not a failure reset API.
• Because this is a low-level close primitive, it does not first run wait_idle() or apply the runtime-dependent fallback logic used by shutdown().

How to Use

Here are some specific examples provided.

When Need Immediate Queue Closure

When teardown should stop normal enqueue activity right away:

logger.close()

In this example, the logger enters closed state immediately.

When Need To Abandon Backlog Explicitly

When pending records should be discarded during fast shutdown:

logger.close(clear=true)

In this example, queued backlog is counted as dropped instead of waiting for further drain.

Error Case

e.g.:

• If clear=true, pending records are intentionally discarded and contribute to dropped_count().

• If clear=false, pending records may still exist after closure until worker drain or later cleanup resolves them.

• If callers need graceful waiting for drain completion, shutdown() is usually the better API.

Notes

1. This is a low-level lifecycle helper; prefer shutdown() for normal graceful teardown.

2. Use clear=true only when backlog loss is an acceptable shutdown tradeoff.

3. Pair it with pending_count(), dropped_count(), or state() when you need to observe what happened to existing backlog after closure.