Module devices 

Each device says how it is, in the sharing folder (docs/database.md, “Devices”): when it last started, when it last closed cleanly, whether it is working now, when it last read the others and when it last wrote its own. The doses rely on it (docs/health.md, “Knowing”): a device that closed cleanly after its last export holds no answer the others have not read; one still working may.

One file per device, <folder>/devices/<id>.device, written by that device only, sealed like the claims (bound to the device it names), its size changed at each writing (share::pad_for: some sync apps tell a change by its size alone), a few hundred bytes, never read past 64 KiB. The same, privately, in $XDG_STATE_HOME/sioul/share/device.toml, never shared, changed under a lock and read just before (change): two processes of Sioul (the window, a phone’s background service) never write an older state back over the other’s.

Written into the folder only when the others need it (change): at each export while the device is in use (working: the doses need its exports fresh, sioul_core::health::FRESH), when anything else it says changes (its session, how far it wrote, whether it shares its doses, its build), when the folder’s copy is not the one it wrote, and once an hour (RESTATED). A device put away whose exchanges find nothing new writes nothing there: a phone’s background step every few minutes would otherwise rewrite it, and its sync app send it, each time.

The identity is the sharing’s own (share::Here::id, a UUID made once per machine), never the host name, which can change or be another’s too.

Structs

Entry

A device’s entry: what it says of itself, its times on its own clock (Unix seconds).

Published 🔒

What this device last wrote into the folder, kept beside its own entry and never shared (published_path): what it said then, its exchanges’ times left out (steady), the file as written (its size and time), where, under which key (sealed_with: the folder sealed again, it is written again at once), and when.

Constants

COMPUTER

PHONE

RESTATED

How long a device not in use leaves its entry in the folder as it is, at most, while only the times of its exchanges change (seconds): restated then, so that the others still hear of it (Settings ▸ Your folder and sharing, the texts’ “last shared”, sioul_core::health::SILENT_DAYS). The doses never wait for it: a device put away is known by its close and how far it wrote, both written at once.

Functions

all

Every device’s entry that reads, and the ids of the devices whose file does not (its seal not arrived, damaged, another key’s, written by an older Sioul’s sharing that knows no working): those are no entry, never one read as closed. Files of other names (a sync app’s conflicted copies, half-written ones) are not read. Of an entry fetched from the server too (remote::overlay), the later of the two copies (written); the folder’s on a tie.

bound 🔒

change

This device’s own entry changed by change, under its lock, read just before: written here, then, sharing on (vault: the folder and its key), into the folder when the others need it (see the module’s words). Returns it as written here.

change_at 🔒

change, at now (Unix seconds, this device’s clock): when the folder’s copy was last restated.

file_of 🔒

folder_of 🔒

in_use 🔒

Whether this device is in use, as its own entry says (Entry::working): the entry kept beside the sharing’s memory (<state>/share/, own_path).

is_zero 🔒

own

This device’s own entry as kept here; a new one when none reads.

own_path

Where this device keeps its own entry, never shared.

publish

This device’s entry, sealed into its file in the folder, its size changed from the one there.

published_path 🔒

sealed_with 🔒

Which key an entry was sealed with, as a mark that says nothing of the key itself (a hash of it under a name of its own).

stamp_of 🔒

The size and time of the folder’s copy of an entry, when there is one.

steady 🔒

What an entry says but for its exchanges’ times, as a hash: what the others must hear at once when it changes.

written 🔒

When an entry was written, as far as its times tell: each writing sets one of them to its device’s clock then (a start, a close, an exchange), and none goes back.