A SharedArrayBuffer is a block of raw memory that can be used by more than one thread at the same time. Normally, when you send data to a Web Worker, JavaScript copies it. With a SharedArrayBuffer, the main page and the workers all look at the same bytes, so nothing is copied and a change made by one thread is seen by the others.
Like an ArrayBuffer, it only stores bytes. To read and write them, you create a typed array such as Int32Array on top of it. To change shared numbers safely from several threads, use the Atomics methods.
For security, a browser only provides SharedArrayBuffer when the page sends the right headers. If typeof SharedArrayBuffer is "undefined" on your page, that is the reason. Node.js has no such rule.
Syntax
JavaScript Syntax
Create a shared buffer, read and write it through a view, and try the two methods:
JavaScript
const buffer = new SharedArrayBuffer(8); // 8 bytes of shared memory
const numbers = new Int32Array(buffer); // a view: 2 numbers of 4 bytes
numbers[0] = 42;
console.log(Atomics.add(numbers, 1, 5)); // 0 (the old value)
console.log(buffer.byteLength); // 8
const growable = new SharedArrayBuffer(8, { maxByteLength: 32 });
growable.grow(16); // make it bigger, in place
console.log(growable.byteLength); // 16
const copy = growable.slice(0, 8); // copy 8 bytes to a new buffer
console.log(copy.byteLength); // 8
Reference
Core Ideas
Ideas every SharedArrayBuffer tutorial in this series builds on:
Idea
Example
Remember
SharedArrayBuffer
new SharedArrayBuffer(8)
A fixed amount of raw bytes that threads can share
byteLength
buffer.byteLength
The size of the buffer in bytes
View
new Int32Array(buffer)
A typed array that reads and writes the shared bytes
Atomics
Atomics.add(view, 0, 1)
Safe reads and writes when several threads work together
Growable buffer
{ maxByteLength: 32 }
A buffer that can grow later, up to a limit
grow()
buffer.grow(16)
Makes a growable buffer bigger in place; it never shrinks
slice()
buffer.slice(0, 4)
Copies a range of bytes into a new, separate buffer
Compare
SharedArrayBuffer vs ArrayBuffer
Both store raw bytes. The big difference is what happens when you send the buffer to another thread:
Feature
ArrayBuffer
SharedArrayBuffer
Sent to a worker
Copied, or moved with a transfer list
Shared: both threads see the same bytes
After sending
A moved buffer is detached (length 0)
Still fully usable on both sides
Change the size
resize() can grow and shrink
grow() can only grow
Copy a range
slice()
slice() (the copy is not shared)
Safe updates from threads
Not needed
Use Atomics
Available in browsers
Always
Only on cross-origin isolated pages
Use a normal ArrayBuffer when one thread owns the data. Use a SharedArrayBuffer when several threads must work on the same bytes. Example 3 shows the difference.
Behavior
How SharedArrayBuffer Works
It is only memory
A SharedArrayBuffer has no items of its own, just a number of bytes. You create a typed array view to read and write it, and several views can look at the same buffer.
Sharing, not copying
When you send a SharedArrayBuffer to a worker with postMessage(), the worker receives a handle to the same memory. Nothing is duplicated, which makes it fast for large data.
Threads can collide
If two threads change the same number at the same time, one change can be lost. The Atomics methods make a read or a write happen in one safe step. Example 2 shows Atomics.add().
The size can grow, never shrink
A buffer created with maxByteLength is growable, and grow() adds zero bytes at the end. There is no way to make a shared buffer smaller.
Browsers ask for isolation
The page must send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Then self.crossOriginIsolated is true and SharedArrayBuffer exists.
Practice
Real-Life Uses
You will rarely need shared memory in everyday code. It helps in a few special places:
Use
How shared memory helps
Big data in workers
Let a worker process an image, audio or game world while the page keeps using the same bytes, without copying them.
Counters and flags
Share a progress counter or a "stop" flag between a worker and the page with Atomics.
Queues between threads
Build a ring buffer in shared memory so one thread can hand work to another.
WebAssembly threads
Threaded WebAssembly programs keep their memory in a shared buffer.
Code
JavaScript Examples
Three short programs. Each one prints plain text that is the same every time you run it, and they all run in Node.js.
Example 1 — Create a Shared Buffer and Look at It
Create a shared buffer, put two views on it, and see that a change through one view shows up in the other.
JavaScript
const buffer = new SharedArrayBuffer(8);
const first = new Int32Array(buffer);
const second = new Int32Array(buffer);
first[0] = 42;
console.log("typeof: " + typeof buffer);
console.log("byteLength: " + buffer.byteLength);
console.log("Int32 items: " + first.length);
console.log("Seen through second view: " + second[0]);
console.log("Instance of ArrayBuffer: " + (buffer instanceof ArrayBuffer));
Counter: 5
Old value from add: 5
New value: 15
Value from store: 100
How It Works
Add in one safe step.Atomics.add(counter, 0, 1) adds 1 to item 0. Unlike counter[0]++, no other thread can sneak in halfway through.
Read safely.Atomics.load() reads the current value. Atomics.add() returns the old value, which is why the second line prints 5 and the next read shows 15.
Store a value.Atomics.store() writes a number and returns that same number, so the last line prints 100.
Example 3 — See the Difference from ArrayBuffer
structuredClone() copies data the same way postMessage() does. Send an ArrayBuffer by moving it, and a SharedArrayBuffer by sharing it.
JavaScript
const normal = new ArrayBuffer(8);
const moved = structuredClone(normal, { transfer: [normal] });
console.log("ArrayBuffer after sending: " + normal.byteLength);
console.log("ArrayBuffer received: " + moved.byteLength);
const shared = new SharedArrayBuffer(8);
const received = structuredClone(shared);
new Int32Array(shared)[0] = 7;
console.log("SharedArrayBuffer after sending: " + shared.byteLength);
console.log("Received buffer sees the change: " + new Int32Array(received)[0]);
console.log("Same buffer object: " + (shared === received));
ArrayBuffer after sending: 0
ArrayBuffer received: 8
SharedArrayBuffer after sending: 8
Received buffer sees the change: 7
Same buffer object: false
How It Works
A normal buffer is moved. With transfer, the bytes go to moved and the original is detached: its byteLength drops to 0.
A shared buffer stays usable. After structuredClone(shared), the original still has 8 bytes. There is nothing to move, because both sides point at the same memory.
The change is visible. The value 7 is written through the original and read through received. The two variables are different objects, but they are handles to the same bytes.
Continue
SharedArrayBuffer Methods
A SharedArrayBuffer has two methods of its own. Each one has its own tutorial:
It is a block of raw memory that several threads, such as the main page and Web Workers, can use at the same time. You read and write it through typed arrays, and you use Atomics when several threads change the same values.
When you send an ArrayBuffer to a worker, it is copied or moved, and a moved buffer becomes unusable on the sending side. A SharedArrayBuffer is shared instead, so both sides keep using the same bytes. In browsers a SharedArrayBuffer also needs a cross-origin isolated page.
Browsers only provide it when the page is cross-origin isolated. The server has to send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Then self.crossOriginIsolated is true. Node.js does not have this rule.
Only when several threads change the same values. Plain reads and writes can collide, and Atomics makes each step safe. If only one thread writes and the others read after a signal, simple code may be enough.
Yes, but only to grow. Create it with new SharedArrayBuffer(length, { maxByteLength }) and call grow(newLength) later. It can never get smaller. A normal ArrayBuffer can use resize() to grow and shrink.