BitLogger/docs/api/library-async-logger-run.md

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

name	group	category	update-time	description	key-word
library-async-logger-run	api	facade	20260613	Start the LibraryAsyncLogger worker loop by delegating to the wrapped async logger's run behavior.	async library worker public

Library-async-logger-run

Start the library-facing async logger worker loop. This is the core runtime API that drains queued records to the underlying sink while preserving the narrower facade boundary.

Interface

pub async fn[S : @bitlogger.Sink] LibraryAsyncLogger::run(self : LibraryAsyncLogger[S]) -> Unit {

input

• self : LibraryAsyncLogger[S] - Library-facing async logger whose queue should be drained by the worker loop.

output

• Unit - No return value. The method runs until the queue is closed or a worker failure occurs.

Explanation

Detailed rules explaining key parameters and behaviors

• This method delegates directly to the wrapped async logger's run() behavior.
• It starts the worker loop that makes accepted queued records reach the underlying sink.
• Failure and lifecycle state are still tracked by the wrapped async logger.
• The narrower library facade does not hide the need to explicitly activate queue draining.
• If the worker fails, the wrapped async logger records that through its failure-state helpers, which still require to_async_logger() for inspection from library-facing code.

How to Use

Here are some specific examples provided.

When Need Background Queue Drain Through The Facade

When library async logging should be processed by a worker task:

let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
@async.with_task_group(group => {
  group.spawn_bg(() => logger.run())
  logger.info("started")
  logger.shutdown()
})

In this example, run() is the worker loop that makes the async facade actually deliver queued records.

When Need Explicit Worker Lifetime Control

When worker execution should be started under caller control:

group.spawn_bg(() => logger.run())

In this example, the caller decides when the worker begins instead of hiding that lifecycle step.

And the started worker loop is still the same wrapped async logger runtime rather than a separate library-specific execution path.

Error Case

e.g.:

• If the worker loop fails, the wrapped async logger records failure state.

• If run() is never started, accepted records may remain queued and not reach the sink.

• If callers need to inspect is_running(), has_failed(), or last_error() directly, they must unwrap first with to_async_logger().

Notes

1. LibraryAsyncLogger::new(...) only constructs the facade; run() is what activates queue draining.

2. Pair this API with shutdown() for a complete worker lifecycle.

3. Use to_async_logger() first when operational code needs direct lifecycle or failure inspection in addition to starting the worker.