doc: add note about AsyncResource for Worker pooling #28023
Conversation
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.)
addaleax
added
doc
doc/api/worker_threads.md
Outdated
| @@ -48,6 +48,9 @@ if (isMainThread) { | |||
| 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, it is strongly recommended to use the | |||
| [`AsyncResource`][] API to inform diagnostic tools (for e.g. asynchronous stack | |||
There was a problem hiding this comment.
Typo: for e.g. should be either for example or e.g., although I would go with such as:
| [`AsyncResource`][] API to inform diagnostic tools (for e.g. asynchronous stack | |
| [`AsyncResource`][] API to inform diagnostic tools (such as asynchronous stack |
There was a problem hiding this comment.
@Trott I don’t think for example or just e.g. would work here, as asynchronous stack traces aren’t diagnostic tools by themselves, but rather provided by them. I’ve changed this to e.g. in order to provide asynchronous stack traces, maybe that works for you?
There was a problem hiding this comment.
(Total ignorable nit: Maybe drop "in order"?)
|
@addaleax - does this mean that the result of a computation coming from a pooled thread can only be consumed by tools, not the calling code? how about attaching a |
It means that the code that calls into worker pools and reads from them should perform async tracking. It means that tools that provide worker pools should do that, and in that case, the user of that tool should not need to be concerned with async tracking, because that’s already taken care of. Does that answer your question?
I don’t understand what you are suggesting here, tbh. Each worker does get assigned a unique ID, and worker’s generally don’t return anything – they do emit message events, but you can use |
addaleax
added
the
author ready
|
@addaleax - thanks for the clarification. Yes, I was referring to the scenario wherein a number of tasks are pushed onto pooled threads, and be able to identify tasks when they complete and post messages / result. Your explanation helped me understand that the unique worker ID can be used for that purpose. |
|
Landed in 55de209 |
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>
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>
When implementing a pool for Worker threads, the correlation between
posting tasks and getting their results may get lost, depending on
the implementation.
The
AsyncResourceAPI 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.)
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes