Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix n-api asynchronous threading documentation #19073

Closed
wants to merge 3 commits into from

Conversation

ebickle
Copy link
Contributor

@ebickle ebickle commented Mar 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.

Fixes: #19071

Checklist
Affected core subsystem(s)

doc

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
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. dont-land-on-v4.x node-api Issues and PRs related to the Node-API. labels Mar 1, 2018
doc/api/n-api.md Outdated
- `[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
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be completed and not comple?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good find, that was a typo in the original documentation. Fixed that as well.

Documentation for napi_create_async_work was missing part of the word "completed" in the parameter documentation
doc/api/n-api.md Outdated
@@ -3346,8 +3348,7 @@ callback invocation, even if it has been successfully cancelled.

## Custom Asynchronous Operations
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
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: async -> asynchronous?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed; expanded the abbreviations.

@Trott
Copy link
Member

Trott commented Mar 1, 2018

Text looks good to me in terms of style/grammar/etc. Pinging @nodejs/n-api to review for content.

doc/api/n-api.md Outdated
@@ -3269,9 +3269,11 @@ napi_status napi_create_async_work(napi_env env,
- `[in] async_resource_name`: Identifier for the kind of resource that is
being provided for diagnostic information exposed by the `async_hooks` API.
- `[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
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor

@digitalinfinity digitalinfinity left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one question- otherwise LGTM- thanks for the change!

Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM once @digitalinfinity's question is addressed.

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.
@ebickle
Copy link
Contributor Author

ebickle commented Mar 2, 2018

@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.

@mhdawson
Copy link
Member

mhdawson commented Mar 2, 2018

@ebickle we can squash as part of landing.

@BridgeAR
Copy link
Member

BridgeAR commented Mar 2, 2018

@BridgeAR BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Mar 2, 2018
@apapirovski
Copy link
Member

Landed in 449d1c8

@apapirovski apapirovski closed this Mar 4, 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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Mar 6, 2018
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Apr 16, 2018
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
@MylesBorins MylesBorins mentioned this pull request May 2, 2018
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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations. node-api Issues and PRs related to the Node-API.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

N-API documentation incorectly states napi_create_async_work is not multithreaded
8 participants