Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

0010 - The package index and caches

Status: accepted

Context

Several questions cost a full read of a package: “who references this object?”, “what colour does it have?”, “which attachments does it have?”. Packages can hold hundreds of thousands of objects. Computing everything up front makes opening slow; computing nothing makes every question slow.

Decision

  • A package keeps what it knows of itself, layer by layer (index of objects and links, colour walks, attachment listings), in energyml-cache.
  • Links and summaries are kept; objects are re-read on demand. The index is invalidated by an edit through an overlay of what was changed.
  • There is one implementation: switching caching off means a slot that is thrown away, not another code path.
  • The colour rule is the same one for every face (ADR 0009).
  • The command-line cache commands are a fixed list.
  • Costs are visible: a call that reads everything (like asking who references an object) says so in its name, and work is counted in tests, never timed.

Consequences

  • Opening stays cheap; expensive questions are asked deliberately.
  • An edit never leaves a stale answer behind, because invalidation is part of the write.