BitLogger/docs/api/runtime-sink-file-set-append-mode.md

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

name	group	category	update-time	description	key-word
runtime-sink-file-set-append-mode	api	runtime	20260707	Update the append-mode policy used by a file-backed RuntimeSink for later reopen behavior.	runtime sink file public

Runtime-sink-file-set-append-mode

Update the append-mode policy used by a file-backed RuntimeSink. This helper changes future reopen behavior without forcing an immediate reopen on the runtime sink.

Interface

pub fn RuntimeSink::file_set_append_mode(self : RuntimeSink, append : Bool) -> Bool {

input

• self : RuntimeSink - Runtime sink whose append-mode policy should change.
• append : Bool - New append-mode policy.

output

• Bool - Whether the policy update was applied.

Explanation

Detailed rules explaining key parameters and behaviors

• Plain File runtime variants update their stored append policy and return true.
• QueuedFile runtime variants forward the policy update to the wrapped inner FileSink only when no queued records are pending.
• This helper updates policy only; it does not force immediate reopen.
• Non-file runtime variants return false.
• If a queued file sink still has pending records, the update is rejected and returns false so already queued records are not later written under a different append policy than the one they were queued under.

How to Use

Here are some specific examples provided.

When Need To Change Future Reopen Behavior On A Runtime Sink

When runtime recovery should later prefer append mode explicitly:

ignore(sink.file_set_append_mode(true))

In this example, later reopen operations will use the updated append policy.

When Want To Separate Policy Mutation From Reopen Timing

When code should update policy now and reopen later:

ignore(sink.file_set_append_mode(false))
ignore(sink.file_reopen_with_current_policy())

In this example, policy mutation and reopen timing remain separate decisions on the runtime sink.

Error Case

e.g.:

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

• If callers need an immediate reopen as part of the same operation, one of the reopen helpers should be used afterward.

• If a queued file sink still has pending records, callers should flush or close it first before changing append mode.

Notes

1. This helper changes stored policy, not live file-handle state by itself.

2. On queued file sinks, clear pending records first so staged reopen policy does not retroactively affect already queued writes.