Cpp: move DFA write locks from the ATN onto the DFA

DFA construction (addDFAState's state-set dedup and DFAState::setEdge) was
serialized by ATN::_stateMutex / ATN::_edgeMutex. But each ParserInterpreter /
LexerInterpreter owns its own decisionToDFA, so concurrent interpreters over a
shared (read-only) ATN serialized on a single per-ATN lock for DFA writes they
do not share — concurrency became a net loss (measured ~0.6x of serial on 4
threads).

Move those two write locks onto the DFA itself (dfa::DFA::stateMutex/edgeMutex,
heap-allocated so DFA stays movable) and lock the owning DFA in the simulators.
ATN::_mutex (lazy nextTokens cache) is unchanged; edge reads stay lock-free.

Independent DFAs now use independent locks (concurrent interpreters scale ~2.1x
on 4 threads); a DFA shared across threads (generated recognizers' static
decisionToDFA) still serializes its own writers, now at per-decision rather than
per-ATN granularity. Same locking discipline, finer scope.

Verified with a ThreadSanitizer build of the runtime + an 8-thread concurrent
parse harness over a shared ATN: no data races.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Christopher Barber <analog.cbarber@gmail.com>

Author: analog-cbarber

runtime/Cpp/runtime/src/atn/ATN.h

@@ -130,9 +130,11 @@ namespace atn {
     friend class LexerATNSimulator;
     friend class ParserATNSimulator;
 
+    // Guards the lazy nextTokens cache (ATNState::_nextTokenWithinRule). The
+    // DFA state/edge write locks formerly here were moved onto the DFA itself
+    // (see dfa::DFA::stateMutex/edgeMutex) so concurrent parses with independent
+    // DFAs no longer serialize on a single per-ATN lock.
     mutable internal::Mutex _mutex;
-    mutable internal::SharedMutex _stateMutex;
-    mutable internal::SharedMutex _edgeMutex;
   };
 
 } // namespace atn

runtime/Cpp/runtime/src/atn/LexerATNSimulator.cpp

@@ -80,7 +80,7 @@ size_t LexerATNSimulator::match(CharStream *input, size_t mode) {
   const dfa::DFA &dfa = _decisionToDFA[mode];
   dfa::DFAState* s0;
   {
-    SharedLock<SharedMutex> stateLock(atn._stateMutex);
+    SharedLock<SharedMutex> stateLock(dfa.stateMutex());
     s0 = dfa.s0;
   }
   if (s0 == nullptr) {
@@ -527,7 +527,7 @@ void LexerATNSimulator::addDFAEdge(dfa::DFAState *p, size_t t, dfa::DFAState *q)
     return;
   }
 
-  UniqueLock<SharedMutex> edgeLock(atn._edgeMutex);
+  UniqueLock<SharedMutex> edgeLock(_decisionToDFA[_mode].edgeMutex());
   p->setEdge(t - MIN_DFA_EDGE, MAX_DFA_EDGE - MIN_DFA_EDGE + 1, q); // connect
 }
 
@@ -559,7 +559,7 @@ dfa::DFAState *LexerATNSimulator::addDFAState(ATNConfigSet *configs, bool suppre
   dfa::DFA &dfa = _decisionToDFA[_mode];
 
   {
-    UniqueLock<SharedMutex> stateLock(atn._stateMutex);
+    UniqueLock<SharedMutex> stateLock(dfa.stateMutex());
     auto [existing, inserted] = dfa.states.insert(proposed);
     if (!inserted) {
       delete proposed;

runtime/Cpp/runtime/src/atn/ParserATNSimulator.cpp

@@ -127,11 +127,11 @@ size_t ParserATNSimulator::adaptivePredict(TokenStream *input, size_t decision,
 
   dfa::DFAState *s0;
   {
-    SharedLock<SharedMutex> stateLock(atn._stateMutex);
+    SharedLock<SharedMutex> stateLock(dfa.stateMutex());
     if (dfa.isPrecedenceDfa()) {
       // the start state for a precedence DFA depends on the current
       // parser precedence, and is provided by a DFA method.
-      SharedLock<SharedMutex> edgeLock(atn._edgeMutex);
+      SharedLock<SharedMutex> edgeLock(dfa.edgeMutex());
       s0 = dfa.getPrecedenceStartState(parser->getPrecedence());
     } else {
       // the start state for a "regular" DFA is just s0
@@ -143,7 +143,7 @@ size_t ParserATNSimulator::adaptivePredict(TokenStream *input, size_t decision,
     auto s0_closure = computeStartState(dfa.atnStartState, &ParserRuleContext::EMPTY, false);
     std::unique_ptr<dfa::DFAState> newState;
     std::unique_ptr<dfa::DFAState> oldState;
-    UniqueLock<SharedMutex> stateLock(atn._stateMutex);
+    UniqueLock<SharedMutex> stateLock(dfa.stateMutex());
     dfa::DFAState* ds0 = dfa.s0;
     if (dfa.isPrecedenceDfa()) {
       /* If this is a precedence DFA, we use applyPrecedenceFilter
@@ -155,7 +155,7 @@ size_t ParserATNSimulator::adaptivePredict(TokenStream *input, size_t decision,
       ds0->configs = std::move(s0_closure); // not used for prediction but useful to know start configs anyway
       newState = std::make_unique<dfa::DFAState>(applyPrecedenceFilter(ds0->configs.get()));
       s0 = addDFAState(dfa, newState.get());
-      UniqueLock<SharedMutex> edgeLock(atn._edgeMutex);
+      UniqueLock<SharedMutex> edgeLock(dfa.edgeMutex());
       dfa.setPrecedenceStartState(parser->getPrecedence(), s0);
     } else {
       newState = std::make_unique<dfa::DFAState>(std::move(s0_closure));
@@ -1293,15 +1293,15 @@ dfa::DFAState *ParserATNSimulator::addDFAEdge(dfa::DFA &dfa, dfa::DFAState *from
   }
 
   {
-    UniqueLock<SharedMutex> stateLock(atn._stateMutex);
+    UniqueLock<SharedMutex> stateLock(dfa.stateMutex());
     to = addDFAState(dfa, to); // used existing if possible not incoming
   }
   if (from == nullptr || t < -1 || t > (int)atn.maxTokenType) {
     return to;
   }
 
   {
-    UniqueLock<SharedMutex> edgeLock(atn._edgeMutex);
+    UniqueLock<SharedMutex> edgeLock(dfa.edgeMutex());
     // Edges are indexed by t + 1 so EOF (t == -1) lands in slot 0; the table
     // therefore needs maxTokenType + 2 slots.
     from->setEdge(t + 1, atn.maxTokenType + 2, to); // connect

runtime/Cpp/runtime/src/dfa/DFA.cpp

@@ -73,9 +73,9 @@ DFAState* DFA::getPrecedenceStartState(int precedence) const {
     return nullptr;
   }
 
-  // Read under ATN::_edgeMutex (held by the caller); the precedence start-state
-  // table is the only edge table that grows, and it is never read via the
-  // lock-free getEdge path used by the lexer/parser simulators.
+  // Read under this DFA's edgeMutex() (held by the caller); the precedence
+  // start-state table is the only edge table that grows, and it is never read
+  // via the lock-free getEdge path used by the lexer/parser simulators.
   return s0->getEdge(static_cast<size_t>(precedence));
 }
 

runtime/Cpp/runtime/src/dfa/DFA.h

@@ -5,12 +5,14 @@
 
 #pragma once
 
+#include <memory>
 #include <unordered_set>
 #include <vector>
 #include <string>
 #include <cstddef>
 #include "antlr4-common.h"
 #include "dfa/DFAState.h"
+#include "internal/Synchronization.h"
 
 namespace antlr4 {
 namespace dfa {
@@ -89,12 +91,31 @@ namespace dfa {
 
     std::string toLexerString() const;
 
+    /// Locks guarding writes to THIS DFA: stateMutex() serializes state-set
+    /// insertion (addDFAState), edgeMutex() serializes edge-table allocation and
+    /// stores (DFAState::setEdge). Lock-free DFAState::getEdge() reads need
+    /// neither. These live on the DFA — not the ATN — so independent DFAs (each
+    /// interpreter owns its own decisionToDFA) never serialize against one
+    /// another; a DFA shared across threads (generated recognizers' static
+    /// decisionToDFA) still serializes its own writers, as before, but now at
+    /// per-decision rather than per-ATN granularity.
+    internal::SharedMutex &stateMutex() const noexcept { return *_stateMutex; }
+    internal::SharedMutex &edgeMutex() const noexcept { return *_edgeMutex; }
+
   private:
     /**
      * {@code true} if this DFA is for a precedence decision; otherwise,
      * {@code false}. This is the backing field for {@link #isPrecedenceDfa}.
      */
     bool _precedenceDfa;
+
+    // Heap-allocated so DFA stays movable (SharedMutex is neither movable nor
+    // copyable). A moved-into DFA gets fresh locks via these initializers; DFAs
+    // are only moved empty during decisionToDFA construction, before any parse.
+    std::unique_ptr<internal::SharedMutex> _stateMutex =
+        std::make_unique<internal::SharedMutex>();
+    std::unique_ptr<internal::SharedMutex> _edgeMutex =
+        std::make_unique<internal::SharedMutex>();
   };
 
 } // namespace atn

runtime/Cpp/runtime/src/dfa/DFAState.cpp

@@ -42,9 +42,9 @@ void DFAState::setEdge(size_t index, size_t minSize, DFAState *target) {
     _edgeCount.store(newCount, std::memory_order_release);
     _edges.store(newEdges, std::memory_order_release);
     // Only the precedence start state ever reaches this with a non-null
-    // `edges`, and it is read exclusively under ATN::_edgeMutex (never via the
-    // lock-free getEdge path), so freeing the old table here cannot race a
-    // concurrent reader.
+    // `edges`, and it is read exclusively under the owning DFA's edgeMutex()
+    // (never via the lock-free getEdge path), so freeing the old table here
+    // cannot race a concurrent reader.
     delete[] edges;
     edges = newEdges;
   }

runtime/Cpp/runtime/src/dfa/DFAState.h

@@ -116,8 +116,8 @@ namespace dfa {
     /// {@code edges[symbol]} points to the target state for that symbol. The
     /// table is allocated lazily at a fixed size and its slots are published
     /// with release/read with acquire, so getEdge() needs no lock. Allocation,
-    /// growth and stores (setEdge) must be serialized by the caller through
-    /// ATN::_edgeMutex.
+    /// growth and stores (setEdge) must be serialized by the caller through the
+    /// owning DFA's edgeMutex() (dfa::DFA::edgeMutex).
 
     /// Lock-free read of the edge for the given (already offset) index, or
     /// nullptr if there is no such edge yet. Safe to call without any lock.
@@ -135,8 +135,8 @@ namespace dfa {
     /// Store an edge. `minSize` is the natural full size of the table for this
     /// DFA kind (the lexer char range, or maxTokenType+2 for the parser, whose
     /// edges are indexed by t+1 so EOF lands in slot 0); the table is
-    /// grown to at least `index + 1` if needed. The caller MUST hold the
-    /// ATN::_edgeMutex write lock. Lexer/parser tables are allocated once at
+    /// grown to at least `index + 1` if needed. The caller MUST hold the owning
+    /// DFA's edgeMutex() write lock. Lexer/parser tables are allocated once at
     /// `minSize` and never reallocated, so concurrent lock-free getEdge() calls
     /// never observe a moved table; only the precedence start state grows, and
     /// it is read exclusively under the lock.