From 3a05efba6ad1ef23409e8b39435fa7d1196e52de Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Fri, 8 May 2026 20:03:30 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20async=20batching=20co?= =?UTF-8?q?nfig?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 5 +++-- docs/README-en.md | 5 +++-- docs/changes/0.3.0.md | 3 +++ 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index eadad70..3d85957 100644 --- a/README.md +++ b/README.md @@ -189,12 +189,13 @@ if native_files_supported() { - 当前 async API 已支持 `with_context_fields(...)`、`with_filter(...)`、`with_patch(...)`、`with_target(...)`、`child(...)` - 当前建议用 `shutdown()` 收口 worker；它会在默认模式下先等待队列清空，再关闭 queue 并等待 worker 退出 - 当前已支持基础生命周期观测：`is_closed()`、`is_running()`、`has_failed()`、`last_error()` +- 当前 async worker 已支持 `max_batch` 批量消费，以及 `flush=Never|Batch|Shutdown` 的基础 flush 策略 - 推荐启动方式见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1) - 这层目前仅面向 `native/llvm` backend；它是独立 adapter，不会污染现有同步 core ### Async Config -- 当前已支持 `parse_async_logger_build_config_text(...)` 与 `build_async_logger(...)` +- 当前已支持 `parse_async_logger_config_text(...)`、`stringify_async_logger_config(...)`、`parse_async_logger_build_config_text(...)` 与 `build_async_logger(...)` - JSON 顶层结构分为两个字段：`logger` 与 `async_config` -- `logger` 完全复用同步 `LoggerConfig` 的 schema；`async_config` 当前支持 `max_pending` 与 `overflow` +- `logger` 完全复用同步 `LoggerConfig` 的 schema；`async_config` 当前支持 `max_pending`、`overflow`、`max_batch` 与 `flush` - 当前推荐写法可直接参考 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1) diff --git a/docs/README-en.md b/docs/README-en.md index b1f5460..61faaf8 100644 --- a/docs/README-en.md +++ b/docs/README-en.md @@ -178,12 +178,13 @@ if native_files_supported() { - 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 async worker now supports batched queue draining via `max_batch` and basic flush policies through `flush=Never|Batch|Shutdown`. - 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. ### Async Config -- `parse_async_logger_build_config_text(...)` and `build_async_logger(...)` are now available. +- `parse_async_logger_config_text(...)`, `stringify_async_logger_config(...)`, `parse_async_logger_build_config_text(...)`, and `build_async_logger(...)` are now available. - The JSON root is split into `logger` and `async_config`. -- `logger` fully reuses the synchronous `LoggerConfig` schema, while `async_config` currently supports `max_pending` and `overflow`. +- `logger` fully reuses the synchronous `LoggerConfig` schema, while `async_config` currently supports `max_pending`, `overflow`, `max_batch`, and `flush`. - The recommended config-driven startup flow is shown in [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1). diff --git a/docs/changes/0.3.0.md b/docs/changes/0.3.0.md index b9649f1..170b814 100644 --- a/docs/changes/0.3.0.md +++ b/docs/changes/0.3.0.md @@ -18,6 +18,8 @@ version 0.3.0 - 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: add `parse_async_logger_config_text(...)`, `stringify_async_logger_config(...)`, and build-config serialization helpers for async config roundtrip support +- feat: add async batching controls `max_batch` and `flush=Never|Batch|Shutdown` for queue draining and flush timing - 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` @@ -32,6 +34,7 @@ version 0.3.0 - test: cover config-built queued text logger flushing and pending count behavior - test: cover partial drain behavior for config-built queued logger - test: cover dropped-count reporting for bounded config-built queue +- test: add async logger lifecycle, config roundtrip, and batching/flush policy test seeds - build: verify `bitlogger_async --target native` and `examples/async_basic --target native` compile successfully ### Example