BitLogger/docs/api/configured-logger-file-flush.md

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

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

Configured-logger-file-flush

Flush the file sink behind a ConfiguredLogger. This helper is the file-specific runtime flush surface for config-built file loggers.

Interface

pub fn ConfiguredLogger::file_flush(self : ConfiguredLogger) -> Bool {}

input

• self : ConfiguredLogger - Config-driven runtime logger 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 sinks forward directly to file flush behavior through the wrapped RuntimeSink.
• Queued file sinks first drain queued records, then flush the wrapped inner file sink.
• For queued file sinks, 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 queued file sinks, this step may also be the point where queued records finally hit the inner file sink, so failure counters can change here even if earlier log calls only queued records.
• Non-file sinks return false.
• This helper is narrower than generic flush() because it targets file sink behavior specifically.
• After a file-backed configured logger has already cleared its file handle, later file_flush() calls return false.

How to Use

Here are some specific examples provided.

When Need Explicit File Durability Steps

When a config-built file logger should flush to disk explicitly:

ignore(logger.file_flush())

In this example, the file-backed runtime sink is flushed directly through the configured logger.

When Need A File-specific Success Flag

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

let ok = logger.file_flush()

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

Error Case

e.g.:

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

• If the file handle was already closed earlier through this logger or another facade sharing the same wrapped runtime sink 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 still mean queue consumption happened but file delivery observed a new failure.

Notes

1. Prefer this helper when the configured sink is known to be file-backed.

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

3. Library or application facades derived from the same configured runtime logger still observe the same underlying file-flush availability state.