BitLogger/docs/api/runtime-sink-drain-progress.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
runtime-sink-drain-progress	api	runtime	20260707	Return a structured generic drain progress snapshot for a RuntimeSink without collapsing queue and plain-file fallback semantics into one Int.	runtime sink drain public

Runtime-sink-drain-progress

Return a structured generic drain progress snapshot for a RuntimeSink. This is the recommended truthful generic runtime drain helper when callers need bounded or full queue progress without relying on the compatibility Int returned by drain().

Interface

pub fn RuntimeSink::drain_progress(
  self : RuntimeSink,
  max_items~ : Int = -1,
) -> RuntimeSinkProgress {

input

• self : RuntimeSink - Runtime sink whose generic drain progress should be observed.
• max_items : Int - Optional upper bound on drained queued items. Negative values mean no explicit bound.

output

• RuntimeSinkProgress - Structured progress snapshot separating queue advancement from plain-file flush fallback steps.

Explanation

Detailed rules explaining key parameters and behaviors

• Queue-wrapped runtime sinks report consumed queued items through queue_advanced_count and honor max_items.
• Plain file runtime sinks still follow the generic fallback path and report FileSink::flush() as file_flush_step_count 1 or 0.
• Plain console-style runtime sinks return a zeroed snapshot because they do not own a drainable queue here.
• Queued file runtime sinks report queue advancement, while delayed file delivery failures still belong to file failure counters and file_flush().
• This helper preserves the old runtime behavior but makes the meaning explicit in the result shape.
• drain() remains available as the legacy convenience wrapper that sums the fields back into one count.

How to Use

Here are some specific examples provided.

When Need Recommended Bounded Generic Drain Progress

When code should observe one bounded drain step without mixing units:

let progress = sink.drain_progress(max_items=16)

In this example, queue progress and plain-file fallback stay separated.

When Need A Full Manual Generic Drain Snapshot

When support code should empty queued work and keep runtime-shape context:

let progress = sink.drain_progress()

In this example, the caller can inspect both the count and the runtime shape afterwards.

Error Case

e.g.:

• If the runtime sink is not queue-backed, the snapshot may stay zeroed or use the plain-file fallback field.

• If callers want file-specific success semantics after queue delivery, file_flush() is the better API.

Notes

1. Prefer drain_progress() over drain() in new generic runtime code.

2. Use pending_count() together with this helper when remaining backlog must also be observed.