From eba7b538f453d5f7a4a094f8b8d9d70848ea2a7a Mon Sep 17 00:00:00 2001 From: Paul Bouchon Date: Thu, 20 Aug 2026 15:49:53 -0400 Subject: [PATCH] doc: warn against awaiting replies in module hooks Awaiting a reply from the registering thread inside a resolve or load hook deadlocks: resolution is synchronous from that thread's perspective, so it is blocked in the request and cannot answer. Fixes: https://github.com/nodejs/node/issues/63085 Signed-off-by: Paul Bouchon --- doc/api/module.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/module.md b/doc/api/module.md index 1aac20780c4..5e2fd4946bb 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -1278,6 +1278,12 @@ register('./my-hooks.mjs', { }); ``` +A hook can send messages to the thread that registered it at any time, as +above. It must not wait for a reply while it is running: resolution and loading +are synchronous from the perspective of the thread that triggered them, so that +thread is blocked until the hook settles and cannot answer in the meantime. +Awaiting a reply inside a `resolve` or `load` hook deadlocks both threads. + #### Asynchronous hooks accepted by `module.register()`