cook:~ docs
← docs · 3 min read

Watch the cache work

A five-node recipe, run three times: cold, fully cached, and after one edit. Real output, replayed.

guidecache

This is examples/02-pipeline from the repository. One recipe counts the words in every chapter, totals them, and writes a report. Three steps, five nodes.

examples/02-pipelineCookfile
recipe report
    gather "chapters/*.txt"
 
    # fan-out: one count per chapter
    cook "build/counts/$<in.stem>.count" {
        wc -w < $<in> | tr -d ' ' > $<out>
    }
 
    # many-to-one: every count in
    cook "build/total.txt" {
        cat $<in> | paste -sd+ - | bc > $<out>
    }
 
    # one step, two outputs
    cook "build/report.txt" "build/report.csv" {
        ...
    }

Cold, then cached, then one edit

The first run cooks all five nodes. The second run touches nothing: every key is already in the store. Then one chapter changes, and exactly the nodes downstream of it rebuild. The count for the other chapters, untouched, stays cached.

~/examples/02-pipelinecook 0.17.0
cook report
      Cooked report/build/counts/one.count in 1ms
      Cooked report/build/counts/three.count in 1ms
      Cooked report/build/counts/two.count in 1ms
      Cooked report/build/total.txt in 1ms
      Cooked report/build/report.txt in 2ms
    Finished in 11ms   (5 nodes, 0 cached)
cook report
      Cached report (5 nodes)
    Finished in 1ms   (5 nodes, all cached)
sed -i 's/moon/sun and stars/' chapters/two.txt
cook report
      Cached report/build/counts/one.count
      Cached report/build/counts/three.count
  Rebuilding report/build/counts/two.count — input changed: chapters/two.txt
      Cooked report/build/counts/two.count in 1ms
  Rebuilding report/build/total.txt — input changed: build/counts/two.count
      Cooked report/build/total.txt in 1ms
  Rebuilding report/build/report.txt — input changed: build/total.txt
      Cooked report/build/report.txt in 2ms
    Finished in 18ms   (5 nodes, 2 cached)
Why one.count stayed cached

Each fan-out unit is keyed on its own input. Editing two.txt changes one key. The total depends on all three counts, so it rebuilds; so does the report, which depends on the total. That is the whole model: the key is built from what you declared, and nothing else.

See the key for yourself

cook why prints every determinant behind a unit’s key, with its hit or miss status. Ask it about the total:

Terminal window
cook why report/build/total.txt

Read 9. Caching and cache trust for seal, the shared store, and cook cache verify.