mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
---
|
|
name: build-library-async-text-logger
|
|
group: api
|
|
category: facade
|
|
update-time: 20260614
|
|
description: Build the library-facing text-console async logger facade from an AsyncLoggerBuildConfig using the concrete text-console builder path.
|
|
key-word:
|
|
- library
|
|
- async
|
|
- text
|
|
- public
|
|
---
|
|
|
|
## Build-library-async-text-logger
|
|
|
|
Build a `LibraryAsyncLogger[FormattedConsoleSink]` from `AsyncLoggerBuildConfig`. This facade is the library-oriented async builder for the concrete text-console sink shape returned by `build_async_text_logger(...)`.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn build_library_async_text_logger(
|
|
config : AsyncLoggerBuildConfig,
|
|
) -> LibraryAsyncLogger[FormattedConsoleSink] {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `config : AsyncLoggerBuildConfig` - Combined sync logger config and async queue/runtime config.
|
|
|
|
#### output
|
|
|
|
- `LibraryAsyncLogger[FormattedConsoleSink]` - Library-facing async logger backed by formatted console output.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This API delegates to `build_async_text_logger(...)` and then narrows the result to `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`.
|
|
- It always produces a concrete `FormattedConsoleSink` from `config.logger.sink.text_formatter` instead of branching on sink kinds.
|
|
- Unlike `build_library_async_logger(...)`, this facade does not go through the full synchronous configured-logger build path first.
|
|
- 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 behind the wrapped text-console async logger.
|
|
- The returned facade wraps the same underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value that `build_async_text_logger(...)` would return directly, so `run()`, `shutdown()`, failure/reset handling, and runtime-dependent close behavior are unchanged under the narrower public type.
|
|
- Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`, not on the returned facade itself.
|
|
- `to_async_logger()` can recover the underlying full async logger if needed.
|
|
- Use this builder when the boundary should preserve the concrete text-console sink type while still hiding broader async inspection and helper APIs from downstream callers.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Narrow Async Text Logger For Libraries
|
|
|
|
When a library wants text-console async output and a narrower public type:
|
|
```moonbit
|
|
let logger = build_library_async_text_logger(
|
|
AsyncLoggerBuildConfig::new(
|
|
logger=text_console(target="lib.text.async"),
|
|
async_config=AsyncLoggerConfig::new(max_pending=4),
|
|
),
|
|
)
|
|
```
|
|
|
|
In this example, the async text sink shape is preserved under the library facade.
|
|
|
|
#### When Need Async State Helpers After Library Text Construction
|
|
|
|
When library-facing text-console construction should still allow internal async inspection later:
|
|
```moonbit
|
|
let logger = build_library_async_text_logger(config)
|
|
let full = logger.to_async_logger()
|
|
ignore(full.pending_count())
|
|
```
|
|
|
|
In this example, the facade is unwrapped before using async state helpers.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If callers need sink-kind-driven branching such as JSON console or file-backed async output, they should use `build_library_async_logger(...)` instead.
|
|
|
|
- If callers expect async state or idle-wait helpers directly on the returned facade, they must unwrap first with `to_async_logger()`.
|
|
|
|
- Normal async lifecycle expectations still apply if the logger is never run.
|
|
|
|
### Notes
|
|
|
|
1. This is the library-side counterpart to `build_application_text_async_logger(...)`.
|
|
|
|
2. It is most useful when a concrete text-console async sink type matters to the caller boundary.
|
|
|
|
3. Use `build_library_async_logger(...)` instead when the library-facing async type should keep the broader `RuntimeSink` build path, including sync queue application through `build_logger(config.logger)`.
|