Skip to content

docs(explanation): add caching chapter covering all layers#160

Merged
jensens merged 1 commit into
mainfrom
docs/caching-explanation
Apr 22, 2026
Merged

docs(explanation): add caching chapter covering all layers#160
jensens merged 1 commit into
mainfrom
docs/caching-explanation

Conversation

@jensens
Copy link
Copy Markdown
Member

@jensens jensens commented Apr 22, 2026

New Diataxis Explanation chapter at `docs/sources/explanation/caching.md`.

Why

We had caching fragments scattered across `performance.md` but no consolidated page that answers "what is cached where, for how long, and how does it get invalidated" — which is exactly what a reader needs when sort/pagination looks unstable or `getObject()` appears to return stale data.

What it covers

  • All six cache layers on the query → getObject path (query result cache, prepared statements, request connection pool, zodb-pgjsonb `LoadCache`, ZODB Connection object cache, PG `shared_buffers`) with scope/lifetime/invalidation.
  • The explicit invariant: brains and `getObject()` results are deliberately not memoized. Why that matters for request-boundary hygiene.
  • Prefetch mechanism (`_maybe_prefetch_objects` + `storage.load_multiple()`) — what it warms, what it doesn't.
  • Invalidation matrix: which write event clears which cache.
  • Every configuration knob (env vars for plone.pgcatalog, `zope.conf` for ZODB, `` for the storage, `postgresql.conf` for PG).
  • Debugging guide for the three common "my cache isn't behaving" symptoms.
  • Cross-links to `performance.md` for benchmarks (no duplication) and `architecture.md` for the write path that drives catalog-side invalidation.

Test plan

  • `sphinx-build -W` clean (the two unrelated TOC warnings are pre-existing and about other how-to pages)
  • Vale clean (added `memoize`, `unpickle`, `truthy`, `unsortable` to project vocab)
  • Mermaid diagram renders
  • Chapter added to `explanation/index.md` TOC between `tika-extraction` and `performance`

🤖 Generated with Claude Code

Maps the full cache chain from query dict to object: query result cache,
prepared statements, request connection pool, zodb-pgjsonb LoadCache,
ZODB Connection object cache, PG shared_buffers. Explains the
invariant that brains and getObject results are deliberately not
memoized (request-boundary hygiene, ZODB handles it in the right
scope), and documents prefetch, invalidation rules, and every
configuration knob.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@jensens jensens merged commit b7eb64e into main Apr 22, 2026
5 checks passed
@jensens jensens deleted the docs/caching-explanation branch April 22, 2026 22:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant