From 24c20c16be27f71223324fc5d5dacb77948fda77 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 06:53:17 +0800 Subject: [PATCH] :memo: narrow async facade semantics docs --- docs/api/application-async-logger.md | 2 +- docs/api/build-application-async-logger.md | 2 +- docs/api/build-library-async-logger.md | 2 +- docs/api/library-async-logger.md | 2 +- docs/api/parse-and-build-library-async-logger.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/application-async-logger.md b/docs/api/application-async-logger.md index 179c620..b1d106b 100644 --- a/docs/api/application-async-logger.md +++ b/docs/api/application-async-logger.md @@ -32,7 +32,7 @@ Detailed rules explaining key parameters and behaviors - This alias does not introduce a new runtime type or wrapper layer. - It preserves the same async lifecycle helpers such as `run()`, `shutdown()`, `pending_count()`, and `state()`. - Because this is only an alias, methods that are async on `AsyncLogger[@bitlogger.RuntimeSink]` remain async here as well. -- The alias therefore keeps the same runtime-sink lifecycle, failure/reset behavior, and runtime-dependent post-close semantics already documented on `AsyncLogger[@bitlogger.RuntimeSink]`. +- The alias therefore keeps the same runtime-sink lifecycle, queue, failure-state, and runtime-dependent post-close semantics already documented on `AsyncLogger[@bitlogger.RuntimeSink]`. - The alias exists to give application boot code a clearer public type name for the standard runtime-sink async logger. - Builders such as `build_application_async_logger(...)` and `parse_and_build_application_async_logger(...)` return this alias. diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index 2328ccc..ad004ed 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -41,7 +41,7 @@ Detailed rules explaining key parameters and behaviors - In particular, a sync queue configured on `LoggerConfig.queue` is preserved inside the wrapped `RuntimeSink` variant instead of being stripped away by the application alias. - 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. +- It also keeps the same queue counters, failure state, sink shape, and runtime-dependent post-close behavior as 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 diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index cce803c..b59e0e6 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -39,7 +39,7 @@ Detailed rules explaining key parameters and behaviors - The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `build_async_logger(...)` would produce directly. - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. -- The narrower facade does not change the underlying runtime-sink failure/reset or runtime-dependent close semantics; it only hides the broader helper surface until `to_async_logger()` is used. +- The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. - 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. - Use this builder when the boundary should preserve the runtime-sink async build path but still hide broader async inspection helpers from downstream callers. diff --git a/docs/api/library-async-logger.md b/docs/api/library-async-logger.md index 3a8b85d..def3496 100644 --- a/docs/api/library-async-logger.md +++ b/docs/api/library-async-logger.md @@ -71,7 +71,7 @@ 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. -- Post-close logging behavior and failure/reset semantics remain those of the wrapped `AsyncLogger[S]`; the facade only narrows what is directly exposed. +- Post-close logging behavior, queue state, and failure-state behavior remain those of the wrapped `AsyncLogger[S]`; the facade only narrows what is directly exposed. - 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. diff --git a/docs/api/parse-and-build-library-async-logger.md b/docs/api/parse-and-build-library-async-logger.md index adf2afd..47a0731 100644 --- a/docs/api/parse-and-build-library-async-logger.md +++ b/docs/api/parse-and-build-library-async-logger.md @@ -40,7 +40,7 @@ Detailed rules explaining key parameters and behaviors - The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `parse_async_logger_build_config_text(...)` plus `build_async_logger(...)` would produce directly. - The resulting facade keeps library-facing async operations such as `run()` and `shutdown()` while exposing a smaller public surface. -- The narrower facade does not change the underlying runtime-sink failure/reset or runtime-dependent close semantics; it only hides the broader helper surface until `to_async_logger()` is used. +- The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. - 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. - Use this parse/build facade when text-driven construction should preserve the runtime-sink build path but still hide broader async inspection helpers at the package boundary.