From dea63b1ed68371f06d8b02a36590727e43ec96de Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:16:18 +0800 Subject: [PATCH] :memo: document async config model aliases --- docs/api/async-logger-build-config-type.md | 74 ++++++++++++++++++++++ docs/api/async-logger-config-type.md | 74 ++++++++++++++++++++++ docs/api/index.md | 2 + 3 files changed, 150 insertions(+) create mode 100644 docs/api/async-logger-build-config-type.md create mode 100644 docs/api/async-logger-config-type.md diff --git a/docs/api/async-logger-build-config-type.md b/docs/api/async-logger-build-config-type.md new file mode 100644 index 0000000..6cbbda3 --- /dev/null +++ b/docs/api/async-logger-build-config-type.md @@ -0,0 +1,74 @@ +--- +name: async-logger-build-config-type +group: api +category: async +update-time: 20260613 +description: Public async build config alias combining the base logger config and async runtime config. +key-word: + - async + - build + - config + - public +--- + +## Async-logger-build-config-type + +`AsyncLoggerBuildConfig` is the public config object that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. It is a direct alias to the build-config model used by async builder APIs, parsers, and serializers. + +### Interface + +```moonbit +pub type AsyncLoggerBuildConfig = @utils.AsyncLoggerBuildConfig +``` + +#### output + +- `AsyncLoggerBuildConfig` - Public async build config object containing `logger` and `async_config`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a built logger instance. +- The current fields are `logger : LoggerConfig` and `async_config : AsyncLoggerConfig`. +- `AsyncLoggerBuildConfig::new(...)` constructs this type as the main handoff object for async build flows. +- `build_async_logger(...)`, `build_async_text_logger(...)`, `parse_async_logger_build_config_text(...)`, `async_logger_build_config_to_json(...)`, and `stringify_async_logger_build_config(...)` all consume or produce this same public shape. + +### How to Use + +Here are some specific examples provided. + +#### When Need One Typed Object For Full Async Logger Setup + +When sync sink setup and async runtime policy should move together through application boot code: +```moonbit +let config : AsyncLoggerBuildConfig = AsyncLoggerBuildConfig::new( + logger=@bitlogger.LoggerConfig::new(target="svc"), + async_config=AsyncLoggerConfig::new(max_pending=64), +) +``` + +In this example, both layers of logger setup are kept in one typed value. + +#### When Need To Export Or Inspect The Full Build Shape + +When application code should inspect the combined async build configuration before constructing the logger: +```moonbit +let config = AsyncLoggerBuildConfig::new(async_config=AsyncLoggerConfig::new(max_batch=4)) +println(stringify_async_logger_build_config(config, pretty=true)) +``` + +In this example, the same public config object supports both review and later build steps. + +### Error Case + +e.g.: +- `AsyncLoggerBuildConfig` itself does not have a runtime failure mode. + +- If only async runtime policy is needed and the base sync logger config is irrelevant, this type may be broader than necessary and `AsyncLoggerConfig` is the smaller fit. + +### Notes + +1. Use `AsyncLoggerBuildConfig::new(...)` when one object should carry both sync and async logger setup. + +2. Use `parse_async_logger_build_config_text(...)` when the same shape should come from JSON text instead of handwritten code. diff --git a/docs/api/async-logger-config-type.md b/docs/api/async-logger-config-type.md new file mode 100644 index 0000000..1aec4af --- /dev/null +++ b/docs/api/async-logger-config-type.md @@ -0,0 +1,74 @@ +--- +name: async-logger-config-type +group: api +category: async +update-time: 20260613 +description: Public async logger config alias used for queue, batching, linger, and flush settings. +key-word: + - async + - config + - alias + - public +--- + +## Async-logger-config-type + +`AsyncLoggerConfig` is the public config object used to describe async queue capacity, overflow behavior, batching, linger timing, and flush policy. It is a direct alias to the async config model used by `async_logger(...)`, config parsers, and async config serializers. + +### Interface + +```moonbit +pub type AsyncLoggerConfig = @utils.AsyncLoggerConfig +``` + +#### output + +- `AsyncLoggerConfig` - Public async config object containing `max_pending`, `overflow`, `max_batch`, `linger_ms`, and `flush`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a type alias, not a runtime logger handle. +- The current fields are `max_pending : Int`, `overflow : AsyncOverflowPolicy`, `max_batch : Int`, `linger_ms : Int`, and `flush : AsyncFlushPolicy`. +- `AsyncLoggerConfig::new(...)` constructs this type with the same normalization rules used by the runtime. +- `parse_async_logger_config_text(...)`, `async_logger_config_to_json(...)`, and `stringify_async_logger_config(...)` all operate on this same public config shape. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Async Runtime Policy Value + +When async queue and flush behavior should be passed around as structured config: +```moonbit +let config : AsyncLoggerConfig = AsyncLoggerConfig::new( + max_pending=64, + overflow=AsyncOverflowPolicy::DropOldest, +) +``` + +In this example, async policy remains a typed object instead of immediately becoming JSON text or a logger instance. + +#### When Need To Inspect The Config Before Building + +When one layer should read or adjust async policy before logger construction: +```moonbit +let config = AsyncLoggerConfig::new(max_batch=4, linger_ms=20) +println(stringify_async_logger_config(config, pretty=true)) +``` + +In this example, the same public config object supports both inspection and later build steps. + +### Error Case + +e.g.: +- `AsyncLoggerConfig` itself does not have a runtime failure mode. + +- Constructor normalization still applies when the value is created through `AsyncLoggerConfig::new(...)`, so very small or negative timing and batch inputs may be adjusted before later serialization or use. + +### Notes + +1. Use `AsyncLoggerConfig::new(...)` when you need a value of this type in code. + +2. Use `AsyncLoggerBuildConfig` when the async config should travel together with the base synchronous `LoggerConfig`. diff --git a/docs/api/index.md b/docs/api/index.md index 0fb6ba3..bea8b72 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -216,10 +216,12 @@ BitLogger API navigation. - [async-runtime-state.md](./async-runtime-state.md) - [async-runtime-state-to-json.md](./async-runtime-state-to-json.md) - [stringify-async-runtime-state.md](./stringify-async-runtime-state.md) +- [async-logger-config-type.md](./async-logger-config-type.md) - [async-logger-config.md](./async-logger-config.md) - [parse-async-logger-config-text.md](./parse-async-logger-config-text.md) - [async-logger-config-to-json.md](./async-logger-config-to-json.md) - [stringify-async-logger-config.md](./stringify-async-logger-config.md) +- [async-logger-build-config-type.md](./async-logger-build-config-type.md) - [parse-async-logger-build-config-text.md](./parse-async-logger-build-config-text.md) - [build-async-logger.md](./build-async-logger.md) - [build-async-text-logger.md](./build-async-text-logger.md)