Gecko [ thecigaretteboxes.com ]

Name	Size	Permission
doc_img	[ DIR ]	drwxr-xr-x
maintaining	[ DIR ]	drwxr-xr-x
adding-new-napi-api.md	2.55 KB	-rw-r--r--
adding-v8-fast-api.md	5.06 KB	-rw-r--r--
api-documentation.md	15.36 KB	-rw-r--r--
backporting-to-release-lines.m...	5.72 KB	-rw-r--r--
building-node-with-ninja.md	1.72 KB	-rw-r--r--
code-of-conduct.md	2.12 KB	-rw-r--r--
collaborator-guide.md	43.49 KB	-rw-r--r--
commit-queue.md	5.76 KB	-rw-r--r--
components-in-core.md	2.51 KB	-rw-r--r--
cpp-style-guide.md	12.81 KB	-rw-r--r--
diagnostic-tooling-support-tie...	8 KB	-rw-r--r--
feature-request-management.md	3.41 KB	-rw-r--r--
internal-api.md	539 B	-rw-r--r--
investigating-native-memory-le...	30.58 KB	-rw-r--r--
issues.md	3.31 KB	-rw-r--r--
node-postmortem-support.md	2.53 KB	-rw-r--r--
offboarding.md	1.13 KB	-rw-r--r--
primordials.md	21.85 KB	-rw-r--r--
pull-requests.md	24.74 KB	-rw-r--r--
releases-node-api.md	6.63 KB	-rw-r--r--
releases.md	45.29 KB	-rw-r--r--
security-model-strategy.md	2.81 KB	-rw-r--r--
security-release-process.md	10.06 KB	-rw-r--r--
security-steward-on-off-boardi...	1.02 KB	-rw-r--r--
sharing-project-news.md	1.45 KB	-rw-r--r--
static-analysis.md	798 B	-rw-r--r--
strategic-initiatives.md	3.26 KB	-rw-r--r--
streaming-to-youtube.md	4.51 KB	-rw-r--r--
suggesting-social-media-posts....	257 B	-rw-r--r--
technical-priorities.md	6.02 KB	-rw-r--r--
technical-values.md	2.79 KB	-rw-r--r--
using-internal-errors.md	5.05 KB	-rw-r--r--
using-symbols.md	2.33 KB	-rw-r--r--
writing-and-running-benchmarks...	23.5 KB	-rw-r--r--
writing-tests.md	16.05 KB	-rw-r--r--

Code Editor : adding-v8-fast-api.md

# Adding V8 Fast API

Node.js uses [V8](https://v8.dev/) as its JavaScript engine.
Embedding functions implemented in C++ incur a high overhead, so V8
provides an API to implement native functions which may be invoked directly
from JIT-ed 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 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).

## Requirements

* Any function passed to `CFunction::Make`, including fast API function
  declarations, should have their signature registered in
  [`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 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.

## Fallback to slow path

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 `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
[`v8-fast-api-calls.h`](../../deps/v8/include/v8-fast-api-calls.h).

* C++ land

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;
      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());
    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");
    }

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;
      return 0;
    } else {
      return a / b;
    }
  }

CFunction fast_divide_(CFunction::Make(FastDivide));

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);
  ```

${this.title}

Code Editor : adding-v8-fast-api.md