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

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

name	group	category	update-time	description	key-word
runtime-sink-file-state-or-none	api	runtime	20260707	Read the current file sink snapshot from a RuntimeSink only when it is actually file-backed.	runtime sink file truthful

Runtime-sink-file-state-or-none

Read the current file sink snapshot from a RuntimeSink only when it is actually file-backed.

This is the truthful companion to file_state(). Prefer it when diagnostics or recovery logic must not confuse fallback snapshots with real file state.

Interface

pub fn RuntimeSink::file_state_or_none(self : RuntimeSink) -> FileSinkState? {

input

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

output

• FileSinkState? - Some(snapshot) when the runtime sink is file-backed, otherwise None.

Explanation

Detailed rules explaining key parameters and behaviors

• Plain File runtime variants return Some(live_snapshot).
• QueuedFile runtime variants forward the wrapped inner file sink snapshot as Some(live_snapshot).
• Non-file runtime variants return None.
• This helper is broader than individual counters or policy reads because it returns the aggregated file snapshot without fallback synthesis.

How to Use

Here are some specific examples provided.

When Need Truthful File Health Diagnostics

When support output should include file state only for real file-backed sinks:

match sink.file_state_or_none() {
  Some(state) => println(stringify_file_sink_state(state, pretty=true))
  None => ()
}

In this example, no compatibility snapshot is fabricated for non-file sinks.

When Need State Without Queue Expansion

When code only needs the file snapshot and not queue metadata:

let maybe_state = sink.file_state_or_none()

In this example, None cleanly signals missing file semantics.

Error Case

e.g.:

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

• If callers also need queue metrics for queued file sinks, prefer file_runtime_state().

Notes

1. Prefer this helper over file_state() for truthful runtime diagnostics.

2. file_state() remains available as the compatibility fallback API.