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

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

name	group	category	update-time	description	key-word
runtime-file-state	api	runtime	20260613	Public combined file-and-queue runtime state alias used by configured logger diagnostics.	runtime file state public

Runtime-file-state

RuntimeFileState is the public snapshot object that combines file state with queue runtime context for configured loggers. It is a direct alias to the runtime model used by configured file diagnostics and JSON export helpers.

Interface

pub type RuntimeFileState = @utils.RuntimeFileState

output

• RuntimeFileState - Public combined runtime snapshot containing a file snapshot plus queue metadata such as queued, pending_count, and dropped_count.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a type alias, not a live runtime controller.
• The current fields are file : FileSinkState, queued : Bool, pending_count : Int, and dropped_count : Int.
• This type is returned by ConfiguredLogger::file_runtime_state() when the configured sink can expose file runtime context.
• It is broader than FileSinkState because it also reports whether queue wrapping is involved and how the queue is behaving.

How to Use

Here are some specific examples provided.

When Need Combined File And Queue Diagnostics

When a configured logger may wrap a file sink in a queue:

match logger.file_runtime_state() {
  Some(snapshot) => println(snapshot.pending_count)
  None => ()
}

In this example, queue backlog can be inspected alongside the embedded file state.

When Need A Single Exportable Runtime Snapshot

When runtime support output should include both file and queue context:

match logger.file_runtime_state() {
  Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
  None => ()
}

In this example, one typed object covers both the file snapshot and queue counters.

Error Case

e.g.:

• RuntimeFileState itself does not have a runtime failure mode.

• If the configured logger is not file-backed, file_runtime_state() may return None instead of producing this snapshot.

Notes

1. Use this type when queued-file diagnostics matter, not just raw file status.

2. Use runtime_file_state_to_json(...) or stringify_runtime_file_state(...) when the snapshot should be exported.