mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
---
|
|
name: library-async-logger-new
|
|
group: api
|
|
category: facade
|
|
update-time: 20260613
|
|
description: Create a narrower library-facing async logger facade from any sink implementation.
|
|
key-word:
|
|
- async
|
|
- library
|
|
- facade
|
|
- public
|
|
---
|
|
|
|
## Library-async-logger-new
|
|
|
|
Create a `LibraryAsyncLogger[S]` from any sink implementation. This is the library-facing async constructor when you want queue-backed async logging behavior without exposing the full `AsyncLogger[S]` surface.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn[S] LibraryAsyncLogger::new(
|
|
sink : S,
|
|
config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(),
|
|
min_level~ : @bitlogger.Level = @bitlogger.Level::Info,
|
|
target~ : String = "",
|
|
flush~ : (S) -> Int raise = fn(_) { 0 },
|
|
) -> LibraryAsyncLogger[S] {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `sink : S` - Any sink value implementing `@bitlogger.Sink`, such as `@bitlogger.console_sink()` or a composed sink.
|
|
- `config : AsyncLoggerConfig` - Queue size, overflow behavior, batching, linger, and flush policy.
|
|
- `min_level : Level` - Minimum enabled level. Messages below this threshold are ignored before enqueue.
|
|
- `target : String` - Default target attached to emitted records unless later overridden.
|
|
- `flush : (S) -> Int raise` - Flush callback used when async batch or shutdown policy needs explicit flushing.
|
|
|
|
#### output
|
|
|
|
- `LibraryAsyncLogger[S]` - Narrow library-facing wrapper over a newly created async logger.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This API builds a regular `async_logger(...)` internally and then wraps it as `LibraryAsyncLogger`.
|
|
- The returned facade intentionally exposes a smaller method set than the full `AsyncLogger[S]` type.
|
|
- Queue settings, flush policy, and runtime state are preserved inside the wrapped async logger.
|
|
- Call `to_async_logger()` if later code must recover the full async logger surface.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Narrower Library-facing Async Constructor
|
|
|
|
When a package should create an async logger without exposing the full async logger API:
|
|
```moonbit
|
|
let logger = LibraryAsyncLogger::new(
|
|
@bitlogger.console_sink(),
|
|
config=AsyncLoggerConfig::new(max_pending=32),
|
|
target="plugin.async",
|
|
)
|
|
```
|
|
|
|
In this example, the package creates a normal async logging pipeline but publishes only the smaller facade type.
|
|
|
|
#### When Need Explicit Flush Behavior In A Library Boundary
|
|
|
|
When the sink requires a flush callback for batch or shutdown policy:
|
|
```moonbit
|
|
let logger = LibraryAsyncLogger::new(
|
|
@bitlogger.console_sink(),
|
|
flush=fn(sink) { 0 },
|
|
)
|
|
```
|
|
|
|
In this example, the facade still keeps the queue-backed async behavior while hiding the full async logger type.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If `target` is empty, the returned logger remains valid and later records simply use an empty default target.
|
|
|
|
- If later code needs methods outside the facade, it must unwrap with `to_async_logger()`.
|
|
|
|
### Notes
|
|
|
|
1. This is the direct constructor counterpart to `async_logger(...)` for library-oriented async APIs.
|
|
|
|
2. Prefer this when public package boundaries should stay narrower than `AsyncLogger[S]`.
|