diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index 9d20e8a..a974e03 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -3,7 +3,7 @@ name: build-application-async-logger group: api category: facade update-time: 20260614 -description: Build the application-facing async logger facade from an AsyncLoggerBuildConfig through the sync-first async builder path. +description: Build the application-facing runtime-sink async logger alias from an AsyncLoggerBuildConfig through the sync-first async builder path. key-word: - application - async @@ -13,7 +13,7 @@ key-word: ## Build-application-async-logger -Build an `ApplicationAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-facing async facade over `build_async_logger(...)`. +Build an `ApplicationAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-facing runtime-sink async alias returned through `build_async_logger(...)`. ### Interface @@ -35,11 +35,13 @@ pub fn build_application_async_logger( Detailed rules explaining key parameters and behaviors -- This API delegates to `build_async_logger(...)`. +- This API delegates to `build_async_logger(...)` directly. - 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. +- Any optional synchronous queue layer and runtime-sink controls chosen by `build_logger(config.logger)` remain active under the returned logger. +- Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this builder 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 failure/reset and runtime-dependent post-close behavior documented on the underlying runtime-sink async logger. +- Use this alias-oriented builder when application code wants the standard runtime-sink async shape without narrowing the public surface. ### How to Use @@ -61,6 +63,17 @@ In this example, the app-facing async facade is built directly from typed config And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger. +#### When Need Async State Helpers Immediately After App Construction + +When application code should keep the ordinary async helper surface directly: +```moonbit +let logger = build_application_async_logger(config) +ignore(logger.pending_count()) +ignore(logger.state()) +``` + +In this example, the application alias exposes async state helpers directly because no narrowing wrapper is added. + ### Error Case e.g.: @@ -75,3 +88,5 @@ e.g.: 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. + +4. Use `build_library_async_logger(...)` instead when a library boundary should narrow the exposed async surface. diff --git a/docs/api/parse-and-build-application-async-logger.md b/docs/api/parse-and-build-application-async-logger.md index fa8334c..5e331eb 100644 --- a/docs/api/parse-and-build-application-async-logger.md +++ b/docs/api/parse-and-build-application-async-logger.md @@ -3,7 +3,7 @@ name: parse-and-build-application-async-logger group: api category: facade update-time: 20260614 -description: Parse JSON async build config text and build the application-facing async logger facade through the sync-first async builder path. +description: Parse JSON async build config text and build the application-facing runtime-sink async logger alias through the sync-first async builder path. key-word: - application - async @@ -13,7 +13,7 @@ key-word: ## Parse-and-build-application-async-logger -Parse raw JSON async build config text and build an `ApplicationAsyncLogger` in one step. This facade is the application-oriented counterpart to `parse_async_logger_build_config_text(...)` plus `build_application_async_logger(...)`. +Parse raw JSON async build config text and build an `ApplicationAsyncLogger` in one step. This is the application-oriented counterpart to `parse_async_logger_build_config_text(...)` plus `build_application_async_logger(...)`. ### Interface @@ -35,10 +35,12 @@ pub fn parse_and_build_application_async_logger( Detailed rules explaining key parameters and behaviors -- This API parses async build config text first, then builds the async application facade. +- This API parses async build config text first, then builds the application async logger through `build_application_async_logger(...)`. - Both the embedded sync logger config and async queue/runtime config are validated by the parser layer. - The embedded `LoggerConfig` is then built through the normal synchronous config path before the outer async layer is applied. -- The returned logger keeps the normal async lifecycle and state helpers. +- Any optional synchronous queue layer and runtime-sink controls from the parsed `logger` section remain active under the returned async logger. +- Because the result is the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this parse-and-build path does not narrow the helper surface. +- The returned logger keeps the full async lifecycle and state helpers directly. ### How to Use @@ -57,6 +59,19 @@ In this example, text parsing and async logger construction happen in one facade And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger. +#### When Need Async State Helpers After JSON-driven App Construction + +When application boot should parse JSON text and still keep direct access to async helper APIs: +```moonbit +let logger = parse_and_build_application_async_logger(raw) catch { + err => return +} +ignore(logger.pending_count()) +ignore(logger.state()) +``` + +In this example, no unwrap step is needed because the application result is an alias, not a narrowing facade. + ### Error Case e.g.: @@ -69,3 +84,5 @@ e.g.: 1. Use this facade when application boot starts from JSON text. 2. Use `build_application_async_logger(...)` when config is already typed as `AsyncLoggerBuildConfig`. + +3. Use `parse_and_build_library_async_logger(...)` instead when text-driven construction should narrow the public async surface for a library boundary.