Build-library-async-logger

Build a LibraryAsyncLogger[RuntimeSink] from AsyncLoggerBuildConfig. This is the library-facing async facade over the general config-driven async builder.

Interface

pub fn build_library_async_logger(
  config : AsyncLoggerBuildConfig,
) -> LibraryAsyncLogger[RuntimeSink] {

input

• config : AsyncLoggerBuildConfig - Combined sync logger config and async queue/runtime config.

output

• LibraryAsyncLogger[RuntimeSink] - Library-facing async logger wrapper.

Explanation

Detailed rules explaining key parameters and behaviors

• This API builds the general async runtime logger and then wraps it in the narrower LibraryAsyncLogger[@bitlogger.RuntimeSink] facade.
• The embedded LoggerConfig still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed.
• The returned facade wraps the same underlying AsyncLogger[@bitlogger.RuntimeSink] value that build_async_logger(...) would produce directly.
• The result keeps async lifecycle operations such as run() and shutdown() while narrowing the public shape.
• The broader async helper surface is preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue counters, lifecycle state, idle-wait helpers, and file-backed runtime helpers stay behind to_async_logger() instead of disappearing.
• The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until to_async_logger() is used.
• Because this facade starts from build_async_logger(...), the wrapped async logger also keeps the runtime-sink flush wiring: Batch and Shutdown use the built sink's real flush() path instead of the default no-op callback used by the text-specific builder line.
• The facade still preserves the underlying async target rules on its exposed write methods: log(..., target=...) can override the target for one call, while info(...), warn(...), and error(...) continue using the stored logger target unless the facade first derived another logger with with_target(...) or child(...).
• In the current direct builder coverage, unwrapping this facade produces the same async state snapshot, runtime-sink variant, queue counters, lifecycle flags, and failure fields as calling build_async_logger(config) directly.
• That same unwrap also preserves file-backed runtime helpers on RuntimeSink values rather than replacing them with facade-specific behavior.
• Async state helpers such as pending_count(), dropped_count(), state(), wait_idle(), and failure-status inspection remain on the underlying AsyncLogger, not on the returned facade itself.
• to_async_logger() can be used to recover the underlying full async logger.
• Use this builder when the boundary should preserve the runtime-sink async build path but still hide broader async inspection helpers from downstream callers.

How to Use

Here are some specific examples provided.

When Need A Narrower Async Type For Libraries

When a reusable package should expose async logging but not the full runtime type directly:

let logger = build_library_async_logger(
  AsyncLoggerBuildConfig::new(
    logger=LoggerConfig::new(target="lib.async"),
    async_config=AsyncLoggerConfig::new(max_pending=4),
  ),
)

In this example, async runtime construction is hidden behind the library facade.

When Need Async State Helpers After Library-oriented Construction

When config-built async state inspection is still needed internally:

let logger = build_library_async_logger(config)
let full = logger.to_async_logger()
ignore(full.pending_count())

In this example, the library async facade is unwrapped before using async state helpers.

And unlike ApplicationAsyncLogger, the narrower builder result does not expose those broader async helpers directly on the facade surface.

When Need A Per-call Target Override Through The Library Async Builder Facade

When typed library async config should still build a facade that allows a one-call target override without unwrapping first:

let logger = build_library_async_logger(config)
logger.log(@bitlogger.Level::Error, "boom", target="lib.audit")

In this example, the emitted record uses lib.audit for that call.

And later info(...), warn(...), or error(...) calls still use the facade's stored target unless code derives another facade first with with_target(...) or child(...).

Error Case

e.g.:

• If backend-specific sink limitations exist, they still apply under the facade.

• If callers need async state, failure-status, or idle-wait helpers outside the library facade, they must unwrap with to_async_logger().

• If callers need file-backed runtime helpers such as file-state or queued runtime inspection, they must unwrap first, but the helper behavior itself stays aligned with the direct build_async_logger(config) result.

• If callers instead want the text-console builder path where Batch and Shutdown keep the default no-op flush callback, they should use build_library_async_text_logger(...); this runtime-sink facade preserves the real sink flush() behavior from build_async_logger(...).

Notes

1. Prefer this API when library boundaries should stay narrow.

2. Use parse_and_build_library_async_logger(...) when starting from JSON text.

3. Use build_library_async_text_logger(...) instead when the library-facing async type should preserve the narrower FormattedConsoleSink shape rather than RuntimeSink.