Module filelock 

One writer at a time on a file that two parts of Sioul change: the window marks a dose in the doses’ record while the sharing writes in it what your other devices marked. One writing an older copy over the other would lose a dose taken, and the sharing would then take it out on every device. An advisory lock on a hidden file beside it (.<name>.lock, which the sharing never carries), held while the file is read, changed and written.

Structs

Read

A TOML file as it was read, kept beside the state read from it (a field that serde skips): saved, only what changed since it was read is written over what the file holds then (save_merged), so that a change your other devices brought in meanwhile (the sharing writes under the same lock) stays. Equal to any other, so that it changes no comparison of the state.

Constants

HELD 🔒

The locks this thread holds: one taken again inside (a writer calling another of the same file) is already held, never waited for.

Statics

EMPTY 🔒

Functions

has_lock

Whether a writer of path takes its lock here (its hidden lock file is there): for files the sharing writes without it otherwise (a note, which most writers do not lock), so that a file one of Sioul’s own writers changes under its lock (the letters’ list) is written under it too.

lock_path 🔒

merge 🔒

What changed from base to new, set over current. A list or a table on one side only stands against an empty one on the other: emptied, it takes out what it held, never what another writer added since; filled from nothing, it adds to what another writer put there.

replace

Bytes written beside path under a hidden name of their own, then renamed over it: a reader never finds the file empty or half written (the sharing reads without the lock), and a full disk leaves the file as it was rather than empty (review of 5 October 2026, F10).

save_merged

state written into path, under its lock, the file read again first: what changed from read (the file as it was read) to state is set over what the file holds now, field by field (a list as a set: what was added added, what was taken out taken out; a list or table missing on one side is an empty one, as a state skips an empty field); the rest stays as the file holds it. A file missing when it was read is read as empty. Nothing read before that could be merged (a file that did not read): state whole. Written beside, then moved.

save_merged_by

The same, settle then given the merged table and the file as it was just before (none when missing): for what a field-by-field merge cannot say (a mark that must never go backwards).

with_lock

f, with the lock on path held: other threads and programs wait for it. Where no lock can be taken (a folder not writable), f runs all the same: writing it fails there anyway. Taken again by the thread holding it, it is held already.