From 86b99fe0042a54eca857e41c3d70a04f551258b2 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:40:26 +0800 Subject: [PATCH] :memo: document buffered sink methods --- docs/api/buffered-sink-flush.md | 71 +++++++++++++++++++++++ docs/api/buffered-sink-pending-count.md | 75 +++++++++++++++++++++++++ docs/api/index.md | 2 + 3 files changed, 148 insertions(+) create mode 100644 docs/api/buffered-sink-flush.md create mode 100644 docs/api/buffered-sink-pending-count.md diff --git a/docs/api/buffered-sink-flush.md b/docs/api/buffered-sink-flush.md new file mode 100644 index 0000000..05fb0b7 --- /dev/null +++ b/docs/api/buffered-sink-flush.md @@ -0,0 +1,71 @@ +--- +name: buffered-sink-flush +group: api +category: sink +update-time: 20260613 +description: Flush buffered records from a BufferedSink into its wrapped sink. +key-word: + - sink + - buffer + - flush + - public +--- + +## Buffered-sink-flush + +Flush buffered records from a `BufferedSink[S]` into its wrapped sink. This is the direct sink-level batching control API for simple synchronous buffering. + +### Interface + +```moonbit +pub fn[S : Sink] BufferedSink::flush(self : BufferedSink[S]) -> Unit { +``` + +#### input + +- `self : BufferedSink[S]` - Buffered sink whose pending records should be forwarded to the wrapped sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- If the buffer is empty, the method does nothing. +- When buffered records exist, they are copied into a temporary `pending` array, the live buffer is cleared, and each record is then written to the wrapped sink in order. +- This helper drains only the local buffer; any later behavior still depends on the wrapped sink `S`. +- The method does not return a count or success flag. + +### How to Use + +Here are some specific examples provided. + +#### When Need Explicit Batch Delivery + +When a buffered sink should forward pending records before the threshold is reached: +```moonbit +sink.flush() +``` + +In this example, callers force buffered records to be written to the wrapped sink immediately. + +#### When Need A Manual Flush Barrier + +When tests or synchronous code want buffering but still need a deliberate release point: +```moonbit +let sink = buffered_sink(console_sink(), flush_limit=4) +sink.flush() +``` + +In this example, the buffered sink exposes a direct batching barrier without using queue semantics. + +### Error Case + +e.g.: +- If the wrapped sink's write behavior fails or has side effects, this helper does not add an extra reporting layer on top of `S`. + +- If callers need a count-returning drain API with drop tracking, `QueuedSink::flush()` or `QueuedSink::drain()` may fit better. + +### Notes + +1. Use this helper when code owns a `BufferedSink` directly and wants explicit control over when buffered records are forwarded. + +2. Automatic flush still happens when buffered record count reaches `flush_limit` during writes. diff --git a/docs/api/buffered-sink-pending-count.md b/docs/api/buffered-sink-pending-count.md new file mode 100644 index 0000000..6363334 --- /dev/null +++ b/docs/api/buffered-sink-pending-count.md @@ -0,0 +1,75 @@ +--- +name: buffered-sink-pending-count +group: api +category: sink +update-time: 20260613 +description: Read the current buffered-record count from a BufferedSink. +key-word: + - sink + - buffer + - queue + - public +--- + +## Buffered-sink-pending-count + +Read the current buffered-record count from a `BufferedSink[S]`. This is the direct sink-level metric for how many records are still waiting in the in-memory buffer. + +### Interface + +```moonbit +pub fn[S] BufferedSink::pending_count(self : BufferedSink[S]) -> Int { +``` + +#### input + +- `self : BufferedSink[S]` - Buffered sink whose current in-memory backlog should be inspected. + +#### output + +- `Int` - Current number of buffered records. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The return value is `self.buffer.val.length()` at the time of the call. +- This is a point-in-time metric and may change immediately after it is read. +- It reflects buffered records that have not yet been flushed to the wrapped sink. +- This helper does not mutate the sink. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Buffer Backlog Visibility + +When code is working with a `BufferedSink` value directly and wants to observe pending buffered records: +```moonbit +let pending = sink.pending_count() +``` + +In this example, callers can inspect the current in-memory backlog without touching the wrapped sink. + +#### When Verify Manual Flush Progress + +When explicit flush steps should be checked operationally: +```moonbit +ignore(sink.flush()) +ignore(sink.pending_count()) +``` + +In this example, the metric helps verify whether buffered records were forwarded out of the local buffer. + +### Error Case + +e.g.: +- This helper does not have a normal failure mode; it only reads current buffer length. + +- If callers need overflow-aware backlog semantics instead of simple buffering, `QueuedSink::pending_count()` is the better API. + +### Notes + +1. Use this helper for direct visibility into simple synchronous buffering. + +2. Pair it with `flush()` when inspecting whether batched writes have been forwarded. diff --git a/docs/api/index.md b/docs/api/index.md index 3c4bcd9..88c7312 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -131,6 +131,8 @@ BitLogger API navigation. - [split-by-level.md](./split-by-level.md) - [buffered-sink.md](./buffered-sink.md) - [buffered-sink-type.md](./buffered-sink-type.md) +- [buffered-sink-pending-count.md](./buffered-sink-pending-count.md) +- [buffered-sink-flush.md](./buffered-sink-flush.md) - [queued-sink.md](./queued-sink.md) - [queued-sink-type.md](./queued-sink-type.md) - [queue-overflow-policy.md](./queue-overflow-policy.md)