doc: add note about AsyncResource for Worker pooling

addaleax · BridgeAR · commit 5fc4e48fdd13 · 2019-06-17T21:12:12.000+02:00
When implementing a pool for Worker threads, the correlation between posting tasks and getting their results may get lost, depending on the implementation. The `AsyncResource` API is the primary way to solve that issue, so link it from the recommendation in the worker docs. (This was brought up at the collaborator summit in Berlin.) PR-URL: #28023 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -49,6 +49,10 @@ The above example spawns a Worker thread for each `parse()` call. In actual
 practice, use a pool of Workers instead for these kinds of tasks. Otherwise, the
 overhead of creating Workers would likely exceed their benefit.
 
+When implementing a worker pool, use the [`AsyncResource`][] API to inform
+diagnostic tools (e.g. in order to provide asynchronous stack traces) about the
+correlation between tasks and their outcomes.
+
 ## worker.isMainThread
 <!-- YAML
 added: v10.5.0
@@ -653,6 +657,7 @@ active handle in the event system. If the worker is already `unref()`ed calling
 `unref()` again will have no effect.
 
 [`'close'` event]: #worker_threads_event_close
+[`AsyncResource`]: async_hooks.html#async_hooks_class_asyncresource
 [`Buffer`]: buffer.html
 [`EventEmitter`]: events.html
 [`EventTarget`]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
