doc: fix n-api asynchronous threading documentation - #19073
Closed
ebickle wants to merge 3 commits into
Closed
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Fixes: nodejs#19071
Comment thread
doc/api/n-api.md
Outdated
| thread and executes in parallel with the main event loop thread. | ||
| - `[in] complete`: The native function which will be called when the | ||
| asynchronous logic is comple or is cancelled. | ||
| asynchronous logic is comple or is cancelled. The given function is called |
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
should this be completed and not comple?
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
Author
There was a problem hiding this comment.
Good find, that was a typo in the original documentation. Fixed that as well.
Sorry, something went wrong.
Documentation for napi_create_async_work was missing part of the word "completed" in the parameter documentation
Trott
reviewed
Mar 1, 2018
Comment thread
doc/api/n-api.md
Outdated
| The simple asynchronous work APIs above may not be appropriate for every | ||
| scenario, because with those the async execution still happens on the main | ||
| event loop. When using any other async mechanism, the following APIs are | ||
| scenario. When using any other async mechanism, the following APIs are |
Copy link
Copy Markdown
Member
There was a problem hiding this comment.
Nit: async -> asynchronous?
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
Author
There was a problem hiding this comment.
Fixed; expanded the abbreviations.
Sorry, something went wrong.
Copy link
Copy Markdown
Member
|
Text looks good to me in terms of style/grammar/etc. Pinging @nodejs/n-api to review for content. |
Sorry, something went wrong.
Comment thread
doc/api/n-api.md
Outdated
| - `[in] execute`: The native function which should be called to excute | ||
| the logic asynchronously. | ||
| the logic asynchronously. The given function is called from a worker pool | ||
| thread and executes in parallel with the main event loop thread. |
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
@ebickle is it guaranteed to execute in parallel with the main event loop thread? Or is it more precise to say "can execute in parallel with the main event loop thread"? That is, is there a situation where the only thread available to do work in the thread pool is the main event loop thread?
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
Author
There was a problem hiding this comment.
@digitalinfinity agree completely with the suggestion. Regardless of whether or not the execute function can ever run in the main event loop thread, it's never guaranteed to be executed in parallel due to the OS' context switching. Updated the documentation.
Sorry, something went wrong.
digitalinfinity
approved these changes
Mar 1, 2018
digitalinfinity
left a comment
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Just one question- otherwise LGTM- thanks for the change!
Sorry, something went wrong.
mhdawson
approved these changes
Mar 1, 2018
mhdawson
left a comment
Copy link
Copy Markdown
Member
There was a problem hiding this comment.
LGTM once @digitalinfinity's question is addressed.
Sorry, something went wrong.
Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter.
Copy link
Copy Markdown
Contributor
Author
|
@digitalinfinity @mhdawson Improved the documentation based on the suggestions. I've posted it as a new commit, let me know if you'd like the commits to be manually squashed on my end. |
Sorry, something went wrong.
Copy link
Copy Markdown
Member
|
@ebickle we can squash as part of landing. |
Sorry, something went wrong.
jasnell
approved these changes
Mar 2, 2018
Copy link
Copy Markdown
Member
Sorry, something went wrong.
BridgeAR
approved these changes
Mar 2, 2018
apapirovski
pushed a commit
that referenced
this pull request
Mar 4, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. PR-URL: #19073 Fixes: #19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
addaleax
pushed a commit
to addaleax/node
that referenced
this pull request
Mar 5, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. PR-URL: nodejs#19073 Fixes: nodejs#19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Merged
gabrielschulhof
pushed a commit
to gabrielschulhof/node
that referenced
this pull request
Apr 12, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. PR-URL: nodejs#19073 Fixes: nodejs#19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
gabrielschulhof
pushed a commit
to gabrielschulhof/node
that referenced
this pull request
Apr 16, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. PR-URL: nodejs#19073 Fixes: nodejs#19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
MylesBorins
pushed a commit
that referenced
this pull request
Apr 16, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. Backport-PR-URL: #19447 PR-URL: #19073 Fixes: #19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Merged
MylesBorins
pushed a commit
that referenced
this pull request
May 1, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. Backport-PR-URL: #19265 PR-URL: #19073 Fixes: #19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Merged
MayaLekova
pushed a commit
to MayaLekova/node
that referenced
this pull request
May 8, 2018
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. PR-URL: nodejs#19073 Fixes: nodejs#19071 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Reviewers
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks.
Fixes: #19071
Checklist
Affected core subsystem(s)
doc