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: add v8 fast api contribution guidelines #46199

Merged
merged 7 commits into from
Jan 24, 2023
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
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
150 changes: 150 additions & 0 deletions doc/contributing/adding-v8-fast-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# 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
anonrig marked this conversation as resolved.
Show resolved Hide resolved
provides an API to implement fast-path C functions which may be invoked directly
from JITted code. These functions also come with additional constraints,
for example, they may not trigger garbage collection.

## Limitations

* 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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
* 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.

Copy link
Member

Choose a reason for hiding this comment

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

Perhaps it's also better to suggest that since in principal, the fast API and the slow API should behave the same to avoid bugs, it's better not to throw errors in the slow API either and just update some flags and return to the JS land to throw?

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree in principal with @joyeecheung, but that is not a limitation of a V8 Fast API declaration, but an implementation recommendation. I think it should not be included in this documentation, but in a more style specific documentation like README.md?

* 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.
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved
anonrig marked this conversation as resolved.
Show resolved Hide resolved

## 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.
anonrig marked this conversation as resolved.
Show resolved Hide resolved
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
[binding functions documentation](../../src#binding-functions) for more
information.
anonrig marked this conversation as resolved.
Show resolved Hide resolved
* 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.
anonrig marked this conversation as resolved.
Show resolved Hide resolved
* 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.

anonrig marked this conversation as resolved.
Show resolved Hide resolved
## 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.
anonrig marked this conversation as resolved.
Show resolved Hide resolved

Passing a `true` value to `fallback` option will force V8 to run the slow path
with the same arguments.
anonrig marked this conversation as resolved.
Show resolved Hide resolved

In V8, the options fallback is defined as `FastApiCallbackOptions` inside
[`v8-fast-api-calls.h`](../../deps/v8/include/v8-fast-api-calls.h).
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved

* C++ land
Copy link
Member

Choose a reason for hiding this comment

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

Why is this a bullet point?

Copy link
Member Author

Choose a reason for hiding this comment

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

It aligns with other sections in the same file for mentioning the context of the example it's referring to. Do you have a recommendation for an alternative?


Example of a conditional fast path on C++

```cpp
// Anywhere in the execution flow, you can set fallback and stop the execution.
static double divide(const int32_t a,
const int32_t b,
v8::FastApiCallbackOptions& options) {
if (b == 0) {
options.fallback = true;
anonrig marked this conversation as resolved.
Show resolved Hide resolved
return 0;
} else {
return a / b;
}
}
```

## Example

A typical function that communicates between JavaScript and C++ is as follows.

* On the JavaScript side:

```js
const { divide } = internalBinding('custom_namespace');
```

* On the C++ side:

```cpp
#include "v8-fast-api-calls.h"

namespace node {
namespace custom_namespace {

static void SlowDivide(const FunctionCallbackInfo<Value>& args) {
Environment* env = Environment::GetCurrent(args);
CHECK_GE(args.Length(), 2);
CHECK(args[0]->IsInt32());
anonrig marked this conversation as resolved.
Show resolved Hide resolved
CHECK(args[1]->IsInt32());
auto a = args[0].As<v8::Int32>();
auto b = args[1].As<v8::Int32>();

if (b->Value() == 0) {
return node::THROW_ERR_INVALID_STATE(env, "Error");
anonrig marked this conversation as resolved.
Show resolved Hide resolved
}

double result = a->Value() / b->Value();
args.GetReturnValue().Set(v8::Number::New(env->isolate(), result));
}

static double FastDivide(const int32_t a,
const int32_t b,
v8::FastApiCallbackOptions& options) {
if (b == 0) {
options.fallback = true;
anonrig marked this conversation as resolved.
Show resolved Hide resolved
return 0;
} else {
return a / b;
}
}

CFunction fast_divide_(CFunction::Make(FastDivide));
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved

static void Initialize(Local<Object> target,
Local<Value> unused,
Local<Context> context,
void* priv) {
SetFastMethod(context, target, "divide", SlowDivide, &fast_divide_);
}

void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
registry->Register(SlowDivide);
registry->Register(FastDivide);
registry->Register(fast_divide_.GetTypeInfo());
}

} // namespace custom_namespace
} // namespace node

NODE_BINDING_CONTEXT_AWARE_INTERNAL(custom_namespace,
node::custom_namespace::Initialize);
NODE_BINDING_EXTERNAL_REFERENCE(
custom_namespace,
node::custom_namespace::RegisterExternalReferences);
```

* Update external references ([`node_external_reference.h`](../../src/node_external_reference.h))

Since our implementation used
`double(const int32_t a, const int32_t b, v8::FastApiCallbackOptions& options)`
signature, we need to add it to external references and in
`ALLOWED_EXTERNAL_REFERENCE_TYPES`.

Example declaration:

```cpp
using CFunctionCallbackReturningDouble = double (*)(const int32_t a,
const int32_t b,
v8::FastApiCallbackOptions& options);
```
anonrig marked this conversation as resolved.
Show resolved Hide resolved
4 changes: 4 additions & 0 deletions src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ 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.
anonrig marked this conversation as resolved.
Show resolved Hide resolved

## libuv API documentation

The other major dependency of Node.js is [libuv][], providing
Expand Down Expand Up @@ -1029,6 +1032,7 @@ 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
anonrig marked this conversation as resolved.
Show resolved Hide resolved
[`BaseObject`]: #baseobject
[`Context`]: #context
[`Environment`]: #environment
Expand Down