From 4889f2b4b89f66989b23091fc76355b5ff6d2bcb Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 09:00:52 +0800 Subject: [PATCH] :memo: clarify text async facade sink-kind behavior --- docs/api/build-application-text-async-logger.md | 5 +++++ docs/api/build-library-async-text-logger.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/api/build-application-text-async-logger.md b/docs/api/build-application-text-async-logger.md index 8aaed05..f1bbd9e 100644 --- a/docs/api/build-application-text-async-logger.md +++ b/docs/api/build-application-text-async-logger.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - This API delegates to `build_async_text_logger(...)` directly. - It is intended for config-driven async text console output where callers want the concrete text sink shape rather than the broader runtime sink enum wrapper. - The builder always creates a `FormattedConsoleSink` from `config.logger.sink.text_formatter` instead of selecting among sink kinds. +- That means even if `config.logger.sink.kind` says `Console`, `JsonConsole`, or `File`, this facade still follows the text-console path and uses only the configured `text_formatter` details. - Unlike `build_application_async_logger(...)`, this alias-oriented builder does not go through the full synchronous configured-logger build path first. - 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 under the returned async logger. @@ -69,6 +70,8 @@ let logger = build_application_text_async_logger( In this example, the async logger is built for text-console output specifically. +And the chosen builder path matters more than `config.logger.sink.kind`: this facade still uses the text formatter directly because it always builds a `FormattedConsoleSink`. + And the returned value keeps the ordinary async logger target semantics because this facade does not wrap or narrow the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. #### When Need A Per-call Target Override After App Text Construction @@ -99,6 +102,8 @@ In this example, the application text alias exposes async state helpers directly e.g.: - If callers need sink-kind-driven branching such as JSON console or file-backed async output, they should use `build_application_async_logger(...)` instead. +- If the config carries file-oriented fields such as `path` only because `sink.kind` was set to `File`, this facade still ignores that sink-kind choice and does not create a file-backed async logger. + - 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. diff --git a/docs/api/build-library-async-text-logger.md b/docs/api/build-library-async-text-logger.md index b077aaa..224e996 100644 --- a/docs/api/build-library-async-text-logger.md +++ b/docs/api/build-library-async-text-logger.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - This API delegates to `build_async_text_logger(...)` and then narrows the result to `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. - It always produces a concrete `FormattedConsoleSink` from `config.logger.sink.text_formatter` instead of branching on sink kinds. +- That means even if `config.logger.sink.kind` says `Console`, `JsonConsole`, or `File`, this facade still follows the text-console path and uses only the configured `text_formatter` details. - Unlike `build_library_async_logger(...)`, this facade does not go through the full synchronous configured-logger build path first. - 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. @@ -67,6 +68,8 @@ let logger = build_library_async_text_logger( In this example, the async text sink shape is preserved under the library facade. +And the chosen builder path matters more than `config.logger.sink.kind`: this facade still uses the text formatter directly because it always builds a `FormattedConsoleSink` before narrowing to `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. + #### When Need Async State Helpers After Library Text Construction When library-facing text-console construction should still allow internal async inspection later: @@ -95,6 +98,8 @@ And later `info(...)`, `warn(...)`, or `error(...)` calls still use the facade's e.g.: - If callers need sink-kind-driven branching such as JSON console or file-backed async output, they should use `build_library_async_logger(...)` instead. +- If the config carries file-oriented fields such as `path` only because `sink.kind` was set to `File`, this facade still ignores that sink-kind choice and does not create a file-backed async logger. + - 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.