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

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

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

Runtime-sink-flush-progress

Return a structured generic flush progress snapshot for a RuntimeSink. This is the recommended truthful generic runtime flush helper when callers need to observe progress without relying on the compatibility Int returned by flush().

Interface

pub fn RuntimeSink::flush_progress(self : RuntimeSink) -> RuntimeSinkProgress {

input

• self : RuntimeSink - Runtime sink whose generic flush progress should be observed.

output

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

Explanation

Detailed rules explaining key parameters and behaviors

• Plain console-style runtime sinks return a zeroed snapshot with queue_backed=false and file_backed=false.
• Plain file runtime sinks call FileSink::flush() and report the fallback result through file_flush_step_count as 1 or 0.
• Queue-wrapped runtime sinks report consumed queued items through queue_advanced_count.
• Queued file runtime sinks still report generic progress as queue advancement, while file_backed=true marks that the queue drains into a file sink.
• This helper does not convert different runtime-shape behaviors into one ambiguous compatibility Int.
• flush() 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 Generic Flush Progress

When direct runtime code should inspect flush progress explicitly:

let progress = sink.flush_progress()

In this example, the caller gets a structured snapshot instead of a mixed Int.

When Need Queue-aware Branching During Flush

When generic runtime support code should react differently for queue-backed and plain-file sinks:

let progress = sink.flush_progress()
if progress.queue_backed {
  println(progress.queue_advanced_count)
}

In this example, queue advancement is explicit and does not need to be inferred from runtime shape.

Error Case

e.g.:

• If the runtime sink shape has no flushable state, the snapshot simply reports zero counts.

• If callers need file-specific success semantics rather than generic runtime progress, file_flush() is the better API.

Notes

1. Prefer flush_progress() over flush() in new generic runtime code.

2. Use flush() only when older compatibility code still expects one numeric count.