Separate visibility from crash survival
Updating a configuration has two different failure questions: can a reader see partially written content, and can the update disappear after a restart? The first concerns when names and data become visible; the second concerns what reached durable storage. We examine writing a temporary file in the same directory, synchronizing it, replacing the name and synchronizing the directory. Atomic name replacement and crash durability are separate properties.
The executable example checks normal API completion and resulting visibility. It injects neither an OS crash nor power loss, so it does not measure media durability. The planned crash experiment is explicitly narrowed to normal synchronization steps and a state-history model in this environment. Stronger recovery claims require the actual filesystem, mount configuration, storage device and synchronization contract to be tested together.
Follow each buffering layer
A successful write can still leave data in language buffering or OS cache before durable storage. Python flush advances language-buffered data downward; it is not by itself a media-durability certificate. The example then calls os.fsync on the file descriptor and lets failure surface as an exception. Record successful completion, not merely that a synchronization function name appears in the source.
Closing a file does not universally substitute for every durability step. Synchronizing file data also does not automatically synchronize the containing directory entry that names it. Track the name-to-file relationship separately from file contents. Consult the Linux fsync contract for the actual descriptor type and map each code operation to that boundary. This prevents several different flush and close events from being compressed into one vague statement that saving finished.
| Operation | Boundary examined |
|---|---|
| Write temporary file | Prepare new content under another name |
| fsync temporary file | File synchronization API |
| replace on same filesystem | Atomic name replacement |
| fsync parent directory | Directory synchronization including the name change |
Prepare the replacement beside the target
Incrementally overwriting config can expose partial new contents to concurrent readers. Instead write the complete next file, flush language buffering, synchronize its descriptor and only then replace the config name. Keeping both in one directory avoids confusing this sequence with a cross-filesystem move. After successful replacement, a newly opened target should expose the new contents.
An existing descriptor for the old file does not necessarily switch to the new object when the directory name changes. Name lookup and already-open references are separate. A configuration-reload design must state when readers reopen and how long old in-memory values may remain usable. One atomic name change does not synchronize every application cache or previously opened reader. Explain exactly which observer sees which version at each event.
Synchronize the directory and verify normal results
After replacing the name, open the parent directory with O_DIRECTORY and fsync its descriptor. A finally block closes that descriptor, and a temporary-directory context removes test files. Assert that config now reads new and the temporary name is absent. This is one replacement in one directory, not a transaction spanning several files or directories.
Successful execution establishes that these API calls returned normally in this environment and that the visible result matched expectations. It does not observe device behavior after immediate power loss. The output states that limitation. Preserve OS, Python version, exit status and complete output under an accurate test label. Calling this a successful crash-injection experiment would attribute an event to the run that never occurred.
import os,tempfile
from pathlib import Path
with tempfile.TemporaryDirectory() as d:
directory=Path(d);target=directory/'config';target.write_bytes(b'old')
with open(directory/'next','wb') as f:
f.write(b'new');f.flush();os.fsync(f.fileno())
os.replace(directory/'next',target)
fd=os.open(directory,os.O_RDONLY|os.O_DIRECTORY)
try:os.fsync(fd)
finally:os.close(fd)
assert target.read_bytes()==b'new' and not (directory/'next').exists()
print('write, flush, file fsync, replace, directory fsync returned; visible=new')
print('normal execution only; no OS crash or power-loss injection')
Limit expectations by interruption boundary
A useful state table separates before writing, written-but-unsynchronized, file-synchronized-before-replace, replaced-before-directory-sync and fully completed. Put ordinary name visibility and post-failure possibilities in different columns. For example, synchronizing new file data before replacement still leaves the public config name referring to the old version. Durable data and publication through a name are different steps.
Without the environment's actual guarantees, do not assign one universal recovered state to every interruption. Killing only a process leaves OS cache alive and therefore does not simulate power-loss durability. Losing a medium and restoring backup is another experiment. Label the failed component explicitly as process, OS or storage. The word crash alone is too imprecise to support a recovery guarantee.
Extend the protocol only with explicit new requirements
Two configuration files replaced separately can expose mixed versions. A manifest or generation-directory protocol needs to define how readers select one consistent generation. Preserving owner, permissions or extended attributes also adds steps to prepare and verify the temporary object. The example's old/new content assertion does not cover those metadata or multi-file requirements.
Capacity exhaustion and I/O errors must stop progress before publishing incomplete data. Check successful completion before replacing the public name. Retaining an old file is not a reason to ignore every failure or tell the caller an update succeeded. Place the success response after the synchronization boundary required by the application's durability contract. Visibility, metadata and the meaning of acknowledged success need to agree; none is supplied automatically by the short replacement example.
Distinguish newly opened readers from retained references
Separate reader R1 opening config before replacement from R2 opening the name afterward. R2 seeing new content does not imply R1's existing descriptor simultaneously switched objects. State which observation the atomic name replacement governs. An application holding parsed configuration in memory adds another reload boundary.
A two-reader extension should coordinate preparation and replacement with an explicit channel, recording name, open time and observed contents. The supplied executable only checks one new read after normal replacement; it does not already contain that concurrent experiment. Do not invent extra observations inside an old evidence record. Save an added test separately. Visibility of a new name and completion of every reader's migration are different, a distinction also useful for caches and distributed placement cutovers.
Place the success acknowledgment at a defined boundary
An update API must map its success response to the promised state: accepted in memory, written to a file, name replaced or required synchronization completed. Those are different acknowledgments. If a later step fails, ask whether an earlier success still satisfies the contract. Moving acknowledgment earlier for performance can change the guarantee rather than merely optimize implementation.
On failure, distinguish old content still visible, new content visible with unresolved durability, and a remaining temporary object. A retry also needs a target name and generation rule. The example's finally removes only its own temporary area; it does not define when a product may delete recovery evidence or old versions. Align response and recovery information with one explicit state machine so the implementation can explain an interrupted update rather than label every partial outcome simply failed.
Exercise: state exactly which boundary was checked
If execution stops after synchronizing the temporary file but before replacement, ordinary lookup of config still refers to the old content. If the new content is readable after replacement, that observation alone does not establish recovery after an OS crash. Directory synchronization, environment guarantees and actual fault injection are separate pieces of evidence.
Moving the temporary file to another filesystem also changes the assumed operation; the same-directory replacement contract no longer follows unchanged. Finish by listing what the run established: normal synchronization calls succeeded, new content was visible and the temporary name disappeared. OS crash, power loss and complete medium-loss recovery were not tested. Precise boundary statements are the learning goal, rather than giving every successful file write the same broad label of crash safety.