From 3a2817969a65785502c3fc21f8d8f9123f8ca4a1 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 07:12:53 +0800 Subject: [PATCH] :memo: clarify async text builder docs --- docs/api/build-application-text-async-logger.md | 3 +++ docs/api/build-library-async-text-logger.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/api/build-application-text-async-logger.md b/docs/api/build-application-text-async-logger.md index a61c8d2..53b7e2a 100644 --- a/docs/api/build-application-text-async-logger.md +++ b/docs/api/build-application-text-async-logger.md @@ -44,6 +44,7 @@ Detailed rules explaining key parameters and behaviors - Because the result is only the `ApplicationTextAsyncLogger` alias over `AsyncLogger[@bitlogger.FormattedConsoleSink]`, this builder returns the same underlying async logger value as `build_async_text_logger(...)` and does not hide any async helpers or introduce a wrapper layer. - The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`. - It also keeps the same close, queue, and failure-state semantics as the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. +- In the current direct text-builder coverage, this alias matches `build_async_text_logger(config)` through serialized state snapshots, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution. - Its configured `flush_policy` is still visible on the returned alias, but this text-specific build path does not wire the explicit sink flush callback that `build_application_async_logger(...)` inherits through `build_async_logger(...)`. - That means `Batch` and `Shutdown` only drive the default no-op async flush callback here; they do not add an extra explicit sink flush step beyond ordinary `FormattedConsoleSink` writes. - Use `build_library_async_text_logger(...)` instead when the next boundary should keep the same concrete text sink type but intentionally narrow the directly exposed async helper surface. @@ -84,6 +85,8 @@ e.g.: - If runtime draining is never started, records still follow the normal async queue lifecycle rules. +- If callers rely on the formatter or state shape after text-builder construction, they should treat this as the same direct `build_async_text_logger(config)` result rather than a reduced alias with different helper behavior. + ### Notes 1. This is a narrower text-console async facade than `build_application_async_logger(...)`. diff --git a/docs/api/build-library-async-text-logger.md b/docs/api/build-library-async-text-logger.md index ad6d80c..a2eef7a 100644 --- a/docs/api/build-library-async-text-logger.md +++ b/docs/api/build-library-async-text-logger.md @@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors - It uses the selected text-oriented `LoggerConfig` fields directly and therefore does not apply `LoggerConfig.queue` or preserve sync runtime sink controls. - A sync queue configured on `LoggerConfig.queue` is therefore ignored by this builder instead of being preserved behind the wrapped text-console async logger. - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value that `build_async_text_logger(...)` would return directly, so `run()`, `shutdown()`, and queue or failure-state behavior are unchanged under the narrower public type. +- In the current direct text-builder coverage, unwrapping this facade yields the same async state snapshot, formatter behavior, queue counters, lifecycle flags, and later failure fields as calling `build_async_text_logger(config)` directly. - The configured `flush_policy` is still carried by that underlying async logger, but this text-specific builder path does not provide the explicit sink flush callback used by `build_library_async_logger(...)` through `build_async_logger(...)`. - As a result, `Batch` and `Shutdown` only invoke the default no-op async flush callback on this text-console path unless downstream code unwraps and adds different behavior elsewhere. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`, not on the returned facade itself. @@ -83,6 +84,8 @@ e.g.: - If callers expect async state or idle-wait helpers directly on the returned facade, they must unwrap first with `to_async_logger()`. +- If callers need to inspect the actual formatter-backed async state after library-level `run()` or `shutdown()` calls, unwrapping exposes the same post-call counters and failure fields that the direct text builder would have produced. + - Normal async lifecycle expectations still apply if the logger is never run. ### Notes