naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-07-31 23:44:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 clarify text async facade sink-kind behavior

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 09:00:52 +08:00
parent 58d1e622a0
commit 4889f2b4b8
2 changed files with 10 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/build-application-text-async-logger.md
+5
View File
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
- This API delegates to `build_async_text_logger(...)` directly. - 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. - 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. - 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. - 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. - 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. - 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. 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]`. 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 #### 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.: 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 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 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. - 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.
docs/api/build-library-async-text-logger.md
+5
View File
@@ -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]`. - 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. - 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. - 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. - 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. - 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. 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 Need Async State Helpers After Library Text Construction
When library-facing text-console construction should still allow internal async inspection later: 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.: 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 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 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. - 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.