From a17f50db887b5d49a98d7e396054231585c1930e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:35:36 +0800 Subject: [PATCH] :memo: document runtime sink control methods --- docs/api/index.md | 3 ++ docs/api/runtime-sink-close.md | 75 +++++++++++++++++++++++++++++++++ docs/api/runtime-sink-drain.md | 75 +++++++++++++++++++++++++++++++++ docs/api/runtime-sink-flush.md | 76 ++++++++++++++++++++++++++++++++++ 4 files changed, 229 insertions(+) create mode 100644 docs/api/runtime-sink-close.md create mode 100644 docs/api/runtime-sink-drain.md create mode 100644 docs/api/runtime-sink-flush.md diff --git a/docs/api/index.md b/docs/api/index.md index 303a312..aa259bf 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -342,6 +342,9 @@ BitLogger API navigation. ## Configured logger runtime +- [runtime-sink-flush.md](./runtime-sink-flush.md) +- [runtime-sink-drain.md](./runtime-sink-drain.md) +- [runtime-sink-close.md](./runtime-sink-close.md) - [configured-logger.md](./configured-logger.md) - [configured-logger-flush.md](./configured-logger-flush.md) - [configured-logger-drain.md](./configured-logger-drain.md) diff --git a/docs/api/runtime-sink-close.md b/docs/api/runtime-sink-close.md new file mode 100644 index 0000000..1308175 --- /dev/null +++ b/docs/api/runtime-sink-close.md @@ -0,0 +1,75 @@ +--- +name: runtime-sink-close +group: api +category: runtime +update-time: 20260613 +description: Close a RuntimeSink and report whether the underlying sink performed a successful close action. +key-word: + - runtime + - sink + - lifecycle + - public +--- + +## Runtime-sink-close + +Close a `RuntimeSink`. This is the direct runtime sink lifecycle API behind configured logger close behavior. + +### Interface + +```moonbit +pub fn RuntimeSink::close(self : RuntimeSink) -> Bool { +``` + +#### input + +- `self : RuntimeSink` - Runtime sink whose underlying resources should be closed. + +#### output + +- `Bool` - Whether the concrete runtime sink reported a successful close action. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain console-style runtime sinks return `true` because they do not have a meaningful close step here. +- Plain file runtime sinks forward directly to `FileSink::close()`. +- Queued file runtime sinks close the wrapped file sink rather than only the queue wrapper. +- Queue-wrapped console-style runtime sinks return `true` as a no-op success. +- This method is the direct sink-level API used by `ConfiguredLogger::close(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Runtime Teardown + +When code owns a `RuntimeSink` and should release its underlying resources: +```moonbit +ignore(sink.close()) +``` + +In this example, sink teardown happens without going through a logger wrapper. + +#### When Need To Observe Close Outcome + +When application code wants a success flag from the direct runtime sink: +```moonbit +let closed = sink.close() +``` + +In this example, callers can branch on the reported close result. + +### Error Case + +e.g.: +- If the runtime sink shape has no real close action, the method may still return `true` as a no-op success. + +- If callers know they are working with a direct `FileSink`, `FileSink::close()` is the narrower API. + +### Notes + +1. Use this helper when code is managing a `RuntimeSink` value directly. + +2. `ConfiguredLogger::close(...)` is the higher-level wrapper for config-built loggers. diff --git a/docs/api/runtime-sink-drain.md b/docs/api/runtime-sink-drain.md new file mode 100644 index 0000000..8e1a5eb --- /dev/null +++ b/docs/api/runtime-sink-drain.md @@ -0,0 +1,75 @@ +--- +name: runtime-sink-drain +group: api +category: runtime +update-time: 20260613 +description: Drain queued work from a RuntimeSink with an optional item limit. +key-word: + - runtime + - sink + - queue + - public +--- + +## Runtime-sink-drain + +Drain queued work from a `RuntimeSink`. This helper is useful when code owns a runtime sink directly and needs controlled queue progress. + +### Interface + +```moonbit +pub fn RuntimeSink::drain(self : RuntimeSink, max_items~ : Int = -1) -> Int { +``` + +#### input + +- `self : RuntimeSink` - Runtime sink whose queued work should be drained. +- `max_items : Int` - Optional upper bound on drained queued items. Negative values mean no explicit bound. + +#### output + +- `Int` - Number of drained items, or the fallback flush count for plain file sinks. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-wrapped runtime sinks forward to the wrapped queue sink's `drain(...)` behavior. +- Plain file runtime sinks fall back to `FileSink::flush()` behavior and return `1` or `0`. +- Plain console-style runtime sinks return `0` because they do not own a drainable queue. +- This method is the direct sink-level API used by `ConfiguredLogger::drain(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Bounded Queue Progress + +When direct queue-backed runtime work should be advanced in chunks: +```moonbit +let drained = sink.drain(max_items=16) +``` + +In this example, callers cap how much queued work is processed in one step. + +#### When Need Full Manual Drain + +When a runtime queue should be emptied without an explicit item cap: +```moonbit +ignore(sink.drain()) +``` + +In this example, the runtime sink drains as much queued work as its concrete variant allows. + +### Error Case + +e.g.: +- If the runtime sink is not queue-backed, the result may be `0` or file-flush fallback behavior. + +- If callers only need generic flush semantics, `flush()` may be the simpler API. + +### Notes + +1. Prefer this helper when queue progress should be bounded or directly observed. + +2. `ConfiguredLogger::drain(...)` is the higher-level wrapper for config-built loggers. diff --git a/docs/api/runtime-sink-flush.md b/docs/api/runtime-sink-flush.md new file mode 100644 index 0000000..88ca3e2 --- /dev/null +++ b/docs/api/runtime-sink-flush.md @@ -0,0 +1,76 @@ +--- +name: runtime-sink-flush +group: api +category: runtime +update-time: 20260613 +description: Flush a RuntimeSink and return how many queued or file-backed operations were advanced. +key-word: + - runtime + - sink + - flush + - public +--- + +## Runtime-sink-flush + +Flush a `RuntimeSink` and return how much work was advanced. This is the direct runtime control API behind configured logger flush behavior. + +### Interface + +```moonbit +pub fn RuntimeSink::flush(self : RuntimeSink) -> Int { +``` + +#### input + +- `self : RuntimeSink` - Runtime sink whose pending file or queue work should be flushed. + +#### output + +- `Int` - Count of advanced operations as reported by the concrete runtime sink variant. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain console-style runtime sinks return `0` because they do not keep explicit buffered flush state here. +- Plain file runtime sinks call `FileSink::flush()` and convert the boolean result into `1` or `0`. +- Queue-wrapped runtime sinks forward to the wrapped queue sink's `flush()` behavior. +- This method is the direct sink-level API used by `ConfiguredLogger::flush(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Runtime Flush Control + +When code is working with a `RuntimeSink` value directly instead of going through `ConfiguredLogger`: +```moonbit +let flushed = sink.flush() +``` + +In this example, the runtime sink reports how much flush work was advanced. + +#### When Need Queue Or File Progress Visibility + +When support code should observe whether a direct flush request did useful work: +```moonbit +if sink.flush() > 0 { + () +} +``` + +In this example, the return value reflects whether queue draining or file flushing advanced any work. + +### Error Case + +e.g.: +- If the runtime sink shape has no flushable state, the method may simply return `0`. + +- If callers need bounded queue progress, `drain(...)` is the better API. + +### Notes + +1. Use this helper when direct runtime sink flushing matters. + +2. `ConfiguredLogger::flush(...)` is the higher-level wrapper for config-built loggers.