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

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

name	group	category	update-time	description	key-word
runtime-sink-file-flush	api	runtime	20260707	Flush the file sink behind a RuntimeSink when one is present, with queued-file success tied to both queue drain and file flush outcome.	runtime sink file public

Runtime-sink-file-flush

Flush the file sink behind a RuntimeSink. This helper is the direct file-specific runtime flush surface for code that owns a sink value instead of a ConfiguredLogger.

Interface

pub fn RuntimeSink::file_flush(self : RuntimeSink) -> Bool {

input

• self : RuntimeSink - Runtime sink whose file sink should be flushed.

output

• Bool - Whether the file-specific flush path succeeded.

Explanation

Detailed rules explaining key parameters and behaviors

• Plain File runtime variants forward directly to FileSink::flush().
• QueuedFile runtime variants first drain the queue, then flush the wrapped file sink.
• For QueuedFile, the returned Bool is true only when all queued records were consumed, the final file flush succeeded, and no new write, flush, or rotation failures were observed during that flush path.
• For QueuedFile, this step may also be the point where queued records finally reach the inner file sink, so failure counters can change here even if earlier log(...) calls only enqueued records.
• Non-file runtime variants return false.
• After a file-backed runtime sink has already cleared its handle, later file_flush() calls return false.

How to Use

Here are some specific examples provided.

When Need Explicit Direct File Durability Steps

When code holds a file-backed RuntimeSink directly and should flush it explicitly:

ignore(sink.file_flush())

In this example, the runtime sink attempts to flush its file-backed output directly.

When Need A File-specific Success Flag

When code should branch on the outcome of a direct file flush:

let ok = sink.file_flush()

In this example, callers can distinguish file-specific flush success from a non-file sink shape.

Error Case

e.g.:

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

• If the file handle was already closed earlier through this runtime sink or another facade sharing the same underlying file-backed state, the method returns false.

• If callers want generic queue or sink advancement instead of file-specific behavior, flush() is the broader API.

• On queued file sinks, a false result may mean queue consumption happened but file delivery still observed a new failure.

Notes

1. Prefer this helper when direct runtime code specifically cares about file flush behavior.

2. Queued file sinks may perform both queue drain work and file flush work here, including surfacing delayed failures from previously queued records.

3. Library or application facades that share the same wrapped file-backed runtime sink still observe the same flush availability state.