Cpp: make DFAState edge lookups lock-free to speed up lexing

The C++ runtime stored each DFA state's outgoing edges in a
FlatHashMap<size_t, DFAState*> and guarded every access with a single
shared ATN-wide mutex (ATN::_edgeMutex). Because the lexer consults the
edge table once per input character, the hottest loop in the runtime paid
a shared-lock acquire plus a hash-map probe on every codepoint. The Java
reference runtime has neither cost: DFAState.edges is a plain array indexed
by symbol, and reads are lock-free (a benign miss simply recomputes the
edge, which is idempotent), while writes are serialized per state.

This change brings the C++ representation in line with Java:

  - DFAState::edges becomes a lazily allocated, fixed-size array of
    std::atomic<DFAState*>. getEdge() reads a slot with acquire ordering
    and needs no lock; setEdge() publishes slots with release ordering and
    is still serialized by the caller via ATN::_edgeMutex.
  - Lexer and parser getExistingTargetState() now read edges lock-free,
    removing the per-symbol shared-lock acquire from the hot path.
  - The lexer and parser edge tables are allocated once at their natural
    full size (the char range and maxTokenType+1 respectively) and never
    reallocated, so a concurrent lock-free reader can never observe a moved
    table. The only table that grows is the precedence DFA's start-state
    table, which is read exclusively under ATN::_edgeMutex and never via
    the lock-free path, so resizing it cannot race a reader.

The concurrency contract is therefore identical to Java's: lock-free reads
tolerating a benign recompute-on-miss, with writes serialized. There is no
public API change.

Measured on an 84 MiB JSON input (Apple M5 Max, single-threaded interpreted
parse), the lexer stage goes from 26.7 to 47.9 MiB/s (~1.8x) and total
native parse from 15.0 to 20.9 MiB/s (~1.4x); a 54 MiB netlist input shows
1.7x / 1.3x. Output is byte-for-byte identical to the previous runtime
across all test inputs.

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

Author: analog-cbarber

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

@@ -181,19 +181,18 @@ size_t LexerATNSimulator::execATN(CharStream *input, dfa::DFAState *ds0) {
 }
 
 dfa::DFAState *LexerATNSimulator::getExistingTargetState(dfa::DFAState *s, size_t t) {
-  dfa::DFAState* retval = nullptr;
-  SharedLock<SharedMutex> edgeLock(atn._edgeMutex);
-  if (t <= MAX_DFA_EDGE) {
-    auto iterator = s->edges.find(t - MIN_DFA_EDGE);
+  if (t > MAX_DFA_EDGE) {
+    return nullptr;
+  }
+  // Lock-free: the edge table is published with release in addDFAEdge and read
+  // here with acquire (see DFAState::getEdge). A benign miss (null) just causes
+  // the target to be recomputed, mirroring the Java runtime.
+  dfa::DFAState *retval = s->getEdge(t - MIN_DFA_EDGE);
 #if LEXER_DEBUG_ATN == 1
-    if (iterator != s->edges.end()) {
-      std::cout << std::string("reuse state ") << s->stateNumber << std::string(" edge to ") << iterator->second->stateNumber << std::endl;
-    }
-#endif
-
-    if (iterator != s->edges.end())
-      retval = iterator->second;
+  if (retval != nullptr) {
+    std::cout << std::string("reuse state ") << s->stateNumber << std::string(" edge to ") << retval->stateNumber << std::endl;
   }
+#endif
   return retval;
 }
 
@@ -529,7 +528,7 @@ void LexerATNSimulator::addDFAEdge(dfa::DFAState *p, size_t t, dfa::DFAState *q)
   }
 
   UniqueLock<SharedMutex> edgeLock(atn._edgeMutex);
-  p->edges[t - MIN_DFA_EDGE] = q; // connect
+  p->setEdge(t - MIN_DFA_EDGE, MAX_DFA_EDGE - MIN_DFA_EDGE + 1, q); // connect
 }
 
 dfa::DFAState *LexerATNSimulator::addDFAState(ATNConfigSet *configs) {

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

@@ -292,11 +292,10 @@ size_t ParserATNSimulator::execATN(dfa::DFA &dfa, dfa::DFAState *s0, TokenStream
 }
 
 dfa::DFAState *ParserATNSimulator::getExistingTargetState(dfa::DFAState *previousD, size_t t) {
-  dfa::DFAState* retval;
-  SharedLock<SharedMutex> edgeLock(atn._edgeMutex);
-  auto iterator = previousD->edges.find(t);
-  retval = (iterator == previousD->edges.end()) ? nullptr : iterator->second;
-  return retval;
+  // Lock-free acquire read (see DFAState::getEdge). Edges are indexed by t + 1 so
+  // EOF (t == SIZE_MAX) maps to slot 0, matching the generated parser; a miss
+  // yields nullptr and the target is recomputed.
+  return previousD->getEdge(t + 1);
 }
 
 dfa::DFAState *ParserATNSimulator::computeTargetState(dfa::DFA &dfa, dfa::DFAState *previousD, size_t t) {
@@ -1297,13 +1296,15 @@ dfa::DFAState *ParserATNSimulator::addDFAEdge(dfa::DFA &dfa, dfa::DFAState *from
     UniqueLock<SharedMutex> stateLock(atn._stateMutex);
     to = addDFAState(dfa, to); // used existing if possible not incoming
   }
-  if (from == nullptr || t > (int)atn.maxTokenType) {
+  if (from == nullptr || t < -1 || t > (int)atn.maxTokenType) {
     return to;
   }
 
   {
     UniqueLock<SharedMutex> edgeLock(atn._edgeMutex);
-    from->edges[t] = to; // connect
+    // 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
   }
 
 #if DFA_DEBUG == 1

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

@@ -69,11 +69,14 @@ bool DFA::isPrecedenceDfa() const {
 DFAState* DFA::getPrecedenceStartState(int precedence) const {
   assert(_precedenceDfa); // Only precedence DFAs may contain a precedence start state.
 
-  auto iterator = s0->edges.find(precedence);
-  if (iterator == s0->edges.end())
+  if (precedence < 0) {
     return nullptr;
+  }
 
-  return iterator->second;
+  // 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.
+  return s0->getEdge(static_cast<size_t>(precedence));
 }
 
 void DFA::setPrecedenceStartState(int precedence, DFAState *startState) {
@@ -85,7 +88,7 @@ void DFA::setPrecedenceStartState(int precedence, DFAState *startState) {
     return;
   }
 
-  s0->edges[precedence] = startState;
+  s0->setEdge(static_cast<size_t>(precedence), static_cast<size_t>(precedence) + 1, startState);
 }
 
 std::vector<DFAState *> DFA::getStates() const {

runtime/Cpp/runtime/src/dfa/DFASerializer.cpp

@@ -25,8 +25,8 @@ std::string DFASerializer::toString() const {
   std::stringstream ss;
   std::vector<DFAState *> states = _dfa->getStates();
   for (auto *s : states) {
-    for (size_t i = 0; i < s->edges.size(); i++) {
-      DFAState *t = s->edges[i];
+    for (size_t i = 0; i < s->edgeCount(); i++) {
+      DFAState *t = s->getEdge(i);
       if (t != nullptr && t->stateNumber != INT32_MAX) {
         ss << getStateString(s);
         std::string label = getEdgeLabel(i);

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

@@ -3,10 +3,12 @@
  * can be found in the LICENSE.txt file in the project root.
  */
 
+#include <algorithm>
+#include <cstddef>
 #include <memory>
 #include <sstream>
 #include <string>
-#include <cstddef>
+
 #include "atn/ATNConfigSet.h"
 #include "atn/SemanticContext.h"
 #include "atn/ATNConfig.h"
@@ -17,6 +19,39 @@
 using namespace antlr4::dfa;
 using namespace antlr4::atn;
 
+DFAState::~DFAState() {
+  delete[] _edges.load(std::memory_order_relaxed);
+}
+
+void DFAState::setEdge(size_t index, size_t minSize, DFAState *target) {
+  std::atomic<DFAState *> *edges = _edges.load(std::memory_order_relaxed);
+  size_t count = _edgeCount.load(std::memory_order_relaxed);
+
+  if (edges == nullptr || index >= count) {
+    size_t newCount = std::max(minSize, index + 1);
+    auto *newEdges = new std::atomic<DFAState *>[newCount];
+    for (size_t i = 0; i < count; ++i) {
+      newEdges[i].store(edges[i].load(std::memory_order_relaxed), std::memory_order_relaxed);
+    }
+    for (size_t i = count; i < newCount; ++i) {
+      newEdges[i].store(nullptr, std::memory_order_relaxed);
+    }
+    // Publish the (fully initialized) table: a lock-free getEdge() that
+    // observes this pointer with acquire is guaranteed to see the slot
+    // contents and the updated count.
+    _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.
+    delete[] edges;
+    edges = newEdges;
+  }
+
+  edges[index].store(target, std::memory_order_release);
+}
+
 std::string DFAState::PredPrediction::toString() const {
   return std::string("(") + pred->toString() + ", " + std::to_string(alt) + ")";
 }

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

@@ -12,8 +12,9 @@
 #include <cstddef>
 #include "antlr4-common.h"
 
+#include <atomic>
+
 #include "atn/ATNConfigSet.h"
-#include "FlatHashMap.h"
 
 namespace antlr4 {
 namespace dfa {
@@ -65,12 +66,6 @@ namespace dfa {
 
     std::unique_ptr<atn::ATNConfigSet> configs;
 
-    /// {@code edges[symbol]} points to target of symbol. Shift up by 1 so (-1)
-    ///  <seealso cref="Token#EOF"/> maps to {@code edges[0]}.
-    // ml: this is a sparse list, so we use a map instead of a vector.
-    //     Watch out: we no longer have the -1 offset, as it isn't needed anymore.
-    FlatHashMap<size_t, DFAState*> edges;
-
     /// if accept state, what ttype do we match or alt do we predict?
     /// This is set to <seealso cref="ATN#INVALID_ALT_NUMBER"/> when <seealso cref="#predicates"/>{@code !=null} or
     /// <seealso cref="#requiresFullContext"/>.
@@ -112,6 +107,41 @@ namespace dfa {
 
     explicit DFAState(std::unique_ptr<atn::ATNConfigSet> configs) : configs(std::move(configs)) {}
 
+    DFAState(const DFAState&) = delete;
+    DFAState& operator=(const DFAState&) = delete;
+
+    ~DFAState();
+
+    /// Outgoing DFA edges, mirroring Java's {@code DFAState.edges} array:
+    /// {@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.
+
+    /// 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.
+    DFAState *getEdge(size_t index) const noexcept {
+      std::atomic<DFAState *> *edges = _edges.load(std::memory_order_acquire);
+      if (edges == nullptr || index >= _edgeCount.load(std::memory_order_acquire)) {
+        return nullptr;
+      }
+      return edges[index].load(std::memory_order_acquire);
+    }
+
+    /// Number of edge slots currently allocated (for serialization/iteration).
+    size_t edgeCount() const noexcept { return _edgeCount.load(std::memory_order_acquire); }
+
+    /// 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
+    /// `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.
+    void setEdge(size_t index, size_t minSize, DFAState *target);
+
     /// <summary>
     /// Get the set of all alts mentioned by all ATN configurations in this
     ///  DFA state.
@@ -134,6 +164,12 @@ namespace dfa {
     bool equals(const DFAState &other) const;
 
     std::string toString() const;
+
+  private:
+    // Array of `_edgeCount` atomic edge slots, or nullptr before the first
+    // edge is added. Owned by this state and freed in the destructor.
+    std::atomic<std::atomic<DFAState *> *> _edges{nullptr};
+    std::atomic<size_t> _edgeCount{0};
   };
 
   inline bool operator==(const DFAState &lhs, const DFAState &rhs) {