From a2e26c4f29c313eafac190146ea36f99920d0627 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 12 May 2021 13:36:56 -0700 Subject: [PATCH] doc: clarify synchronous blocking of MessagePort Fixes: https://github.com/nodejs/node/issues/25630 Signed-off-by: James M Snell --- doc/api/worker_threads.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 5d0781751ca6b2..cf8b7c37b91ec2 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -679,6 +679,29 @@ The `ArrayBuffer`s for `Buffer` instances created using transferred but doing so renders all other existing views of those `ArrayBuffer`s unusable. +#### Synchronous blocking of message handling + +The `postMessage()` method will defer the actual transmission and +handling of the message until after the current synchronous execution +context completes and the Node.js event loop as allowed to continue +turning. + +In the following example, for instance, the `onmessage` handler for +`mc.port1` will not be invoked until after the `for` loop completes +and the Node.js event loop is not blocked. + +```js +const mc = new MessageChannel(); + +mc.port1.onmessage = console.log; + +mc.port2.postMessage(1); + +for (let n = 0; n < 1e9; n++) { + console.log(n); +} +``` + #### Considerations when cloning objects with prototypes, classes, and accessors Because object cloning uses the [HTML structured clone algorithm][],