Bridge-level thread-handling contract: per-call safety classification, scoped/controllable internal parallelism, encapsulated global state — safety AND throughput

[gsdali]

Companion to #341 (NCollection race characterisation, CLOSED), from OCCTReconstruct's contention audit (OCCTReconstruct#175/#309, 2026-07-21).

Rewritten 2026-09-21. The original body's four "measured starting points" were re-measured; two had gone stale and one turned out to be a live documentation defect. What follows is the current state, with the original measurements kept where they still hold so the argument stays auditable.

The problem, unchanged

The thread-safety surface is not knowable from the API. OCCTSerial exists but is opt-in, callers discover unsafe calls one crash at a time (#298, CLOSED, was exactly this: the documented "independent shapes are thread-safe" guarantee was wrong for fillet and chamfer), and the practical downstream response is blanket serialization. Measured cost for one consumer's suite: 4213s serialized against 2066s parallel.

A defined and enforced contract at the bridge is both the safety fix and the speed-up.

Measured state, 2026-09-21

Claim	Status
890 OSD_ThreadPool symbols in the bundled kernel	still exact
Kernel built WITHOUT TBB (OSD_Parallel_TBB.cxx.o compiled empty)	still true
STEP writer mutates Interface_Static process globals	still true, now characterised, see below
OCCTBridge_Modeling.mm:1562 hard-codes SetRunParallel(Standard_True)	STALE, twice over
OCCTSerialQueue.swift documents no per-call classification	was worse than stated, now fixed

The two stale items

The file is gone. OCCTBridge_Modeling.mm was split into 12 OCCTBridge_Modeling_<Bucket>.mm files by #396 (CLOSED). Any plan built from :1562 needs to re-find the site.

The SetRunParallel situation has inverted. It was removed under #367/#369 after appearing to cause silent data corruption. The default is now serial, with SetRunParallel(Standard_False) explicit at OCCTBridge_Modeling_Boolean.mm:4068 and :4163, and a comment at :1071 recording that re-enabling is "very likely safe". So the problem is no longer oversubscription; it is that we leave cores idle. CLAUDE.md tracks re-enabling as a separate open decision.

Checking TBB is worth one warning: a naive nm -C ... | grep -i tbb returns three hits, but two are Vrml_WWWInline::SetBbox* (the substring "tbb" inside "SetBbox") and the third is the OSD_Parallel_TBB.cxx.o object header with no symbols under it. That absence is what "compiled empty" looks like.

What has been delivered since filing

Proposal item 2 is already done for the data-exchange surface, and nobody had written it down. igesMutex() is exactly the "auto-acquire inside the bridge for global-state calls" this issue asks for: 40 bridge entry points (23 STEP, 15 IGES, 2 Document) hold a process-wide recursive mutex for their whole body.

The measurement behind why it must stay is #1403 (OPEN) and its carried patches 0036 through 0041:

	TSan reports	Named racing globals
Before	178	16
After	37	0

Interface_Static is only part of it. The data-exchange path also routes through a per-format singleton controller and its shared write actor, which is #1403's remaining item and is not fixable by any lock (nine call sites treat the actor as a configuration channel). Upstream research context: OCCT#1179 (CLOSED).

The documentation defect this issue's first bullet led to. OCCTSerialQueue.swift did not merely lack a classification, it stated the opposite of the truth: "Individual bridge calls are NOT auto-locked", in the one file a consumer reads before deciding whether they need OCCTSerial. Fixed in #2073 (MERGED), along with the same claim in its public doc comment and the total absence of thread-safety documentation in Exporter.swift.

What is left, and what closing this requires

1. Classify every bridge entry point as concurrent-safe / exclusive / global-state, and publish the table. Not started. The DE surface is now effectively global-state-and-handled, so the work is the remaining ~700 entry points. This is the bulk of the issue.
2. Enforce: auto-acquire for exclusive/global-state calls. Done for DE, unproven elsewhere because step 1 has not run. Interface_Static snapshot/restore is moot: the whole DE surface is serialized instead.
3. Control internal parallelism. Needs rewriting around the inverted default. The question is now whether and how to re-enable SetRunParallel, plus whether pool sizing should be caller-controllable so N concurrent pipelines can bound total workers instead of N x ncores. OSD_ThreadPool/BOPTools_Parallel: root-cause the cross-caller corruption behind #367 #369 is the decision record.
4. Throughput payoff. Still follows, and still the point: with a trustworthy concurrent-safe surface, consumers stop blanket-serializing.

Closing criteria

• A published per-entry-point classification table in docs/thread-safety.md, derived, not hand-maintained (4,056 entries cannot be curated), with a gate that fails when a new bridge entry point is added without a classification. The realistic shape is a script that infers the class from what a function touches (shared caches, process globals, igesMutex()) and a small adjudicated exception list, in the mould of Scripts/census-*.py.
• Every exclusive/global-state call auto-acquiring, or a documented reason it does not.
• A decision recorded on SetRunParallel and pool sizing, either way.

Items 1 and 2 are the substance. Item 3 is a decision, not a build. Item 4 is the consequence, not work.

Precedents that still hold: #298 plus patch 0003 (the classify-then-fix loop works), patch 0010 (#319, CLOSED: measured runaway to bounded), and now 0036-0041 (measure, relocate ownership, re-measure). Nothing here needs TBB or upstream changes except where #341's characterisation says so.

[gsdali]

First concrete data point from #341's investigation (v1.15.4), toward the "classify" stage of the
staged proposal above:

exclusive — every OBJ/glTF/PLY CAF-reader/writer bridge function (OCCTImportOBJ,
OCCTExportOBJ, OCCTDocumentLoadOBJ*, OCCTDocumentWriteOBJ, OCCTDocumentWritePLY,
OCCTExportPLYWithOptions, OCCTImportGLTF, OCCTExportGLTF, OCCTDocumentLoadGLTF,
OCCTDocumentWriteGLTF). Root cause: RWMesh_CafReader::fillDocument() races on the process-global
XCAFDoc_ShapeTool::theAutoNaming with zero synchronization (confirmed via ThreadSanitizer, 9-17
races per stress run — see Scripts/repro/341-meshcaf/). Currently enforced ad hoc via a dedicated
meshCafMutex() in OCCTBridge_IO.mm, exactly the kind of per-call lock this issue's stage 2
("auto-acquire OCCTSerial inside the bridge for exclusive/global-state calls") proposes doing
systematically instead of one-off.

Also relevant to stage 1 ("classify... back it with the #341/#298 TSan protocol rather than
assertion"): #341 also cleared three call patterns previously assumed unsafe by
Tests/OCCTStressTests/StressConcurrencyTests.swift's long-standing .disabled() suites —
independent shape creation, shared-instance read-only queries (volume/area/bounds/faceCount/
isValid), and concurrent curve/surface evaluation. Those are concurrent-safe by this issue's
proposed taxonomy: every bridge call site for curve/surface eval builds its own function-local
GeomAdaptor_Curve/adaptor (confirmed by reading OCCTBridge_Curve3D.mm), so the class's documented
but real unsynchronized BSplCLib_Cache (GeomAdaptor_Curve.hxx's mutable Handle(BSplCLib_Cache) Cache) is never actually shared across threads through today's Swift API — a live example of the gap
between "this OCCT class isn't thread-safe in isolation" and "this bridge call is reachable-unsafe,"
which is exactly the distinction stage 1's classification table needs to make per-call rather than
per-OCCT-class.

Not attempting the full staged proposal here — #341 was scoped to characterization + the one
concrete fix. Leaving this as a data point for whoever picks up the classification table.

[gsdali]

Cross-reference: #920 documents a possibly-related CI-only crash (3/3 reruns on a PR's branch, 2/2 clean on main's control, 7/7 clean locally) investigated during PR #912's round 2. Root cause not established — could be this issue's class of unsynchronized shared OCCT state, or could be unrelated. Not folded in directly since the connection is speculative.

[gsdali]

Folded under #707 as the campaign's deliverable half, and left open there rather than closed: the content of this issue is the contract, and nothing else states it.

#707 finds the races; this issue says what the bridge promises about them, per call, in docs/thread-safety.md. The two only make sense together, which is why this one has sat open with no work on it: a safety classification written before the sweep would be a guess, and the sweep without a written contract leaves consumers no better off.

See #707's scope comment for the lane order and the upstream timing that now drives it.

[gsdali]

Triage, 2026-09-21. Re-measured all four of the "measured starting points" against the current tree. Two are stale, two are still exact, and one of them led to a real fix.

Stale

1. OCCTBridge_Modeling.mm:1562 does not exist. That file was split into 12 OCCTBridge_Modeling_<Bucket>.mm files by #396. Any plan built from this citation needs to re-find the site.

2. The SetRunParallel(Standard_True) claim has inverted. The issue says the bridge "hard-codes builder.SetRunParallel(Standard_True)… and the caller has no knob". It was removed under #367/#369 after appearing to cause silent data corruption, and the default is now serial, with SetRunParallel(Standard_False) explicit at OCCTBridge_Modeling_Boolean.mm:4068 and :4163. So proposal item 3's premise is gone: the problem is no longer oversubscription, it is that we are leaving cores on the floor, and CLAUDE.md already tracks re-enabling as a separate open decision.

Still exact

3. 890 OSD_ThreadPool symbols. Measured again just now: 890. Unchanged.

4. No TBB. Still right, and worth recording how it looks when checked: a naive nm | grep -i tbb returns 3 hits, but two are Vrml_WWWInline::SetBbox* (the string "tbb" inside "SetBbox") and the third is the OSD_Parallel_TBB.cxx.o object header with no symbols following it, which is what "compiled empty" looks like.

The one that produced a fix

The issue's first bullet cites OCCTSerialQueue.swift as naming racy areas with "no per-call classification". Following it up found that file actively wrong: it says "Individual bridge calls are NOT auto-locked" while forty entry points across the STEP, IGES and Document bridge files hold a process-wide recursive mutex for their whole body. That is the file a consumer reads to decide whether they need OCCTSerial, and it was wrong in both directions. Fixed in PR #2073.

Which also means proposal item 2 is already done for the data-exchange surface and nobody had written it down. igesMutex() is exactly the "auto-acquire inside the bridge for global-state calls" this issue asks for, and #1403's work this week is the measurement behind why it must stay: 16 named racing globals in that path, now 0.

Verdict

Valid, thesis intact, needs its measurements retaken before it is planned from. Items 1 and 2 are the live parts; item 2 is partly delivered for DE and needs classifying elsewhere. Item 3 needs rewriting around the inverted SetRunParallel situation, and item 4's throughput argument still follows.

Not proposing to close it. Proposing that whoever picks it up re-derives the four bullets first, because two of them would send them to the wrong place.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NWwhHu3LTRQQkNn9WSnb7U

[gsdali]

Body rewritten, and one correction to my own triage comment above.

I wrote there that item 1's remaining work was the entry points outside data exchange, implying a modest number. Measured properly: the bridge declares 4,056 OCCT* entry points across its 16 headers (4,263 definitions in the .mm files, the difference being file-local helpers). Forty are handled by igesMutex().

So item 1 is a ~4,000-item classification, not a few hundred. That is the single most important fact about this issue and neither the original body nor my first comment stated it. The body now leads with it, and the closing criteria now say the table must be derived, not hand-maintained, in the mould of the existing Scripts/census-*.py tooling, with an adjudicated exception list rather than 4,000 curated entries.

That is also, I suspect, why this issue has sat since July: the proposal reads as tractable until you count the surface.

Summary of the rewrite

• Kept the two measurements that still hold exactly (890 OSD_ThreadPool symbols, no TBB) with a note on the grep -i tbb false-positive trap.
• Marked the two stale ones and said why: OCCTBridge_Modeling.mm no longer exists (Further large-file breakout candidates (tracking issue, not yet actioned) #396), and SetRunParallel has inverted from hardcoded-parallel to explicit-serial (OCCTShapeFuseMulti (Shape.fuseAll): SetRunParallel(true) causes data corruption under concurrent calls #367/OSD_ThreadPool/BOPTools_Parallel: root-cause the cross-caller corruption behind #367 #369), so item 3 is now a decision about re-enabling rather than a fix for oversubscription.
• Recorded that item 2 is already delivered for the DE surface and nobody had written it down, with XSControl_Controller's per-format-singleton ownership: structural, unfixable-by-accessor-lock races in STEPControl_ActorWrite/IFSelect_WorkSession (found investigating #1157) #1403's before/after (178 reports and 16 named globals, to 37 and 0).
• Recorded the documentation defect the first bullet led to, fixed in docs: the STEP/IGES surface IS auto-locked, and three files said otherwise #2073.
• Linked every referenced issue with its state: NCollection race under parallel execution: documented downstream as 'run --no-parallel', never filed or characterised upstream — needs the #298 TSan protocol #341, SheetMetal.Builder.build silently returns an empty solid under parallel test execution (8/10 runs) — contradicts the documented "independent shapes are thread-safe" guarantee #298, isSelfIntersecting: hard-bounded (worker-thread) variant + upstream OCCT checkpoint/quadratic report (follow-up to #293) #319, Further large-file breakout candidates (tracking issue, not yet actioned) #396 closed; XSControl_Controller's per-format-singleton ownership: structural, unfixable-by-accessor-lock races in STEPControl_ActorWrite/IFSelect_WorkSession (found investigating #1157) #1403 open; upstream OCCT#1179 closed.
• Added explicit closing criteria, separating the two that are real work (classify, enforce) from the one that is a decision (SetRunParallel) and the one that is a consequence (throughput).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NWwhHu3LTRQQkNn9WSnb7U