BitLogger/docs/api/runtime-sink-file-runtime-state.md

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

name	group	category	update-time	description	key-word
runtime-sink-file-runtime-state	api	runtime	20260613	Read combined file and queue runtime state from a RuntimeSink when it is backed by a file sink.	runtime sink file public

Runtime-sink-file-runtime-state

Read combined file and queue runtime state from a RuntimeSink. This helper is the richest file-specific diagnostics API on direct runtime sink values.

The returned RuntimeFileState value is owned by src/file_model; this method belongs to the runtime facade layer in src/runtime and combines file snapshots from src/file_runtime.FileSink with outer queue metrics.

Interface

pub fn RuntimeSink::file_runtime_state(self : RuntimeSink) -> RuntimeFileState? {

input

• self : RuntimeSink - Runtime sink whose file runtime state should be inspected.

output

• RuntimeFileState? - Combined file and queue diagnostics when the runtime sink is file-backed, otherwise None.

Explanation

Detailed rules explaining key parameters and behaviors

• Plain File runtime variants return Some(RuntimeFileState::new(sink.state())), so queue metadata stays at its default non-queued shape.
• QueuedFile runtime variants return Some(RuntimeFileState) with the wrapped file state plus queued=true, pending_count=sink.pending_count(), and dropped_count=sink.dropped_count().
• The returned snapshot object itself is the shared @file_model.RuntimeFileState model, not a runtime-owned concrete type.
• Non-file runtime variants return None.
• This helper is richer than file_state() because it can also surface queued backlog and dropped counts.

How to Use

Here are some specific examples provided.

When Need Rich File Runtime Diagnostics

When support output should include both file and queue state:

let state = sink.file_runtime_state()

In this example, callers can inspect availability, failure counters, and queue metrics together.

When Need To Branch On File-backed Runtime Shape

When code should behave differently for file-backed direct sinks:

match sink.file_runtime_state() {
  Some(state) => ignore(state)
  None => ()
}

In this example, the optional return value reflects whether the runtime sink is file-backed.

Error Case

e.g.:

• If the runtime sink is not file-backed, the method returns None.

• If callers only need raw file status without queue context, file_state() may be the simpler API.

Notes

1. Use this helper for the richest file-backed runtime diagnostics on direct sink values.

2. It is especially useful for queued file sinks where file health and queue state both matter.