BitLogger/docs/api/async-logger-type.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
async-logger-type	api	async	20260707	Public asynchronous logger root type used for queue-backed sink-preserving logging pipelines with explicit lifecycle, failure, and flush-callback state.	async logger type public

Async-logger-type

AsyncLogger[S] is the public asynchronous root logger type. It stores a concrete sink type S together with queue policy, runtime state counters, and lifecycle state, then serves as the base value for async composition, worker control, and async write APIs.

Interface

pub struct AsyncLogger[S] {
  min_level : @bitlogger.Level
  target : String
  timestamp : Bool
  overflow : AsyncOverflowPolicy
  max_batch : Int
  linger_ms : Int
  flush_policy : AsyncFlushPolicy
  sink : S
  flush_callback : (S) -> Unit raise
  context_fields : Array[@bitlogger.Field]
  filter : (@bitlogger.Record) -> Bool
  patch : @bitlogger.RecordPatch
  queue : @async.Queue[@bitlogger.Record]
  pending_count : Ref[Int]
  dropped_count : Ref[Int]
  phase : Ref[AsyncLifecyclePhase]
  last_error : Ref[String]
}

output

• AsyncLogger[S] - Public queue-backed asynchronous logger value parameterized by the concrete sink type S.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a public root struct, not a type alias.
• The current fields cover targeting, overflow policy, batching, linger timing, flush policy, the wrapped sink, context/filter/patch behavior, queue state, and the internal lifecycle phase model.
• flush_callback : (S) -> Unit raise stores the raising flush callback used by batch and shutdown flush policies.
• pending_count, dropped_count, phase, and last_error are the mutable runtime refs that power the higher-level lifecycle and diagnostics helpers.
• phase is the stronger internal lifecycle source of truth; helper reads such as is_closed(), is_running(), has_failed(), and the richer state() snapshot are derived from it.
• The sink type parameter is preserved across async composition, which is why helpers such as with_target(...), with_context_fields(...), with_filter(...), and with_patch(...) keep returning AsyncLogger[S].
• async_logger(...) constructs this type as the main asynchronous entry point.
• This root type is also what sits underneath both async facade families: ApplicationAsyncLogger is a direct alias over the runtime-sink line, while LibraryAsyncLogger[S] is a narrowing wrapper around an AsyncLogger[S] value.

How to Use

Here are some specific examples provided.

When Need A Typed Root Async Logger Value

When queue-backed logging should begin from a concrete sink-preserving root object:

let logger : AsyncLogger[ConsoleSink] = async_logger(console_sink(), target="app.async")

In this example, the root async logger keeps the concrete sink type visible for later typed composition.

When Need Worker Control Plus Runtime State

When code should both enqueue logs and inspect async runtime behavior:

let logger = async_logger(console_sink(), config=AsyncLoggerConfig::new(max_pending=32))
ignore(logger.pending_count())
ignore(logger.state())

In this example, the root type combines queue-backed logging with explicit runtime observability.

Error Case

e.g.:

• AsyncLogger[S] itself does not have a runtime failure mode.

• Actual enqueue, worker, and flush behavior still depends on the wrapped sink S, async runtime support, and the configured queue policy.

• Post-close logging behavior now follows the shared close contract rather than backend-specific divergence, but lifecycle interpretation should still prefer state() over manual field reasoning.

Notes

1. Use async_logger(...), build_async_logger(...), or build_async_text_logger(...) when you need a value of this type.

2. Use ApplicationAsyncLogger when application code wants the same full async lifecycle and state helper surface under an app-facing alias.

3. Use LibraryAsyncLogger[S] when a library boundary should intentionally narrow the public async surface and expose broader lifecycle/state helpers only through to_async_logger().

4. Prefer the method helpers such as state(), has_failed(), last_error(), is_running(), and shutdown() instead of reading these public fields conceptually as if they were a stable manual mutation surface.