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	20260512	Close the async logger queue and optionally clear pending records immediately.	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.

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 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.