[doc] STAR-15 (BOX-13): withdraw Box pooling/Clone; document shared-cache hot path#21
Conversation
…ache hot path Reset rebuilds the machine in place for serial reuse of one Box. There is deliberately no Clone and no Box pool: per-run state (injected globals, the Starlark step counter) lives on the machine, so sharing or hand-pooling a Box leaks that state between runs. Document the recommended hot-path / concurrency pattern on Reset and SetScriptCache: construct a fresh New(...) per run and share only the compiled -program cache via SetScriptCache (a single starlet.MemoryCache is concurrency -safe), keeping compilation shared while per-run state stays isolated. Add TestSharedScriptCacheAcrossBoxes: a counting ByteCache proves two boxes running an identical script compile it exactly once across the shared cache.
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 12 |
| Duplication | 0 |
🟢 Coverage ∅ diff coverage · +0.00% coverage variation
Metric Results Coverage variation ✅ +0.00% coverage variation (-1.00%) Diff coverage ✅ ∅ diff coverage Coverage variation details
Coverable lines Covered lines Coverage Common ancestor commit (8e7cf4e) 1073 1060 98.79% Head commit (f615576) 1073 (+0) 1060 (+0) 98.79% (+0.00%) Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch:
<coverage of head commit> - <coverage of common ancestor commit>Diff coverage details
Coverable lines Covered lines Diff coverage Pull request (#21) 0 0 ∅ (not applicable) Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified:
<covered lines added or modified>/<coverable lines added or modified> * 100%
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #21 +/- ##
=======================================
Coverage 98.37% 98.37%
=======================================
Files 11 11
Lines 799 799
=======================================
Hits 786 786
Misses 7 7
Partials 6 6 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
1 participant
STAR-15 / BOX-13
Resetrebuilds the underlying machine in place for serial reuse of one Box. A hand-rolled Box pool (or aClone) would leak per-run state — injected globals and the Starlark step counter both live on the machine. There is no real consumer for a BoxClone, so it is withdrawn rather than implemented.Changes (doc + test only — no behavior change)
Resetgodoc: states it keeps the Box config for serial reuse, and that there is deliberately no Clone/pool, with the reason (per-run state leakage).SetScriptCachegodoc: documents the hot-path / concurrency recommendation — a singlestarlet.MemoryCache(concurrency-safe) shared across per-runNew(...)boxes compiles each distinct script once while every Box keeps isolated per-run state.TestSharedScriptCacheAcrossBoxes: a countingByteCacheproves two boxes running an identical script compile it exactly once across the shared cache — locking the documented guidance as executable.Verified
gofmt/go vetclean,go test -race -count=2green, and the Dockergolang:1.19floor green.