doc: clarify synchronous blocking of Worker stdio

jasnell · jasnell · commit 61a67c16253f · 2021-05-17T12:06:18.000-07:00
Fixes: nodejs#25630 Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: nodejs#38658 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -1193,6 +1193,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
