From 27f7651c9a2c4d32f323b0a35c4215413d589c35 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Fri, 8 May 2026 18:13:57 +0800 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Harden=20async=20logger=20?= =?UTF-8?q?lifecycle=20semantics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + bitlogger_async/async_logger_native.mbt | 77 +++++++++++-- bitlogger_async/async_logger_stub.mbt | 141 ++++++++++++++++++++++++ docs/README-en.md | 2 + docs/changes/0.3.0.md | 1 + examples/async_basic/main.mbt | 3 +- 6 files changed, 217 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d7728e9..eadad70 100644 --- a/README.md +++ b/README.md @@ -187,6 +187,8 @@ if native_files_supported() { - 当前已新增独立 package：`bitlogger_async/` - 异步层基于 `moonbitlang/async`，提供 `AsyncLogger`、`async_logger(...)`、后台 `run()` worker 与有界 async queue - 当前 async API 已支持 `with_context_fields(...)`、`with_filter(...)`、`with_patch(...)`、`with_target(...)`、`child(...)` +- 当前建议用 `shutdown()` 收口 worker；它会在默认模式下先等待队列清空，再关闭 queue 并等待 worker 退出 +- 当前已支持基础生命周期观测：`is_closed()`、`is_running()`、`has_failed()`、`last_error()` - 推荐启动方式见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1) - 这层目前仅面向 `native/llvm` backend；它是独立 adapter，不会污染现有同步 core diff --git a/bitlogger_async/async_logger_native.mbt b/bitlogger_async/async_logger_native.mbt index 630e087..3be4867 100644 --- a/bitlogger_async/async_logger_native.mbt +++ b/bitlogger_async/async_logger_native.mbt @@ -94,6 +94,10 @@ pub struct AsyncLogger[S] { queue : @async.Queue[@bitlogger.Record] pending_count : Ref[Int] dropped_count : Ref[Int] + is_closed : Ref[Bool] + is_running : Ref[Bool] + has_failed : Ref[Bool] + last_error : Ref[String] } pub fn[S] async_logger( @@ -114,6 +118,10 @@ pub fn[S] async_logger( queue: @async.Queue::new(kind=queue_kind_of(config)), pending_count: Ref::new(0), dropped_count: Ref::new(0), + is_closed: Ref::new(false), + is_running: Ref::new(false), + has_failed: Ref::new(false), + last_error: Ref::new(""), } } @@ -298,29 +306,84 @@ pub fn[S] AsyncLogger::dropped_count(self : AsyncLogger[S]) -> Int { self.dropped_count.val } +pub fn[S] AsyncLogger::is_closed(self : AsyncLogger[S]) -> Bool { + self.is_closed.val +} + +pub fn[S] AsyncLogger::is_running(self : AsyncLogger[S]) -> Bool { + self.is_running.val +} + +pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool { + self.has_failed.val +} + +pub fn[S] AsyncLogger::last_error(self : AsyncLogger[S]) -> String { + self.last_error.val +} + pub fn[S] AsyncLogger::close(self : AsyncLogger[S], clear? : Bool = false) -> Unit { + self.is_closed.val = true + if clear { + let abandoned = self.pending_count.val + if abandoned > 0 { + self.dropped_count.val += abandoned + self.pending_count.val = 0 + } + } self.queue.close(error=AsyncLoggerClosed, clear=clear) } -pub async fn[S] AsyncLogger::wait_idle(self : AsyncLogger[S]) -> Unit { - while self.pending_count() > 0 { +pub async fn[S] AsyncLogger::shutdown(self : AsyncLogger[S], clear? : Bool = false) -> Unit { + if clear { + self.close(clear=true) + } else { + self.wait_idle() + if self.pending_count() > 0 { + self.close(clear=true) + } else { + self.close() + } + } + while self.is_running() { @async.pause() } } -pub async fn[S : @bitlogger.Sink] AsyncLogger::run(self : AsyncLogger[S]) -> Unit { +pub async fn[S] AsyncLogger::wait_idle(self : AsyncLogger[S]) -> Unit { + while self.pending_count() > 0 && self.is_running() { + @async.pause() + } +} + +async fn[S : @bitlogger.Sink] run_worker(logger : AsyncLogger[S]) -> Unit { while true { - let rec = self.queue.get() catch { + let rec = logger.queue.get() catch { err if err is AsyncLoggerClosed => break err => raise err } - self.sink.write(rec) - if self.pending_count.val > 0 { - self.pending_count.val -= 1 + logger.sink.write(rec) + if logger.pending_count.val > 0 { + logger.pending_count.val -= 1 } } } +pub async fn[S : @bitlogger.Sink] AsyncLogger::run(self : AsyncLogger[S]) -> Unit { + self.is_running.val = true + self.has_failed.val = false + self.last_error.val = "" + run_worker(self) catch { + err => { + self.has_failed.val = true + self.last_error.val = err.to_string() + self.is_running.val = false + raise err + } + } + self.is_running.val = false +} + pub fn build_async_logger( config : AsyncLoggerBuildConfig, ) -> AsyncLogger[@bitlogger.RuntimeSink] { diff --git a/bitlogger_async/async_logger_stub.mbt b/bitlogger_async/async_logger_stub.mbt index 19fc113..7b1a2d1 100644 --- a/bitlogger_async/async_logger_stub.mbt +++ b/bitlogger_async/async_logger_stub.mbt @@ -22,6 +22,23 @@ pub fn AsyncLoggerConfig::new( pub struct AsyncLogger[S] {} +pub struct AsyncLoggerBuildConfig { + logger : @bitlogger.LoggerConfig + async_config : AsyncLoggerConfig +} + +pub fn AsyncLoggerBuildConfig::new( + logger~ : @bitlogger.LoggerConfig = @bitlogger.default_logger_config(), + async_config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(), +) -> AsyncLoggerBuildConfig { + { logger, async_config } +} + +pub fn parse_async_logger_build_config_text(input : String) -> AsyncLoggerBuildConfig raise { + ignore(input) + abort("bitlogger_async currently only supports native/llvm backends") +} + pub fn async_logger[S : @bitlogger.Sink]( sink : S, config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(), @@ -34,3 +51,127 @@ pub fn async_logger[S : @bitlogger.Sink]( ignore(target) abort("bitlogger_async currently only supports native/llvm backends") } + +pub fn[S] AsyncLogger::with_timestamp(self : AsyncLogger[S], enabled~ : Bool = true) -> AsyncLogger[S] { + ignore(self) + ignore(enabled) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::with_target(self : AsyncLogger[S], target : String) -> AsyncLogger[S] { + ignore(self) + ignore(target) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::with_context_fields( + self : AsyncLogger[S], + fields : Array[@bitlogger.Field], +) -> AsyncLogger[S] { + ignore(self) + ignore(fields) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::with_filter( + self : AsyncLogger[S], + predicate : (@bitlogger.Record) -> Bool, +) -> AsyncLogger[S] { + ignore(self) + ignore(predicate) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::with_patch( + self : AsyncLogger[S], + patch : @bitlogger.RecordPatch, +) -> AsyncLogger[S] { + ignore(self) + ignore(patch) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::with_min_level( + self : AsyncLogger[S], + min_level : @bitlogger.Level, +) -> AsyncLogger[S] { + ignore(self) + ignore(min_level) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::child(self : AsyncLogger[S], target : String) -> AsyncLogger[S] { + ignore(self) + ignore(target) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::is_enabled(self : AsyncLogger[S], level : @bitlogger.Level) -> Bool { + ignore(self) + ignore(level) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::pending_count(self : AsyncLogger[S]) -> Int { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::dropped_count(self : AsyncLogger[S]) -> Int { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::is_closed(self : AsyncLogger[S]) -> Bool { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::is_running(self : AsyncLogger[S]) -> Bool { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::last_error(self : AsyncLogger[S]) -> String { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn[S] AsyncLogger::close(self : AsyncLogger[S], clear? : Bool = false) -> Unit { + ignore(self) + ignore(clear) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub async fn[S] AsyncLogger::wait_idle(self : AsyncLogger[S]) -> Unit { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub async fn[S] AsyncLogger::shutdown(self : AsyncLogger[S], clear? : Bool = false) -> Unit { + ignore(self) + ignore(clear) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub async fn[S : @bitlogger.Sink] AsyncLogger::run(self : AsyncLogger[S]) -> Unit { + ignore(self) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn build_async_logger( + config : AsyncLoggerBuildConfig, +) -> AsyncLogger[@bitlogger.RuntimeSink] { + ignore(config) + abort("bitlogger_async currently only supports native/llvm backends") +} + +pub fn build_async_text_logger(config : AsyncLoggerBuildConfig) -> AsyncLogger[@bitlogger.FormattedConsoleSink] { + ignore(config) + abort("bitlogger_async currently only supports native/llvm backends") +} diff --git a/docs/README-en.md b/docs/README-en.md index 933b3ae..b1f5460 100644 --- a/docs/README-en.md +++ b/docs/README-en.md @@ -176,6 +176,8 @@ if native_files_supported() { - A separate `bitlogger_async/` package is now included. - It uses `moonbitlang/async` and provides `AsyncLogger`, `async_logger(...)`, a background `run()` worker, and bounded async queue delivery. - The current async API already supports `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, and `child(...)`. +- `shutdown()` is now the recommended way to stop the async worker. By default it waits for the queue to drain, closes the queue, and then waits for the worker to exit. +- Basic lifecycle observability is also available through `is_closed()`, `is_running()`, `has_failed()`, and `last_error()`. - The recommended startup pattern is shown in [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1). - This layer currently targets `native/llvm` only and remains isolated from the synchronous logger core. diff --git a/docs/changes/0.3.0.md b/docs/changes/0.3.0.md index 614aaf9..b9649f1 100644 --- a/docs/changes/0.3.0.md +++ b/docs/changes/0.3.0.md @@ -17,6 +17,7 @@ version 0.3.0 - feat: add `AsyncLogger`, `async_logger(...)`, `run()`, `wait_idle()`, `close()`, `pending_count()`, and `dropped_count()` on top of `moonbitlang/async` - feat: add async logger composition helpers `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, `child(...)`, and `with_timestamp(...)` - feat: add `AsyncLoggerBuildConfig`, `parse_async_logger_build_config_text(...)`, and `build_async_logger(...)` for config-driven async logger assembly +- feat: add async lifecycle helpers `shutdown()`, `is_closed()`, `is_running()`, `has_failed()`, and `last_error()` for safer worker teardown and observability - feat: expose `Record::new(...)` for adapter and integration layers - fix: repair native file backend FFI declarations so native target checks succeed again - feat: support config keys `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue` diff --git a/examples/async_basic/main.mbt b/examples/async_basic/main.mbt index 038451d..4a44413 100644 --- a/examples/async_basic/main.mbt +++ b/examples/async_basic/main.mbt @@ -21,7 +21,6 @@ async fn main { logger.info("one", fields=[@lib.field("token", "secret")]) logger.child("worker").info("two") logger.with_target("skip.demo").info("three") - logger.wait_idle() - logger.close() + logger.shutdown() }) }