The memory model

What the memory model promises

A worker is a second JavaScript program that runs at the same time as your page. Each worker has its own variables. Usually, nothing is shared.

A SharedArrayBuffer changes that. It is a block of bytes that the page and its workers can all read and write. When two programs touch the same bytes at the same time, you need rules for what each one sees. Those rules are the memory model.

A few words you will see in this lesson:

• An agent is one running JavaScript program, like the page or one worker.
• A cell is one numbered spot in shared memory, like cells[0].
• An atomic operation is one step that no other agent can split in the middle. The Atomics functions, like Atomics.add, are atomic.
• A plain read or write is the normal kind, like cells[0] = 5. It is not atomic.

This lesson follows SharedArrayBuffer & Atomics. That lesson showed the functions. This one explains the order rules behind them. The next lesson, Parallel patterns with workers, uses these rules to build groups of workers.

Data races

A data race happens when all of these are true:

• Two agents use the same shared cell.
• At least one of them writes to it.
• At least one of the two uses a plain read or write.
• Nothing decides which one goes first.

A line like cells[0] += 1 looks like one small step. It is really three steps: read the old value, add one, and write the new value. Another agent can act between those steps.

1let balance = 100;2const a = balance;3const b = balance;4balance = a + 50;5balance = b + 50;6console.log(balance);

This code acts out two agents, A and B, in one fixed order. Here is what each line does:

• Line 1 starts the balance at 100.
• Line 2 is A reading the balance. A keeps 100.
• Line 3 is B reading the balance. B also keeps 100.
• Line 4 is A writing its deposit: 100 + 50, so 150.
• Line 5 is B writing its deposit. B still uses its old 100, so it also writes 150.
• Line 6 prints 150. One deposit of 50 is lost.

We picked this order on purpose, so the lost deposit is easy to see. A real race does not always lose exactly one deposit. Real agents can run in other orders, and the rules allow even stranger values. So the rule is simple: never trust a result that comes from a data race.

Step through a lost deposit

The replay below runs the same balance code, one line at a time. It shows one bad order of plain reads and writes. It is a recording of this small model. It does not watch real workers, and it cannot tell you the order your workers will use.

1let balance = 100;Run2const a = balance;3const b = balance;4balance = a + 50;5balance = b + 50;6console.log(balance);

Start with the two reads. A and B each keep 100 in their own variable. Then A writes 150. B still holds its old 100, so B also writes 150, over the top of A's value. The deposit was lost between B's read and B's write. Addition worked fine; the order was the problem.

1let balance = 100;2let a;3let b;4// Choose each step below in the playground.5a = balance;6b = balance;7balance = a + 50;8balance = b + 50;9console.log(balance);

Now pick the steps in a different order. If A reads and writes before B reads, the plain model reaches 200. Switch to atomic deposits: each write becomes one Atomics.add, which reads, adds, and writes as one step. Then the two deposits always reach 200 in this model.

One shared order for atomic steps

Atomic operations follow a rule called sequential consistency. It means:

• All atomic operations happen one at a time, in one list.
• Every agent agrees on that list.
• Each agent's own atomic steps appear in the list in the same order as in its code.

Picture one shared notebook. Every atomic step is written on its own line, and every agent reads the same notebook.

1const cell = new Int32Array(new ArrayBuffer(4));2Atomics.store(cell, 0, 100);3Atomics.add(cell, 0, 50);4Atomics.add(cell, 0, 50);5console.log(Atomics.load(cell, 0));

• Line 1 makes one cell that holds a whole number. An Int32Array is a list of whole numbers stored in bytes.
• Line 2 uses Atomics.store to put 100 in cell 0.
• Lines 3 and 4 each use Atomics.add to add 50. No other atomic step can land in the middle of either add.
• Line 5 uses Atomics.load to read the cell. It prints 200.

This small example uses a normal ArrayBuffer, so it can run in the page. With workers you would use a SharedArrayBuffer instead. The order rule is the same.

Atomic steps protect only the cells they touch. They do not protect your whole app. So give each cell one clear job, such as a flag, a counter, or a lock. Do not mix plain and atomic access on the same cell when agents compete for it. The specification recommends programs with no data races. In those programs, everything happens in an order you can follow.

The table below compares four ways to use shared cells. Read each row as: "this kind of access is this, follows this order rule, and is good for this job."

Share a value with a ready flag

Here is a common way for one agent to hand a value to another. It uses two cells:

• A data cell holds the value. It uses plain reads and writes.
• A ready flag cell says "the data is there". It uses atomic steps only. 0 means not ready, and 1 means ready.

The writer fills the data cell first. Then it sets the flag to 1. The reader checks the flag first. It reads the data only after it sees 1.

1const cells = new Int32Array(new ArrayBuffer(8));2const data = 0;3const ready = 1;4cells[data] = 42;5Atomics.store(cells, ready, 1);6if (Atomics.load(cells, ready) === 1) {7  console.log(cells[data]);8}

• Line 1 makes two cells.
• Lines 2 and 3 name them: cell 0 is data, and cell 1 is ready.
• Line 4 puts 42 in the data cell, with a plain write.
• Line 5 uses Atomics.store to set the ready flag to 1.
• Line 6 uses Atomics.load to read the flag.
• Only when the flag is 1 does line 7 read the data. It prints 42.

The flag works because both agents use atomic steps on it. That gives them one shared moment to agree on: "ready became 1". Everything the writer did before that moment is there for the reader after it sees the 1.

This is a small teaching example, not a full mailbox. A real worker setup also has to decide:

• Which agent is allowed to write each cell.
• Whether the data can be replaced, and when.
• How a waiting agent finds out that the flag changed.

For job details with many fields, use postMessage, which sends a copy of a value to a worker. Use shared cells only when a small shared value really helps.

Spin locks and the pause hint

A lock lets only one agent at a time use some shared data. The lock is one cell:

• 0 means unlocked: anyone may take it.
• 1 means locked: one agent is using the data.

A spin lock keeps trying to take the lock, again and again, instead of going to sleep. That can make sense for a very short wait inside a worker. But every failed try keeps the processor busy.

To take the lock, the code uses Atomics.compareExchange. This is a compare-and-swap: "if the cell still holds this value, swap in that value". It does the check and the swap as one step, and it gives back the value the cell had before.

1function pauseHint() {2  if (typeof Atomics.pause === "function") Atomics.pause();3}4 5function tryLock(lock) {6  return Atomics.compareExchange(lock, 0, 0, 1) === 0;7}8 9function unlock(lock) {10  Atomics.store(lock, 0, 0);11}12 13const lock = new Int32Array(new ArrayBuffer(4));14console.log(tryLock(lock));15unlock(lock);16console.log(Atomics.load(lock, 0));

• Lines 1 to 3 call Atomics.pause only if it exists. typeof gives the kind of a value as text, such as "function".
• Lines 5 to 7 try to take the lock. If the cell holds 0, it becomes 1. The call gives back the old value, so the result is true only when the old value was 0.
• Lines 9 to 11 give the lock back by storing 0.
• Line 13 makes the lock cell. It starts at 0.
• Line 14 takes the lock and prints true.
• Line 15 gives it back, and line 16 prints 0.

Atomics.pause returns nothing you can use. It is only a hint to the processor: "I am waiting in a loop." On some computers it does nothing at all. It exists in Node 24 and newer browsers, but not in Node 22. That is why the code checks for it first.

For a long wait inside a worker, use Atomics.wait instead. It puts the worker to sleep until a cell changes. Never spin on the page's main thread: the page freezes while the loop runs.

Try again instead of locking

A lock-free design changes shared cells without a lock. It uses compare-and-swap in a loop:

1. Read the cell.
2. Work out the new value.
3. Swap it in, but only if the cell still holds the value you read.
4. If another agent changed the cell first, go back to step 1.

One agent may have to try again. But each time a swap works, the work moves forward, so no agent is ever stuck waiting for a lock. Lock-free is a choice for some designs. You don't need it for every counter.

1const cell = new Int32Array(new ArrayBuffer(4));2Atomics.store(cell, 0, 3);3const observed = Atomics.load(cell, 0);4Atomics.compareExchange(cell, 0, observed, observed + 1);5console.log(Atomics.load(cell, 0));

• Line 1 makes one cell.
• Line 2 stores 3 in it.
• Line 3 reads the cell and keeps 3 in observed.
• Line 4 asks: "if the cell still holds 3, put 4 in".
• Nothing else changed the cell, so line 5 prints 4.

If another agent changes the cell first, the swap does nothing. It gives back the value that is really in the cell now. The loop reads again, works out a new value, and tries again.

1const cell = new Int32Array(new ArrayBuffer(4));2Atomics.store(cell, 0, 3);Run3const observed = Atomics.load(cell, 0);4Atomics.store(cell, 0, 4); // another agent changes the cell5const firstOld = Atomics.compareExchange(cell, 0, observed, observed + 1);6const fresh = Atomics.load(cell, 0);7Atomics.compareExchange(cell, 0, fresh, fresh + 1);8console.log(Atomics.load(cell, 0));

The replay adds a change from another agent on line 4, between the read and the first swap. The cell is now 4. So the first swap, on line 5, still expects 3. It gives back 4 and changes nothing. The retry reads 4 on line 6 and swaps in 5 on line 7. Line 8 prints 5.

Real lock-free lists and stacks have harder problems, such as items that are removed while another agent is still using them. That is why a single counter is the right first example.

Two real workers, exact totals

The examples so far act out one chosen order. Now for real workers. Node has a module called worker_threads that starts workers. The lesson's tests run two programs with it, and both always give the same answer.

In the first program, two workers each run Atomics.add one thousand times on one shared counter. The total is always exactly 2000.

1const { Worker, isMainThread, workerData, parentPort } = require("node:worker_threads");2if (isMainThread) {3  const buffer = new SharedArrayBuffer(4);4  const workers = [0, 1].map(() => new Worker(__filename, { workerData: buffer }));5  Promise.all(workers.map((worker) => new Promise((done) => worker.once("exit", done))))6    .then(() => console.log(new Int32Array(buffer)[0]));7} else {8  const cell = new Int32Array(workerData);9  for (let index = 0; index < 1000; index += 1) Atomics.add(cell, 0, 1);10  parentPort.close();11}

• Line 1 loads the worker tools. The same file runs as the main program and as each worker; isMainThread tells them apart.
• Line 3 makes 4 shared bytes: room for one counter.
• Line 4 starts two workers and gives each the shared bytes.
• Lines 5 and 6 wait until both workers stop, then print the counter.
• In each worker, line 8 makes a view of the shared bytes, and line 9 adds 1 a thousand times with Atomics.add.

The test saves this program to a short-lived file, runs it, and checks that it prints 2000.

1const { Worker, isMainThread, workerData, parentPort } = require("node:worker_threads");2if (isMainThread) {3  const buffer = new SharedArrayBuffer(8);4  const workers = [0, 1].map(() => new Worker(__filename, { workerData: buffer }));5  Promise.all(workers.map((worker) => new Promise((done) => worker.once("exit", done))))6    .then(() => console.log(new Int32Array(buffer)[1]));7} else {8  const cells = new Int32Array(workerData);9  for (let index = 0; index < 1000; index += 1) {10    while (Atomics.compareExchange(cells, 0, 0, 1) !== 0) {}11    cells[1] += 1;12    Atomics.store(cells, 0, 0);13  }14  parentPort.close();15}

The second program uses two cells. Cell 0 is the lock, and it only gets atomic steps. Cell 1 is a counter that gets a plain write.

• Line 10 keeps trying until it takes the lock.
• Line 11 adds 1 to the counter with a plain write. This is safe, because only the lock holder can be here.
• Line 12 gives the lock back.

Again, the two workers print exactly 2000.

Neither test tries to prove that a plain race loses a deposit. That result changes from run to run, so a test for it would sometimes pass and sometimes fail. The lesson uses the fixed-order model to show the danger, and real workers only for results that never change.

Pick the simplest tool that works

Start with messages. A group of workers can get each job with postMessage and send the result back the same way. Add shared memory only for a small value that many agents touch often, and only after you have designed and tested it. Good examples:

• A counter of finished jobs.
• A ready flag.
• The position in a small shared queue.

For every shared cell, answer these plain questions:

• What is this cell for? Write it down in a comment.
• Is it an atomic flag or plain data? Keep those in separate cells.
• Which agent is allowed to write it?
• When may a reader look at it?
• How does a waiting worker find out it changed?

These questions stop most shared-memory bugs before you think about speed.

Common misconceptions

• “A race always prints the wrong number.” A race can print the right number in one run and the wrong one in the next. You can't trust it either way.
• “A data race can make JavaScript crash or do anything.” No. The rules list which values a race may give. The values can surprise you, but the program keeps running.
• “Atomic protects everything near it.” An atomic step protects only the one cell it touches. How the other cells stay safe is up to your design.
• “Atomics.pause is a sleep.” It is only a hint while the code loops, and it may do nothing at all.
• “Lock-free means no retries.” A compare-and-swap loop tries again whenever another agent changed the cell first.

The table below lists four terms that are easy to mix up. Read each row as: "this term means this, and it does not mean that."

The specification gives careful advice: write programs with no data races. Use atomic steps every time agents compete for a cell. Never use plain access and atomic access on the same cell that agents compete for.

Practice exercises

let balance = 100;
const a = balance;
const b = balance;
balance = a + 50;
balance = b + 50;
console.log(balance);

let balance = 100;
const a = balance;
const b = balance;
balance = a + 50;
balance = b + 50;
console.log(balance);

const cell = new Int32Array(new ArrayBuffer(4));
Atomics.store(cell, 0, 100);
Atomics.add(cell, 0, 50);
Atomics.add(cell, 0, 50);
console.log(Atomics.load(cell, 0));

const cell = new Int32Array(new ArrayBuffer(4));
Atomics.store(cell, 0, 100);
Atomics.add(cell, 0, 50);
Atomics.add(cell, 0, 50);
console.log(Atomics.load(cell, 0));

const cells = new Int32Array(new ArrayBuffer(8));
const data = 0;
const ready = 1;
cells[data] = 42;
Atomics.store(cells, ready, 1);
if (Atomics.load(cells, ready) === 1) {
  console.log(cells[data]);
}

const cell = new Int32Array(new ArrayBuffer(4));
Atomics.store(cell, 0, 3);
const observed = Atomics.load(cell, 0);
Atomics.compareExchange(cell, 0, observed, observed + 1);
console.log(Atomics.load(cell, 0));

const cell = new Int32Array(new ArrayBuffer(4));
Atomics.store(cell, 0, 3);
const observed = Atomics.load(cell, 0);
Atomics.compareExchange(cell, 0, observed, observed + 1);
console.log(Atomics.load(cell, 0));

Check your understanding

For each question, find the shared cell first. Then ask: is each read or write plain or atomic, and which agent sees what?

Key takeaways

• A data race is when agents clash on one shared cell and at least one uses a plain read or write. Never trust a result from a race.
• Atomic steps happen one at a time, in one order that every agent agrees on. This is called sequential consistency.
• To share a value, write the data first, then set a ready flag with Atomics.store. The reader checks the flag with Atomics.load before it reads the data.
• Check that Atomics.pause exists before you call it. Use it only as a hint in a short spin. For long waits, use Atomics.wait.
• A lock-free compare-and-swap loop tries again with the new value when another agent changed the cell first.
• Messages are usually the clearest way to send work to workers. Shared atomic cells suit small values that many agents touch.

Coming next: Parallel patterns with workers. There, these small rules grow into groups of workers, message plans, and fast ways to move data.