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
143 changes: 143 additions & 0 deletions doc/contributing/adding-v8-fast-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# 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.
* 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

* Each unique fast API function signature should be defined inside the
anonrig marked this conversation as resolved.
Show resolved Hide resolved
[`external references`](../../src/node_external_reference.h) file.
* 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.
*
## Fallback to slow path

Fast API supports fallback to slow path in case logically it is wise to do so,
for example when providing a detailed error, or need to trigger JavaScript.
anonrig marked this conversation as resolved.
Show resolved Hide resolved
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
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 divide(const FunctionCallbackInfo<Value>& args) {
anonrig marked this conversation as resolved.
Show resolved Hide resolved
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(result);
anonrig marked this conversation as resolved.
Show resolved Hide resolved
}

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
} 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", Divide, &fast_divide_);
anonrig marked this conversation as resolved.
Show resolved Hide resolved
}

void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
registry->Register(Divide);
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