Streaming & Backpressure Across Threads

A worker that parses a 2 GB log file can produce parsed records far faster than a page can render them. Nothing in postMessage notices. The queue grows inside the browser, the tab’s memory climbs past a gigabyte, and the heap snapshot shows nothing unusual — because the pending messages are not on the JavaScript heap at all.

This topic belongs to High-Performance Computation Patterns and covers the discipline that prevents it: making the producer’s rate depend on the consumer’s progress. Two mechanisms do that — transferable streams, where the platform handles it, and credit-based flow control, where you do — plus the instrumentation that tells you which one is failing.

The Failure: A Queue With No Ceiling

The naive shape is the one everybody writes first:

// worker.ts — a producer with no idea whether anyone is reading
for await (const batch of parseLogFile(file)) {
  self.postMessage({ kind: 'BATCH', batch }, [batch.buffer]);   // returns instantly, always
}
self.postMessage({ kind: 'END' });

postMessage never blocks and never rejects. Each call enqueues a message in the receiving agent’s task queue; the browser holds it in internal memory until the receiving event loop gets to it. If the page spends 14 ms rendering each batch and the worker produces one every 2 ms, the queue grows by six messages every 16 ms — around 22 MB per second at 64 kB per chunk.

The failure signature is worth memorising, because it is unlike an ordinary leak:

• Memory grows in the browser process, not in the JS heap. A heap snapshot of both threads accounts for a few megabytes while the task manager shows a gigabyte.
• The consumer becomes progressively less responsive, because its event loop is saturated by a backlog it cannot drain.
• Cancellation does nothing. Terminating the worker stops production but the queued messages have already been handed to the consumer.
• It scales with hardware in the wrong direction. A faster machine produces faster, so the gap widens.

Prerequisites

• A consumer whose per-chunk cost you have measured. Flow control is calibrated against it; without a number, any credit limit is a guess.
• Chunked data. A single 500 MB blob is not a stream — it is one message, and it belongs in Transferable Objects & Zero-Copy.
• A module worker, so ReadableStream and TextDecoderStream are available with the same spellings on both sides.
• An end-of-stream marker in the protocol, explicit and unambiguous, even if you also use streams elsewhere.
• A cancellation path. Streams give you one; a hand-written protocol needs a control message the producer actually checks.

Step 1 — Transfer the Stream, Not the Chunks

The platform already solved this problem, and the solution is transferable. A ReadableStream, WritableStream or TransformStream can appear in a transfer list, after which the object belongs to the receiving agent and the browser tunnels chunks between threads with backpressure intact.

// page.ts — hand the file's byte stream to the worker
const worker = new Worker(new URL('./parse.worker.ts', import.meta.url), { type: 'module' });
const stream = file.stream();                        // ReadableStream<Uint8Array>

worker.postMessage({ kind: 'PARSE', stream }, [stream]);   // the stream itself moves

// parse.worker.ts — read at whatever pace the parser can manage
self.addEventListener('message', async (event: MessageEvent) => {
  const { stream } = event.data as { stream: ReadableStream<Uint8Array> };
  const reader = stream.pipeThrough(new TextDecoderStream()).getReader();

  for (;;) {
    const { value, done } = await reader.read();     // pulls only when ready
    if (done) break;
    parseChunk(value);
  }
  self.postMessage({ kind: 'END' });
});

The await reader.read() is the whole mechanism. The reader pulls one chunk at a time; the source produces the next only when asked. If the parser slows down, the file reader slows down with it, and nothing accumulates anywhere — the queue is bounded by the stream’s own high-water mark, which defaults to one chunk for byte streams.

Step 2 — Credit-Based Flow Control Where Streams Do Not Fit

Streams are the right answer when the data is stream-shaped and the engines support them. Two situations call for something else: a protocol where chunks are results rather than bytes (parsed record batches, rendered tiles, search hits), and support floors that predate transferable streams.

The mechanism is the one TCP uses: the consumer grants credits, the producer spends them.

// worker.ts — the producer half
let credits = 0;
let pending: (() => void) | null = null;

self.addEventListener('message', (event: MessageEvent) => {
  if (event.data.kind === 'CREDIT') {
    credits += event.data.n as number;
    pending?.();                       // wake the paused producer
    pending = null;
  }
});

async function awaitCredit(): Promise<void> {
  if (credits > 0) return;
  await new Promise<void>((resolve) => { pending = resolve; });
}

export async function produce(source: AsyncIterable<Float64Array>): Promise<void> {
  for await (const batch of source) {
    await awaitCredit();               // the only line that matters
    credits--;
    self.postMessage({ kind: 'BATCH', batch }, [batch.buffer]);
  }
  self.postMessage({ kind: 'END' });
}

// page.ts — the consumer half
const CREDIT_LIMIT = 8;
worker.postMessage({ kind: 'CREDIT', n: CREDIT_LIMIT });     // prime the pipeline

worker.addEventListener('message', async (event: MessageEvent) => {
  if (event.data.kind !== 'BATCH') return;
  await render(event.data.batch);                            // the slow part
  worker.postMessage({ kind: 'CREDIT', n: 1 });              // return exactly one
});

Peak memory is now CREDIT_LIMIT × chunkSize, chosen rather than discovered. Eight is a good starting point: enough in flight that the producer is never idle waiting for a round trip, few enough that a 1 MB chunk size caps the queue at 8 MB.

Step 3 — Size the Chunks

Chunk size trades per-message overhead against per-message latency, and the useful range is narrower than people expect.

Two rules generalise from it. Keep transport under 10% of total job time — measure one chunk end to end and multiply. And keep a single chunk’s handling under 8 ms on the consumer, so processing one never costs a dropped frame. Where the consumer renders, that second rule usually binds first and points at 64–256 kB.

Always transfer binary chunks rather than cloning them: postMessage(chunk, [chunk.buffer]) moves the bytes and removes the copy from both sides of the hop.

Step 4 — Adapt the Window Instead of Guessing It

A fixed credit limit is a compromise between two failure modes: too low and the producer idles for a round trip after every chunk; too high and peak memory is larger than it needs to be. When chunk cost varies — records that are sometimes 40 kB and sometimes 4 MB — a fixed count is wrong in both directions at different moments.

Two adjustments fix most of it without inventing a congestion-control algorithm.

Grant credits in bytes, not chunks. The consumer tracks how many bytes it has released rather than how many messages it handled, so a window expressed as “16 MB in flight” holds regardless of chunk size:

// consumer: a byte-denominated window
const WINDOW_BYTES = 16 * 1024 * 1024;
let outstanding = 0;

worker.addEventListener('message', async (event: MessageEvent) => {
  const { batch } = event.data as { batch: Float64Array };
  outstanding += batch.byteLength;
  await render(batch);
  outstanding -= batch.byteLength;
  worker.postMessage({ kind: 'CREDIT', bytes: batch.byteLength });
});

Keep two chunks in flight, minimum. The producer should always have permission for the next chunk while the consumer works on the current one; otherwise every chunk costs a full round trip of dead time. A floor of two credits (or two chunks’ worth of bytes) is the difference between a pipeline and a ping-pong game, and it costs one extra chunk of memory.

Anything beyond that — measuring consumer latency and growing the window until throughput stops improving — is worth doing only when the consumer’s cost varies by an order of magnitude within one job. For most pipelines, a byte window sized at 8–32 MB with a two-chunk floor is within a few percent of optimal and has no tuning surface to get wrong later.

Advanced: A Pipeline Across a Pool

Streaming and parallelism interact awkwardly, because a pool destroys ordering. Three shapes are worth knowing.

Serial stages, one worker each. Decode in worker A, transform in worker B, aggregate on the page. Each pair of stages is its own flow-controlled link, and the slowest stage sets the rate for everything upstream — which is exactly what backpressure is for. Transferable streams shine here: readable ends can be transferred from worker to worker directly through a MessageChannel, without the page relaying chunks.

Fan-out to N workers, unordered. Suitable when results carry their own identity — tiles, records with keys, search hits. The dispatcher hands chunk i to whichever worker is idle, and the consumer reassembles by key. Credits are per-worker, so the total in flight is N × limit; size the per-worker limit accordingly, or the memory ceiling multiplies quietly with hardwareConcurrency.

Fan-out with a reorder buffer. Required when output order must match input order. The consumer holds completed-but-early results until their predecessors arrive, which means the buffer can grow to the spread between the fastest and slowest worker. Cap it explicitly and stop granting credits when it fills, or the reorder buffer becomes the unbounded queue you removed from the transport.

The pool mechanics — sizing, idle tracking, dispatch — are covered in Worker Pool Management; what changes in a streaming context is only that each worker needs its own credit accounting rather than one global counter.

Data-Transfer Strategy for Streams

The ring-buffer row is the one to reach for when the rate is fixed and the latency budget is sub-millisecond — audio, sensors, simulation frames. There the queue is a fixed allocation by construction and the coordination is done with Atomics, as in Building a Lock-Free Ring Buffer with Atomics.

Verification & Measurement

Export queue depth as a number. With credits, the producer already knows it: sent - acknowledged. Log the maximum per job, and alert on any job whose depth reaches the credit limit for more than a second — that is a consumer that has stopped consuming.

// producer: two counters and one derived metric
let sent = 0, acked = 0;
// …on post: sent++      …on credit: acked++
const depth = () => sent - acked;
performance.measure(`stream-depth-${depth()}`, { start: performance.now(), duration: 0 });

Watch the receiving event loop, not the sending one. A saturated consumer shows long tasks back to back with no idle gaps; the profiling technique is in Profiling Worker CPU Usage with the Chrome Performance Tab. A producer-bound pipeline looks the opposite: an idle consumer waiting between chunks.

Reproduce a slow consumer deliberately. Flow control is only exercised when the consumer lags, which on a development machine it rarely does. Add a test mode that inserts an artificial delay per chunk — await new Promise(r => setTimeout(r, 40)) — and confirm three things: peak memory stays at the designed ceiling, the producer parks rather than spins, and cancelling mid-job actually stops production. A pipeline that has never been run against a slow consumer has never had its backpressure tested.

Compare wall clock against the theoretical floor. Total time should approach chunks × consumerCostPerChunk. Materially longer means transport overhead — chunks too small — or a credit limit so low the producer stalls waiting for round trips.

Failure Modes & Error Handling

Two consumers on one channel. Adding a second message listener that also handles chunks doubles the work and halves the credits returned per chunk, because only one listener owns the accounting. Keep one owner per channel and fan out inside it.

A lost end marker hangs the job forever. If END is posted but the consumer had already unsubscribed, or an error path skips it, the consumer waits indefinitely. Make completion explicit and idempotent, and add a watchdog timeout for jobs whose duration you can bound.

Cancellation that does not reach the producer. With streams, reader.cancel() propagates to the source. With a credit protocol, nothing propagates unless you send a CANCEL message and the producer checks it between chunks — a tight loop that never yields will not see it. The abortable-task patterns in Cancelling Worker Tasks with AbortSignal apply directly.

Errors that vanish mid-stream. A throw inside the producer’s loop rejects a promise nobody is awaiting. Catch it, post an ERROR message with a serialised cause, and have the consumer reject its own completion promise — see Structured Error Serialization Across Threads.

A window sized from a fast machine. The consumer’s per-chunk cost is several times higher on a low-end phone, which changes the ideal window. Derive it at runtime from measured consumer latency rather than hard-coding a constant tuned on a laptop.

Reusing a transferred chunk. Once posted with a transfer list the buffer is detached in the producer; a producer that recycles a scratch buffer across iterations will find it empty on the second pass. Allocate per chunk, or use a pool of buffers the consumer returns.

A producer that never yields. Flow control assumes the producer’s loop reaches an await between chunks; a synchronous loop that computes for 400 ms cannot see a credit message, a cancel message, or anything else, because the worker’s event loop never runs. Any producer whose per-chunk work is long must yield explicitly — the chunking techniques in Breaking Long Tasks into Yielding Chunks apply on the worker thread exactly as they do on the main one.

Credit leaks. A consumer that throws while rendering and never returns the credit permanently reduces the window; after N failures the pipeline is deadlocked at zero credits. Return credits in a finally.

Browser Compatibility

Transferable streams are the newest of these; a support floor below Safari 16.4 is the main reason to write a credit protocol instead. Async iteration over a ReadableStream (for await (const chunk of stream)) landed later still and is not yet universal, so prefer an explicit getReader() loop in portable code.