diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 7b414a5d1a2263..b39ef6749dd952 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -968,6 +968,45 @@ active handle in the event system. If the worker is already `unref()`ed calling ## Notes +### Synchronous blocking of stdio + +`Worker`s utilize message passing via {MessagePort} to implement interactions +with `stdio`. This means that `stdio` output originating from a `Worker` can +get blocked by synchronous code on the receiving end that is blocking the +Node.js event loop. + +```mjs +import { + Worker, + isMainThread, +} from 'worker_threads'; + +if (isMainThread) { + new Worker(new URL(import.meta.url)); + for (let n = 0; n < 1e10; n++) {} +} else { + // This output will be blocked by the for loop in the main thread. + console.log('foo'); +} +``` + +```cjs +'use strict'; + +const { + Worker, + isMainThread, +} = require('worker_threads'); + +if (isMainThread) { + new Worker(__filename); + for (let n = 0; n < 1e10; n++) {} +} else { + // This output will be blocked by the for loop in the main thread. + console.log('foo'); +} +``` + ### Launching worker threads from preload scripts Take care when launching worker threads from preload scripts (scripts loaded