Skip to content

fix: make document model builds safe for concurrent use - #721

Open
daveshanley wants to merge 2 commits into
mainfrom
claude/concurrent-model-build
Open

daveshanley wants to merge 2 commits into
mainfrom
claude/concurrent-model-build

Conversation

@daveshanley

@daveshanley daveshanley commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Summary

BuildV3Model and BuildV2Model checked and set the cached model with no synchronization. Concurrent calls on the same document raced, and each caller could build and receive its own model, while the document kept whichever was stored last.

  • The document's mutable state (spec info, configuration, rolodex and both models) now lives in atomic.Pointer fields. Getters and cached builds are a single atomic load, with no locking.
  • A mutex serializes the builds themselves. Concurrent callers wait for the first build, then share its model.
  • Release takes the same mutex, so it waits for a build in progress. It is still end-of-life: it clears the SpecInfo in place (the SpecIndex shares it), so it must come after every other use of the document and of any SpecInfo taken from it. The interface doc now says so. Detaching SpecInfo without clearing it was rejected because the index would keep the YAML tree and spec bytes alive.
  • Render and Serialize read through the atomic fields.
  • The interface docs for both build methods state they are safe for concurrent use.

Callers such as libopenapi-validator no longer need their own locking around model builds.

Testing

  • New document_concurrency_test.go runs concurrent builds alongside the getters, Render, Serialize and SetConfiguration, and concurrent builds alongside Release. Against main it reports 40 data races and 30 failures where concurrent callers received different models. With this change it passes.
  • go test -race ./... passes, and document.go has 100% statement coverage.

Benchmarks

8 interleaved runs against main, benchstat:

Benchmark main this PR
cached BuildV3Model 1.83ns 1.94ns (+0.11ns)
GetSpecInfo, GetRolodex 1.8ns 1.8ns
cached BuildV3Model, 16 goroutines 0.14ns 0.15ns
fresh BuildV3Model 1.06ms 1.05ms (no significant change)

The +0.11ns on the cached build is one atomic acquire load in place of a plain load, the same cost sync.Once pays. No benchmark allocates more. A plain mutex was measured first and rejected: it doubled getter cost and pushed the 16-goroutine case to 89ns per call.

🤖 Generated with Claude Code

BuildV3Model and BuildV2Model checked and set the cached model with no
synchronization. Concurrent calls on one document raced, and each caller
could build and receive its own model.

The document's mutable state (spec info, configuration, rolodex and both
models) now lives in atomic pointers, so getters and cached builds read
without locking. A mutex serializes the builds themselves: concurrent
callers wait for the first build, then share its model. Release takes
the same mutex.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (34f4d57) to head (7ff8458).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #721   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          315       315           
  Lines        39919     39938   +19     
=========================================
+ Hits         39919     39938   +19     
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Release clears the SpecInfo in place, and the SpecIndex shares it, so a
reader still holding it races with Release. Detaching it instead would
keep the YAML tree and spec bytes alive through the index. Release stays
safe against concurrent builds; every other use must finish first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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