Skip to content

doc: add v8 fast api contribution guidelines #46199

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

Merged
nodejs-github-bot merged 7 commits into from
Jan 24, 2023
Merged

doc: add v8 fast api contribution guidelines #46199

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f4c05cb
doc: add v8 fast api contribution guidelines
anonrig Jan 13, 2023
b79e5c8
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 16, 2023
20446b5
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 16, 2023
9acab7d
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 18, 2023
cb3f47a
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 18, 2023
269c8f2
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 18, 2023
a2e2d67
fixup! doc: add v8 fast api contribution guidelines
anonrig Jan 23, 2023
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
Prev Previous commit
fixup! doc: add v8 fast api contribution guidelines
  • Loading branch information
@anonrig
anonrig committed Jan 23, 2023
commit a2e2d67c7400bd803dcf5ed59b5c85ba6a898cce
30 changes: 15 additions & 15 deletions doc/contributing/adding-v8-fast-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Adding V8 Fast API

Node.js uses [V8](https://v8.dev/) as its JavaScript engine.
Embedder functions implemented in C++ incur a high overhead, so V8
provides an API to implement fast-path C functions which may be invoked directly
Embedding functions implemented in C++ incur a high overhead, so V8
provides an API to implement native functions which may be invoked directly
from JITted code. These functions also come with additional constraints,
for example, they may not trigger garbage collection.

Expand All @@ -11,36 +11,36 @@ for example, they may not trigger garbage collection.
* Fast API functions may not trigger garbage collection. This means by proxy
that JavaScript execution and heap allocation are also forbidden, including
`v8::Array::Get()` or `v8::Number::New()`.
* Throwing errors is not available on fast API, but can be done
through the fallback to slow API.
* Throwing errors is not available from within a fast API call, but can be done
through the fallback to the slow API.
* Not all parameter and return types are supported in fast API calls.
For a full list, please look into
[`v8-fast-api-calls.h`](../../deps/v8/include/v8-fast-api-calls.h) file.
[`v8-fast-api-calls.h`](../../deps/v8/include/v8-fast-api-calls.h).

## Requirements

* Any function passed to `CFunction::Make`, including fast API function
declarations, should have their signature registered in
[`external references`](../../src/node_external_reference.h) file.
Although, it would not start failing or crashing until the function end up
in a snapshot (either the built-in or a user-land one). Please refer to
[`node_external_reference.h`](../../src/node_external_reference.h) file.
Although, it would not start failing or crashing until the function ends up
in a snapshot (either the built-in or a user-land one). Please refer to the
[binding functions documentation](../../src#binding-functions) for more
information.
* To test fast APIs, make sure to run the tests in a loop with a decent
iterations count to trigger V8 for optimization and to prefer the fast API
over slow one.
iterations count to trigger relevant optimizations that prefer the fast API
over the slow one.
* The fast callback must be idempotent up to the point where error and fallback
conditions are checked, because otherwise executing the slow callback might
produce visible side effects twice.

Comment thread
anonrig marked this conversation as resolved.
Outdated
## Fallback to slow path

Fast API supports fallback to slow path in case logically it is wise to do so,
for example when a detailed error or JavaScript execution is needed.
Fallback mechanism can be enabled and changed from the C++ implementation of
the fast API function declaration.
Fast API supports fallback to slow path for when it is desirable to do so,
for example, when throwing a custom error or executing JavaScript code is
needed. The fallback mechanism can be enabled and changed from the C++
implementation of the fast API function declaration.

Passing a `true` value to `fallback` option will force V8 to run the slow path
Passing `true` to the `fallback` option will force V8 to run the slow path
with the same arguments.

In V8, the options fallback is defined as `FastApiCallbackOptions` inside
Expand Down
6 changes: 3 additions & 3 deletions src/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ embedder API.
Important concepts when using V8 are the ones of [`Isolate`][]s and
[JavaScript value handles][].

V8 supports fast-path C functions called [V8 Fast API][]
which is useful for improving the performance in certain cases.
V8 supports [fast API calls][], which can be useful for improving the
performance in certain cases.

## libuv API documentation

Expand Down Expand Up @@ -1032,7 +1032,6 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
[Callback scopes]: #callback-scopes
[JavaScript value handles]: #js-handles
[N-API]: https://nodejs.org/api/n-api.html
[V8 Fast API]: ../doc/contributing/adding-v8-fast-api.md
[`BaseObject`]: #baseobject
[`Context`]: #context
[`Environment`]: #environment
Expand All @@ -1059,6 +1058,7 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
[cleanup hooks]: #cleanup-hooks
[event loop]: #event-loop
[exception handling]: #exception-handling
[fast API calls]: ../doc/contributing/adding-v8-fast-api.md
[internal field]: #internal-fields
[introduction for V8 embedders]: https://v8.dev/docs/embed
[libuv]: https://libuv.org/
Expand Down