From e172e141e94ebfeee1a69084cd5843fc41d85592 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:57:38 +0800 Subject: [PATCH] :memo: align async facade builders --- docs/api/build-application-async-logger.md | 3 +++ docs/api/build-library-async-logger.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index 380ecaa..9d20e8a 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - This API delegates to `build_async_logger(...)`. - That means the embedded `LoggerConfig` is built first through the normal synchronous config path before the outer async layer is applied. - The returned logger keeps the standard async lifecycle and state helper surface. +- Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, it also keeps the same failure/reset and runtime-dependent post-close behavior documented on the underlying runtime-sink async logger. - Use this facade when application code wants a dedicated async app-level entry point. ### How to Use @@ -72,3 +73,5 @@ e.g.: 1. This is a facade over the existing async runtime logger builder. 2. Use `parse_and_build_application_async_logger(...)` when starting from JSON text. + +3. Use `build_application_text_async_logger(...)` instead when callers should keep the concrete text-console sink type and the direct text-builder path. diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index 73e592b..b60f9d6 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -38,6 +38,7 @@ 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 result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. +- The narrower facade does not change the underlying runtime-sink failure/reset or runtime-dependent close semantics; it only hides the broader helper surface until `to_async_logger()` is used. - 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. @@ -82,3 +83,5 @@ e.g.: 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`.