diff --git a/docs/api/application-async-logger.md b/docs/api/application-async-logger.md index 8155abd..14c5de4 100644 --- a/docs/api/application-async-logger.md +++ b/docs/api/application-async-logger.md @@ -31,6 +31,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 it is `AsyncLogger[@bitlogger.RuntimeSink]`, the alias also keeps ordinary async logger composition and target behavior such as `with_target(...)`, `child(...)`, and per-call `log(..., target=...)` overrides. - 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, queue, failure-state, and runtime-dependent post-close semantics already documented on `AsyncLogger[@bitlogger.RuntimeSink]`. - In the current direct alias coverage, values built through `build_application_async_logger(...)` keep the same serialized state snapshot shape, queue counters, lifecycle flags, failure fields, and runtime-sink helper surface that the underlying runtime-sink async logger exposes directly. @@ -64,6 +65,8 @@ async fn start_async(logger : ApplicationAsyncLogger) -> Unit { In this example, callers see the app-facing alias instead of the more explicit generic async logger spelling, while `run()` keeps its async calling contract. +And the inherited async logger target rules stay the same: `log(..., target=...)` can override the target per call, while `with_target(...)` and `child(...)` derive new logger values with changed default targets. + ### Error Case e.g.: @@ -77,6 +80,8 @@ e.g.: 1. This alias is about naming and public intent, not a different async implementation. -2. Use `build_application_async_logger(...)` or `parse_and_build_application_async_logger(...)` for the usual construction paths. +2. Inherited `AsyncLogger` behavior stays unchanged on this alias, including target overrides on `log(...)` and derived target composition through `with_target(...)` and `child(...)`. -3. Use `ApplicationTextAsyncLogger` or `build_application_text_async_logger(...)` when application code should keep the narrower text-console sink type instead of the broader runtime-sink alias. +3. Use `build_application_async_logger(...)` or `parse_and_build_application_async_logger(...)` for the usual construction paths. + +4. Use `ApplicationTextAsyncLogger` or `build_application_text_async_logger(...)` when application code should keep the narrower text-console sink type instead of the broader runtime-sink alias. diff --git a/docs/api/application-text-async-logger.md b/docs/api/application-text-async-logger.md index 3626ff9..74599a4 100644 --- a/docs/api/application-text-async-logger.md +++ b/docs/api/application-text-async-logger.md @@ -31,6 +31,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 as other async logger aliases. +- Because it is `AsyncLogger[@bitlogger.FormattedConsoleSink]`, the alias also keeps ordinary async logger composition and target behavior such as `with_target(...)`, `child(...)`, and per-call `log(..., target=...)` overrides. - Because this is only an alias, methods that are async on `AsyncLogger[@bitlogger.FormattedConsoleSink]` remain async here as well. - The alias therefore keeps the same text-console-specific builder and lifecycle semantics already documented on `AsyncLogger[@bitlogger.FormattedConsoleSink]`, including the concrete sink shape plus the same close, queue, and failure-state behavior. - The application-facing type does not hide any async state or lifecycle helpers; queue/backlog/failure inspection remains directly available on this alias just as it is on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. @@ -68,6 +69,8 @@ In this example, the app-facing alias communicates the concrete text-console asy And the same pending-count, state, and failure helpers remain directly available because no narrowing wrapper is added. +And the inherited async logger target rules stay the same: `log(..., target=...)` can override the target per call, while `with_target(...)` and `child(...)` derive new logger values with changed default targets. + ### Error Case e.g.: @@ -81,8 +84,10 @@ e.g.: 1. This alias is about naming and public intent, not a different async implementation. -2. Use `build_application_text_async_logger(...)` when callers want the `FormattedConsoleSink`-backed async type explicitly. +2. Inherited `AsyncLogger` behavior stays unchanged on this alias, including target overrides on `log(...)` and derived target composition through `with_target(...)` and `child(...)`. -3. Use `ApplicationAsyncLogger` when application code should keep the broader runtime-sink shape instead of the text-console-specific one. +3. Use `build_application_text_async_logger(...)` when callers want the `FormattedConsoleSink`-backed async type explicitly. -4. Use `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]` instead when a library boundary should intentionally narrow the exposed async surface while still preserving the concrete text sink type. +4. Use `ApplicationAsyncLogger` when application code should keep the broader runtime-sink shape instead of the text-console-specific one. + +5. Use `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]` instead when a library boundary should intentionally narrow the exposed async surface while still preserving the concrete text sink type. diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index 913390a..b70c3e8 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - Any optional synchronous queue layer and runtime-sink controls chosen by `build_logger(config.logger)` remain active under the returned logger. - 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 alias also keeps inherited async logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - 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 queue counters, failure state, sink shape, and runtime-dependent post-close behavior as the underlying runtime-sink async logger. - In the current direct builder coverage, this alias matches `build_async_logger(config)` all the way through serialized state snapshots, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after `run()` or `shutdown()`. @@ -66,6 +67,8 @@ 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. +The returned value also keeps the ordinary async logger target semantics because the facade does not wrap or narrow the underlying `AsyncLogger[@bitlogger.RuntimeSink]`. + #### When Need Async State Helpers Immediately After App Construction When application code should keep the ordinary async helper surface directly: diff --git a/docs/api/build-application-text-async-logger.md b/docs/api/build-application-text-async-logger.md index 53b7e2a..4b5a1da 100644 --- a/docs/api/build-application-text-async-logger.md +++ b/docs/api/build-application-text-async-logger.md @@ -42,6 +42,7 @@ Detailed rules explaining key parameters and behaviors - 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. - Because the result is only the `ApplicationTextAsyncLogger` alias over `AsyncLogger[@bitlogger.FormattedConsoleSink]`, this builder returns the same underlying async logger value as `build_async_text_logger(...)` and does not hide any async helpers or introduce a wrapper layer. +- The returned alias also keeps inherited async logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - 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 close, queue, and failure-state semantics as the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. - In the current direct text-builder coverage, this alias matches `build_async_text_logger(config)` through serialized state snapshots, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution. @@ -67,6 +68,8 @@ let logger = build_application_text_async_logger( In this example, the async logger is built for text-console output specifically. +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 Async State Helpers Immediately After Text App Construction When application code should keep the ordinary async helper surface directly on the text-console variant: