A content-addressed store on disk, safe to share between OS processes: large values kept by digest, an action cache, verifying traces, and scratch directories, with a garbage collector that never takes what a reader is using.

{:ok, store} = Roux.Blob.open("~/.cache/my_tool/store")
{:ok, digest} = Roux.Blob.put_term(store, big_value)
{:ok, ^big_value} = Roux.Blob.get_term(store, digest)

Layout

A store is a directory:

• FORMAT — the layout's version; a store of another is refused;
• cas/<aa>/<digest> — content-addressed entries (put/2, adopt/2, get/2, link/3), named by the SHA-256 of their bytes in lowercase hex, aa its first two digits;
• traces/<name digest>/<observations digest>.<bytes digest> — verifying traces (Roux.Blob.Trace), each version a file of its own; the action cache (remember/3, recall/2: a term stored under any key) keeps each entry as a trace of no observations;
• ac/<aa>/<key digest> — action-cache entries roux 0.2.1 kept, still read;
• roots/<owner digest> — the digests an owner keeps alive (retain/3), a manifest's among them;
• scratch/<os pid>.<token>-<n>/ — a directory per use (scratch/2), named after the OS process and a token of its VM's own;
• tmp/ — files being written; trash/ — entries being removed, a CAS entry under a name that begins with its digest.

Entries

An entry is immutable. It is written under a name of its own in tmp/ and hard-linked into place, so a reader finds it whole or not at all. A CAS entry is never replaced: a writer that finds its name taken (EEXIST) has found the same bytes — content addressing makes "already there" always right — and leaves them. A rename that replaces a name is not atomic everywhere: on APFS a concurrent link(2) or open finds no name for a moment, so replacing the empty relation file that every solve links made those links fail ({:error, :enoent}) while the entry was there all along. CAS entries are read-only on disk: a hard link to one (link/3) shares its inode, and a program writing into the link would write into the store.

A trace or action-cache entry whose value changes is never replaced either: each value is a version of its own, named by its bytes' digest and linked into place, and a write removes the versions it found before it (Roux.Blob.Trace's "Versions"). A reader always finds a complete version, and after a write, the one it wrote. A root, whose owner rewrites it, is renamed into place, and only when its bytes change (an equal write refreshes the file instead); a collection that cannot read a root it listed sweeps nothing. A reader that finds an entry gone, or not holding what its name says, takes it for a miss (and a corrupt one is taken out of its name, so the next write replaces it).

Trust

A store has the manifest's trust model: its files were written by this tool, for this user, on this machine. Terms are decoded as the manifest decodes them — without :safe, so a term naming an atom the VM has not created yet (a function name in a stored finding) decodes in a fresh VM instead of missing. What makes that trust good is who can write the files, and open/1 checks exactly that: it refuses a root, or a FORMAT file, that the current OS user does not own or that is writable by its group or by everyone (Roux.Blob.TrustError). A symbolic link as the root is followed, and its target checked the same way. A root open/1 creates is made 0700. Bytes that do not decode — a truncated or corrupt file — are still a miss, never a crash.

Raw I/O, and touches that refresh

Every file operation of the store is raw (Roux.Blob.IO): it goes straight to the operating system from the calling process, never through the VM's one file server, so a fan-out of lookups (Roux.Runtime.parallel/3) runs side by side.

A lookup that finds an entry — a put/2 of bytes already there, a recall/2 hit, a trace found or put again (Roux.Blob.Trace) — refreshes its modification time, which is what a collection and a trace prune read as "in use". It does so only when that time is older than the store's refresh: interval (an hour by default, open/2): a warm run that reads the same entries again writes nothing. An entry used within the interval has therefore been marked within twice it, the store's window (window/1), and nothing takes an entry for unused within the window: a collection's grace and keep periods are never shorter (a shorter one is taken as the window), and a trace's prune leaves every trace marked within it, however many.

Collection

An entry is swept by renaming it aside — into trash/, under a name that begins with its digest — then looking at it again: one touched meanwhile is linked back under its name. For that moment the name is missing, so a reader of a missing entry looks for its aside copy too (get/2, link/3): the inode is always under one of the two names, and a process that found an entry present (a put/2, whose finding marks it used) can always link it.

gc/2 first sweeps the action-cache entries and traces unused for longer than its keep period, then marks from the live roots — every owner's retained digests (retain/3), and the digests named by the action-cache entries and traces left — and sweeps what is left and older than a grace period. An entry is renamed aside before it is deleted, and put back when it was touched meanwhile: a put/2 of bytes already there, a recall/2 or a trace lookup touches the entry it finds. The pointers' fate is decided first so that one put back — used as it was being taken — finds what it names still there; and a lookup that finds its entry taken between its read and its touch misses rather than use a value naming entries the collection is taking. The grace period must be longer than the longest run between writing an entry and retaining it: a run's own entries are young until it retains them.