Module cache 

The build cache: what a cook produced for its own later runs, all of it in the one segment a host anchors.

Some assets are expensive to compile – the EnvironmentMap IBL convolution alone is hundreds of millions of float ops per build – and a scene import re-parses a source file that may run to gigabytes. Both are deterministic functions of a small set of inputs, so the inputs are hashed into a key (key) and the output is stored under it. A later build that produces the same key reuses what is stored instead of doing the work again. The baked asset previews (thumbnails) ride the same segment on the same terms: cook renders them, so cook stores them, though the editor is what reads them back.

One file per writer role is the rule the layout is built on. A build writes this segment and nothing else, the running application writes its own, so a cook against a live editor never touches the file that editor is writing. Two builds may still share this one, and the segment survives that: an index reads from the file it indexed, so the loser of a race loses entries rather than publishing the wrong bytes under the right key.

The file is touched at the two moments the design allows and no others: the index is read when the first lookup needs it, and the segment is replaced by flush when the work producing it finishes. In between, a hit seeks to the one entry it wants and a store lands in memory, so a compile that stores for every asset costs one write rather than one per asset. That is also what makes the concurrent-store race structurally impossible: nothing writes the file while the compile is running.

What produced an entry is not part of its key. The identity of the cook binary rides the segment header instead (identity), so a segment an older binary wrote is dropped whole rather than replayed against code that moved.

Every operation is best-effort: a miss, an unreadable segment, or a failed write all leave the caller to compile normally, so the cache can never break or corrupt a build. Deleting cache/ at any point costs recomputation and nothing else.

Which file the segment is is not this module’s business: a host anchors the one it resolved from its own state tree. Until one does, every operation here is a miss and every asset compiles.

Modules

thumbnails

The thumbnail set inside the build segment: the baked PNG entries and the one entry mapping asset name to key.

Functions

anchor

Point the build cache at segment for the rest of the process, or until another anchor replaces it. A host resolves the path from its own state tree (StateTree::build_cache_path); nothing here knows what one looks like.

clear_anchor

Drop the anchor, leaving the build with no segment to warm from.