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

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

name	group	category	update-time	description	key-word
runtime-sink-progress	api	runtime	20260707	Public structured generic progress snapshot used by RuntimeSink and ConfiguredLogger flush or drain helpers.	runtime progress flush public

Runtime-sink-progress

RuntimeSinkProgress is the public structured progress snapshot returned by the truthful generic flush_progress(...) and drain_progress(...) helpers. It separates queue advancement from plain file flush fallback steps so callers do not have to infer mixed Int semantics from flush() or drain() alone.

Interface

pub struct RuntimeSinkProgress {
  queue_advanced_count : Int
  file_flush_step_count : Int
  queue_backed : Bool
  file_backed : Bool
}

output

• RuntimeSinkProgress - Public generic progress snapshot containing queue advancement count, plain-file flush fallback count, and runtime-shape flags.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a public root struct, not a type alias.
• queue_advanced_count reports how many queued records were consumed by a queue-backed runtime helper call.
• file_flush_step_count reports the plain-file fallback step count used by generic helpers on non-queued file sinks, currently 1 for a successful FileSink::flush() and 0 otherwise.
• queue_backed reports whether the runtime sink shape was queue-backed during the helper call.
• file_backed reports whether the runtime sink shape was file-backed during the helper call.
• For queued file sinks, queue_advanced_count may be positive while file_flush_step_count stays 0; delayed file failures still belong to file_flush() and failure-counter inspection rather than to this generic progress snapshot.

How to Use

Here are some specific examples provided.

When Need Truthful Generic Runtime Progress

When code should inspect generic flush or drain work without guessing what one Int means:

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

In this example, queue progress stays explicit instead of being folded into a compatibility count.

When Need To Distinguish Plain File Fallback From Queue Work

When generic runtime support code should tell plain-file fallback apart from queued advancement:

let progress = logger.drain_progress()
if progress.file_backed && !progress.queue_backed {
  println(progress.file_flush_step_count)
}

In this example, the caller can recognize the plain-file generic fallback path directly.

Error Case

e.g.:

• RuntimeSinkProgress itself does not have a runtime failure mode.

• This type reports generic progress only; it does not prove durable file delivery.

• If callers need file-specific success semantics, file_flush() is still the narrower API.

Notes

1. Prefer this structured result over the legacy Int returned by flush() and drain() when new code can choose.

2. For queued file sinks, combine this snapshot with file_flush(), file_runtime_state(), or file failure counters when file outcome matters.