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.

Sign up for GitHub

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
Closed

doc: fix n-api asynchronous threading documentation #19073

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ab63ce5
doc: fix n-api asynchronous threading documentation
ebickle Mar 1, 2018
f59ea55
doc: fix typo in napi_create_async_work documentation
ebickle Mar 1, 2018
3493aa9
doc: remove async abbreviation and clarify threading behavior
ebickle Mar 2, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

- `[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.

from the main event loop thread.
- `[in] data`: User-provided data context. This will be passed back into the
execute and complete functions.
- `[out] result`: `napi_async_work*` which is the handle to the newly created
Expand Down Expand Up @@ -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.

necessary to ensure an async operation is properly tracked by the runtime.

### napi_async_init
Expand Down