From 4b5456f6463876b454253b6989f450fef5b160dc Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:04:02 +0800 Subject: [PATCH] :memo: clarify async library facade scope --- docs/api/build-library-async-logger.md | 20 +++++++++++++++---- docs/api/library-async-logger.md | 9 ++++++--- .../parse-and-build-library-async-logger.md | 20 +++++++++++++++++-- 3 files changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index 9fd42ad..14a873c 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -2,8 +2,8 @@ name: build-library-async-logger group: api category: facade -update-time: 20260520 -description: Build the library-facing async logger facade from an AsyncLoggerBuildConfig. +update-time: 20260614 +description: Build the library-facing async logger facade from an AsyncLoggerBuildConfig while intentionally hiding direct async state helpers. key-word: - library - async @@ -35,8 +35,9 @@ pub fn build_library_async_logger( Detailed rules explaining key parameters and behaviors -- This API builds the general async runtime logger and then wraps it in the narrower `LibraryAsyncLogger` facade. +- This API builds the general async runtime logger and then wraps it in the narrower `LibraryAsyncLogger[@bitlogger.RuntimeSink]` facade. - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. +- Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can be used to recover the underlying full async logger. ### How to Use @@ -57,12 +58,23 @@ let logger = build_library_async_logger( In this example, async runtime construction is hidden behind the library facade. +#### When Need Async State Helpers After Library-oriented Construction + +When config-built async state inspection is still needed internally: +```moonbit +let logger = build_library_async_logger(config) +let full = logger.to_async_logger() +ignore(full.pending_count()) +``` + +In this example, the library async facade is unwrapped before using async state helpers. + ### Error Case e.g.: - If backend-specific sink limitations exist, they still apply under the facade. -- If callers need methods outside the library facade, they must unwrap with `to_async_logger()`. +- If callers need async state, failure-status, or idle-wait helpers outside the library facade, they must unwrap with `to_async_logger()`. ### Notes diff --git a/docs/api/library-async-logger.md b/docs/api/library-async-logger.md index 2953e47..e302ece 100644 --- a/docs/api/library-async-logger.md +++ b/docs/api/library-async-logger.md @@ -2,8 +2,8 @@ name: library-async-logger group: api category: facade -update-time: 20260613 -description: Public library-facing async logger facade type used to expose a narrower surface than AsyncLogger. +update-time: 20260614 +description: Public library-facing async logger facade type used to expose a narrower surface than AsyncLogger while preserving sink typing. key-word: - library - async @@ -33,7 +33,8 @@ Detailed rules explaining key parameters and behaviors - This is a public facade struct, not a type alias. - The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter. -- The facade keeps common library-safe async operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, `run()`, `shutdown()`, and the main async write methods. +- The facade keeps common library-safe async operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, `run()`, `shutdown()`, and the main async write methods `log(...)`, `info(...)`, `warn(...)`, and `error(...)`. +- It does not expose the wider `AsyncLogger[S]` composition surface or the async state and lifecycle inspection helpers directly. - Call `to_async_logger()` when later code must recover the full underlying `AsyncLogger[S]` surface. ### How to Use @@ -69,6 +70,8 @@ e.g.: - Runtime behavior still depends on the wrapped sink `S` and async runtime support, so sink-specific or target-specific limitations remain unchanged behind the facade. +- Helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, `is_running()`, `has_failed()`, `last_error()`, `flush_policy()`, `state()`, and `wait_idle()` remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first. + ### Notes 1. Use `LibraryAsyncLogger::new(...)`, `build_library_async_logger(...)`, or `parse_and_build_library_async_logger(...)` when you need a value of this type. diff --git a/docs/api/parse-and-build-library-async-logger.md b/docs/api/parse-and-build-library-async-logger.md index b612e68..de2ff9e 100644 --- a/docs/api/parse-and-build-library-async-logger.md +++ b/docs/api/parse-and-build-library-async-logger.md @@ -2,8 +2,8 @@ name: parse-and-build-library-async-logger group: api category: facade -update-time: 20260520 -description: Parse JSON async build config text and build the library-facing async logger facade. +update-time: 20260614 +description: Parse JSON async build config text and build the library-facing async logger facade while intentionally hiding direct async state helpers. key-word: - library - async @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - This API parses async build config text, validates it, builds the async runtime logger, and narrows it to the library facade. - The resulting facade keeps async lifecycle helpers while exposing a smaller public surface. +- Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection stay on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can recover the underlying async logger when a wider API is required. ### How to Use @@ -54,6 +55,19 @@ let logger = parse_and_build_library_async_logger( In this example, parsing and library-facade construction happen together. +#### When Need Async State Helpers After Text-driven Library Bootstrapping + +When JSON-driven construction should still allow internal async state inspection later: +```moonbit +let logger = parse_and_build_library_async_logger(raw) catch { + err => return +} +let full = logger.to_async_logger() +ignore(full.pending_count()) +``` + +In this example, the caller unwraps the library async facade before using async state helpers. + ### Error Case e.g.: @@ -61,6 +75,8 @@ e.g.: - If the embedded config is invalid, parsing raises before the library facade is returned. +- If callers assume async state or idle-wait helpers are available directly on the returned facade, they must unwrap first with `to_async_logger()`. + ### Notes 1. This is the narrow async library parse-and-build facade.