♻️ Harden async logger lifecycle semantics

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
 

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] {

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")
+}

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.
 

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`

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()
   })
 }