From 43e343158ed81a27740b56b3936c5db8a0008c89 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 07:14:25 +0800 Subject: [PATCH] :memo: clarify root async builder docs --- docs/api/build-async-logger.md | 4 ++++ docs/api/build-async-text-logger.md | 3 +++ 2 files changed, 7 insertions(+) diff --git a/docs/api/build-async-logger.md b/docs/api/build-async-logger.md index 7113a21..e038498 100644 --- a/docs/api/build-async-logger.md +++ b/docs/api/build-async-logger.md @@ -40,6 +40,8 @@ Detailed rules explaining key parameters and behaviors - The returned sink type is `RuntimeSink`, which keeps configured control helpers available where relevant. - This builder returns the underlying `AsyncLogger[@bitlogger.RuntimeSink]` value directly. `build_application_async_logger(...)` only re-exports the same result under the `ApplicationAsyncLogger` alias, while `build_library_async_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.RuntimeSink]`. - Because this path starts from `build_logger(config.logger)`, it preserves the broader runtime-sink build path, including sync-side queue decoration when `LoggerConfig.queue` is present. +- In the current direct builder coverage, the returned logger exposes the expected serialized async state snapshot, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after `run()` or `shutdown()`. +- File-backed runtime helpers also stay directly available on the returned `RuntimeSink` with the same behavior later observed through the application and library facade equivalence tests. - Use `build_async_text_logger(...)` instead when you want the direct text-console async builder path with `FormattedConsoleSink` and without the sync runtime-sink construction layer. - The `src-async` library is designed to compile on `native / llvm / js / wasm / wasm-gc`, but runtime mode differs by backend. - Current local release-facing verification is explicit for `native / js / wasm / wasm-gc`. @@ -83,6 +85,8 @@ e.g.: - If the configured sink shape is unsupported for a specific capability, the resulting runtime behavior follows the existing sink/runtime rules rather than inventing a separate builder-only failure model. +- If callers depend on queued runtime-sink helpers or file-backed runtime helpers, this builder is the direct API that preserves them rather than a reduced facade path. + ### Notes 1. Prefer this API when applications externalize both sync sink choice and async queue behavior. diff --git a/docs/api/build-async-text-logger.md b/docs/api/build-async-text-logger.md index de52007..2f00991 100644 --- a/docs/api/build-async-text-logger.md +++ b/docs/api/build-async-text-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - Unlike `build_async_logger(...)`, this helper does not run the full synchronous `build_logger(config.logger)` path first. - That means it uses `config.logger.sink.text_formatter`, `min_level`, `target`, and `timestamp` directly, but it does not apply `LoggerConfig.queue` or preserve other sync runtime sink controls. - This builder returns the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value directly. `build_application_text_async_logger(...)` only re-exports that same result under the `ApplicationTextAsyncLogger` alias, while `build_library_async_text_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. +- In the current direct text-builder coverage, the returned logger exposes the expected serialized async state snapshot, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution. - The async `flush_policy` still comes from `config.async_config`, but this text-specific builder does not supply the explicit `flush=fn(sink) { sink.flush() }` callback used by `build_async_logger(...)`. - In practice, `Batch` and `Shutdown` therefore only trigger the default no-op async flush callback on this path, while each record write still follows whatever immediate behavior `FormattedConsoleSink` already has on its own. - This helper is best suited to text-console output paths where callers want the concrete formatted sink type instead of `RuntimeSink`. @@ -69,6 +70,8 @@ e.g.: - If the logger is never `run()`, pending records still follow the normal async queue lifecycle rules. +- If callers rely on the concrete formatter or post-run state shape, this builder is the direct API that preserves those text-console details rather than a reduced alias or wrapper. + ### Notes 1. This API is narrower than `build_async_logger(...)` because it preserves a concrete text sink type.