snapshot of https://github.com/nats-io/nats-server.git (main, 2026-09-15; blobs > 131072B omitted)

locksordering.txt

@@ -0,0 +1,67 @@
+Here is the list of some established lock ordering.
+
+In this list, A -> B means that you can have A.Lock() then B.Lock(), not the opposite.
+
+jetStream -> jsAccount -> Server -> client -> Account
+
+jetStream -> jsAccount -> stream -> consumer
+
+The "prMu" lock protects the peer reconcile signaling state on jetStream, so
+signaling is cheap and never contends on the JS lock. It must not be held while
+acquiring the JetStream lock.
+
+  jetStream -> prMu
+
+A lock to protect jetstream account's usage has been introduced: jsAccount.usageMu.
+This lock is independent and can be invoked under any other lock: jsAccount -> jsa.usageMu, stream -> jsa.usageMu, etc...
+
+A lock to protect the account's leafnodes list was also introduced to
+allow that lock to be held and the acquire a client lock which is not
+possible with the normal account lock.
+
+accountLeafList -> client
+
+AccountResolver interface has various implementations, but assume: AccountResolver -> Server
+
+A reloadMu lock was added to prevent newly connecting clients racing with the configuration reload.
+This must be taken out as soon as a reload is about to happen before any other locks:
+
+    reloadMu -> Server
+    reloadMu -> optsMu
+
+The "jscmMu" lock in the Account is used to serialise calls to checkJetStreamMigrate and
+clearObserverState so that they cannot interleave which would leave Raft nodes in
+inconsistent observer states.
+
+    jscmMu -> Account -> jsAccount
+    jscmMu -> stream.clsMu
+    jscmMu -> RaftNode
+
+The "clsMu" lock protects the consumer list on a stream, used for signalling consumer activity.
+
+    stream -> clsMu
+
+The "clMu" and "ddMu" locks protect clustered and dedupe state respectively.
+The stream lock (`mset.mu`) is optional, but if holding "clMu" or "ddMu",
+locking the stream lock afterward would violate locking order.
+
+    stream -> clMu
+    stream -> clMu -> ddMu
+
+The "mset.batches.mu" lock protects the batching state without needing to hold the stream lock.
+If "clMu" is used to commit a batch, it should only be acquired while already holding the batch lock.
+
+    stream -> mset.batches.mu -> clMu
+
+The "isolateMu" lock isolates direct get and msg get reads from writes, so those reads do not
+observe partially applied rollups or atomic batches. Other read paths (consumer delivery,
+mirrors/sources, info requests, etc.) are sequentially consistent and may observe a prefix of
+an inflight batch. It must be acquired before the stream lock, never while holding it.
+
+    isolateMu -> stream
+
+The "eventIdsMu" lock protects the server's event ID generator. It may be acquired
+while holding the Server lock, but the Server lock must not be acquired while
+holding eventIdsMu.
+
+    Server -> eventIdsMu