naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-08-02 00:14:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 clarify root async builder docs

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 07:14:25 +08:00
parent 3a2817969a
commit 43e343158e
2 changed files with 7 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/build-async-logger.md
+4
View File
@@ -40,6 +40,8 @@ Detailed rules explaining key parameters and behaviors
- The returned sink type is `RuntimeSink`, which keeps configured control helpers available where relevant. - The returned sink type is `RuntimeSink`, which keeps configured control helpers available where relevant.
- This builder returns the underlying `AsyncLogger[@bitlogger.RuntimeSink]` value directly. `build_application_async_logger(...)` only re-exports the same result under the `ApplicationAsyncLogger` alias, while `build_library_async_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.RuntimeSink]`. - This builder returns the underlying `AsyncLogger[@bitlogger.RuntimeSink]` value directly. `build_application_async_logger(...)` only re-exports the same result under the `ApplicationAsyncLogger` alias, while `build_library_async_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.RuntimeSink]`.
- Because this path starts from `build_logger(config.logger)`, it preserves the broader runtime-sink build path, including sync-side queue decoration when `LoggerConfig.queue` is present. - Because this path starts from `build_logger(config.logger)`, it preserves the broader runtime-sink build path, including sync-side queue decoration when `LoggerConfig.queue` is present.
- In the current direct builder coverage, the returned logger exposes the expected serialized async state snapshot, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after `run()` or `shutdown()`.
- File-backed runtime helpers also stay directly available on the returned `RuntimeSink` with the same behavior later observed through the application and library facade equivalence tests.
- Use `build_async_text_logger(...)` instead when you want the direct text-console async builder path with `FormattedConsoleSink` and without the sync runtime-sink construction layer. - Use `build_async_text_logger(...)` instead when you want the direct text-console async builder path with `FormattedConsoleSink` and without the sync runtime-sink construction layer.
- The `src-async` library is designed to compile on `native / llvm / js / wasm / wasm-gc`, but runtime mode differs by backend. - The `src-async` library is designed to compile on `native / llvm / js / wasm / wasm-gc`, but runtime mode differs by backend.
- Current local release-facing verification is explicit for `native / js / wasm / wasm-gc`. - Current local release-facing verification is explicit for `native / js / wasm / wasm-gc`.
@@ -83,6 +85,8 @@ e.g.:
- If the configured sink shape is unsupported for a specific capability, the resulting runtime behavior follows the existing sink/runtime rules rather than inventing a separate builder-only failure model. - If the configured sink shape is unsupported for a specific capability, the resulting runtime behavior follows the existing sink/runtime rules rather than inventing a separate builder-only failure model.
- If callers depend on queued runtime-sink helpers or file-backed runtime helpers, this builder is the direct API that preserves them rather than a reduced facade path.
### Notes ### Notes
1. Prefer this API when applications externalize both sync sink choice and async queue behavior. 1. Prefer this API when applications externalize both sync sink choice and async queue behavior.
docs/api/build-async-text-logger.md
+3
View File
@@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors
- Unlike `build_async_logger(...)`, this helper does not run the full synchronous `build_logger(config.logger)` path first. - Unlike `build_async_logger(...)`, this helper does not run the full synchronous `build_logger(config.logger)` path first.
- That means it uses `config.logger.sink.text_formatter`, `min_level`, `target`, and `timestamp` directly, but it does not apply `LoggerConfig.queue` or preserve other sync runtime sink controls. - That means it uses `config.logger.sink.text_formatter`, `min_level`, `target`, and `timestamp` directly, but it does not apply `LoggerConfig.queue` or preserve other sync runtime sink controls.
- This builder returns the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value directly. `build_application_text_async_logger(...)` only re-exports that same result under the `ApplicationTextAsyncLogger` alias, while `build_library_async_text_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. - This builder returns the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value directly. `build_application_text_async_logger(...)` only re-exports that same result under the `ApplicationTextAsyncLogger` alias, while `build_library_async_text_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`.
- In the current direct text-builder coverage, the returned logger exposes the expected serialized async state snapshot, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution.
- The async `flush_policy` still comes from `config.async_config`, but this text-specific builder does not supply the explicit `flush=fn(sink) { sink.flush() }` callback used by `build_async_logger(...)`. - The async `flush_policy` still comes from `config.async_config`, but this text-specific builder does not supply the explicit `flush=fn(sink) { sink.flush() }` callback used by `build_async_logger(...)`.
- In practice, `Batch` and `Shutdown` therefore only trigger the default no-op async flush callback on this path, while each record write still follows whatever immediate behavior `FormattedConsoleSink` already has on its own. - In practice, `Batch` and `Shutdown` therefore only trigger the default no-op async flush callback on this path, while each record write still follows whatever immediate behavior `FormattedConsoleSink` already has on its own.
- This helper is best suited to text-console output paths where callers want the concrete formatted sink type instead of `RuntimeSink`. - This helper is best suited to text-console output paths where callers want the concrete formatted sink type instead of `RuntimeSink`.
@@ -69,6 +70,8 @@ e.g.:
- If the logger is never `run()`, pending records still follow the normal async queue lifecycle rules. - If the logger is never `run()`, pending records still follow the normal async queue lifecycle rules.
- If callers rely on the concrete formatter or post-run state shape, this builder is the direct API that preserves those text-console details rather than a reduced alias or wrapper.
### Notes ### Notes
1. This API is narrower than `build_async_logger(...)` because it preserves a concrete text sink type. 1. This API is narrower than `build_async_logger(...)` because it preserves a concrete text sink type.