doc/contributing/adding-v8-fast-api.md - external/github.com/v8/node - Git at Google

 # Adding V8 Fast API callbacks

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

 Early iterations of the Fast API imposed significant constraints on these
 functions, such as not allowing re-entry into JavaScript execution and not
 throwing errors directly from fast calls. As of V8 12.6, these constraints no
 longer exist; however, a function whose execution cost is far higher than its
 calling cost is unlikely to benefit from having a "fast" variant, so some
 judgement is required when considering whether or not to add a Fast API
 callback.

 ## Basics

 A Fast API callback must correspond to a conventional ("slow") implementation
 of the same callback. Compare the two conventions:

 ```cpp
 // Conventional ("slow") implementation
 void IsEven(const v8::FunctionCallbackInfo<v8::Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   if (!args[0]->IsInt32()) {
     return THROW_ERR_INVALID_ARG_TYPE(env, "argument must be an integer");
   }

   int32_t n = args[0]->Int32Value(env->context()).FromJust();
   bool result = n % 2 == 0;
   args.GetReturnValue().Set(result);
 }

 // Fast implementation
 bool FastIsEven(v8::Local<v8::Value> receiver,
                 const int32_t n) {
   return n % 2 == 0;
 }
 static v8::CFunction fast_is_even(v8::CFunction::Make(FastIsEven));
 ```

 The main differences between the two call conventions are:

 * A conventional call passes its arguments as `v8::Value` objects, via a
   `v8::FunctionCallbackInfo` object. A Fast API call passes its arguments
   directly to the C++ function, as native C++ types where possible.
 * A conventional call passes its return value via a `v8::ReturnValue` object,
   accessible via the `v8::FunctionCallbackInfo` object. A Fast API call returns
   its value directly from the C++ function, as a native C++ type.
 * A conventional call can pass any number of arguments of any type, which must
   be validated within the implementation. A Fast API callback will only ever be
   called in compliance with its function signature, so the `FastIsEven` example
   above will only ever be called with a single argument of type `int32_t`. Any
   calls from JavaScript whose arguments do not correspond to a fast callback
   signature will be directed to the slow path by V8, even if the function is
   optimized.
 * The fast callback cannot be bound directly. It must first be used to build a
   `v8::CFunction` handle, which is passed alongside the conventional callback
   when binding the function.

 ## Argument and return types

 The following are valid argument types in Fast API callback signatures:

 * `bool`
 * `int32_t`
 * `uint32_t`
 * `int64_t`
 * `uint64_t`
 * `float`
 * `double`
 * `v8::Local<v8::Value>` (analogous to `any`)
 * `v8::FastOneByteString&` (analogous to `string`, but _only_ allows sequential
   one-byte strings, which is often not useful)

 <!--
 Deliberately omitted:
 * `void *` (external object pointers)
 * `v8::Local<v8::Object>` (this is actually treated the same as
                            v8::Local<v8::Value> by the API - in other words, V8
                            will pass _any_ JS value in an "object" handle,
                            whether it's an object or not, which is effectively
                            an unsafe cast and can lead to unexpected errors)
 -->

 The list of valid return types is similar:

 * `void`
 * `bool`
 * `int32_t`
 * `uint32_t`
 * `int64_t`
 * `uint64_t`
 * `float`
 * `double`

 <!-- * `void *` -->

 ### Prepending a `receiver` argument

 V8 will always pass the "receiver" (the `this` value of the JavaScript function
 call) in the first argument position. The arguments to the JavaScript function
 call are then passed from the second position onwards.

 ```cpp
 // Let's say that this function was bound as a method on some object,
 // such that it would be called in JavaScript as `object.hasProperty(foo)`.
 bool FastHasProperty(v8::Local<v8::Value> receiver,
                      v8::Local<v8::Value> property,
                      v8::FastApiCallbackOptions& options) {
   v8::Isolate* isolate = options.isolate;

   if (!receiver->IsObject()) {
     // invalid `this` value; throw some kind of error here
   }

   bool result;
   if (!receiver.As<v8::Object>()->Has(isolate->GetCurrentContext(),
                                       property).To(&result)) {
     // error pending in V8, value is ignored
     return false;
   }

   return result;
 }
 ```

 Even if your function binding does not need access to the receiver, you must
 still prepend it to your function arguments.

 ```cpp
 bool FastIsObject(v8::Local<v8::Value> receiver, // unused
                   v8::Local<v8::Value> value) {
   return value->IsObject();
 }
 ```

 ### Appending an `options` argument (optional)

 Fast callbacks may add an optional final function argument of type
 `v8::FastApiCallbackOptions&`. This is required if the callback interacts with
 the isolate in any way: see
 [Stack-allocated objects and garbage collection](#stack-allocated-objects-and-garbage-collection)
 and [Handling errors](#handling-errors).

 ```cpp
 void FastThrowExample(v8::Local<v8::Value> receiver,
                       const int32_t n,
                       v8::FastApiCallbackOptions& options) {
   if (IsEvilNumber(n)) {
     v8::HandleScope handle_scope(options.isolate);
     THROW_ERR_INVALID_ARG_VALUE(options.isolate, "Begone, foul spirit!");
   }
 }
 ```

 ## Registering a Fast API callback

 Compare registering a conventional API binding:

 ```cpp
 void Initialize(Local<Object> target,
                 Local<Value> unused,
                 Local<Context> context,
                 void* priv) {
   Environment* env = Environment::GetCurrent(context);
   SetMethodNoSideEffect(context, target, "isEven", IsEven);
 }
 ```

 with registering an API binding with a fast callback:

 ```cpp
 void Initialize(Local<Object> target,
                 Local<Value> unused,
                 Local<Context> context,
                 void* priv) {
   Environment* env = Environment::GetCurrent(context);
   SetFastMethodNoSideEffect(context,
                             target,
                             "isEven",
                             SlowIsEven,
                             &fast_is_even);
 }
 ```

 The Fast API equivalents of the method binding functions take an additional
 parameter, which specifies the fast callback(s).

 In the majority of cases, there will only be a single fast callback, and the
 additional parameter should be a pointer to the `v8::CFunction` object
 constructed by the call to `CFunction::Make`.

 In rare cases, there may be more than one fast callback, _eg._ if the function
 accepts optional arguments. In this case, the additional parameter should be a
 reference to an array of `v8::CFunction` objects, which is used to initialize a
 `v8::MemorySpan<v8::CFunction>`:

 ```cpp
 int32_t FastFuncWithoutArg(v8::Local<v8::Value> receiver) {
   return -1;
 }
 int32_t FastFuncWithArg(v8::Local<v8::Value> receiver,
                         const v8::FastOneByteString& s) {
   return s.length;
 }
 static CFunction fast_func_callbacks[] = {CFunction::Make(FastFuncWithoutArg),
                                           CFunction::Make(FastFuncWithArg)};

 void Initialize(Local<Object> target,
                 Local<Value> unused,
                 Local<Context> context,
                 void* priv) {
   Environment* env = Environment::GetCurrent(context);
   SetFastMethodNoSideEffect(context,
                             target,
                             "func",
                             SlowFunc,
                             fast_func_callbacks);
 }
 ```

 In addition, all method bindings should be registered with the external
 reference registry. This is done by passing both the conventional callback
 pointer and the `v8::CFunction` handle to `registry->Register`.

 ```cpp
 void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(SlowIsEven);
   registry->Register(fast_is_even);
 }
 ```

 Omitting this step can lead to fatal exceptions if the callback ends up in a
 snapshot (either the built-in snapshot, or a user-land one). Refer to the
 [binding functions documentation](../../src/README.md#registering-binding-functions-used-in-bootstrap)
 for more information.

 ## Type checking

 A callback argument that is a "primitive" C++ type (for example, `int32_t`)
 does not require type checks, as V8 will only ever invoke the fast callback if
 the argument in the JavaScript function call matches the corresponding argument
 type in the fast callback signature.

 Non-primitive arguments (such as TypedArrays) are passed to Fast API callbacks
 as `v8::Local<v8::Value>`. However, registering a fast callback with this
 argument type signals to the V8 engine that it can invoke the fast callback
 with _any value_ as that argument.

 If using arguments of type `v8::Local<v8::Value>`, then it is the
 implementation's responsibility to ensure that the arguments are validated
 before casting or otherwise consuming them. This can either take place within
 the C++ callbacks themselves, or within a JavaScript wrapper function that
 performs any necessary validation before calling the bound function.

 ## Stack-allocated objects and garbage collection

 The Fast API now allows access to the isolate, and allows allocation of
 `v8::Local` handles on the stack.

 A fast callback intending to make use of this functionality should accept a
 final argument of type `v8::FastApiCallbackOptions&`. V8 will pass the isolate
 pointer in `options.isolate`.

 If a fast callback creates any `v8::Local` handles within the fast callback,
 then it must first initialize a new `v8::HandleScope` to ensure that the
 handles are correctly scoped and garbage-collected.

 ```cpp
 bool FastIsIterable(v8::Local<v8::Value> receiver,
                     v8::Local<v8::Value> argument,
                     v8::FastApiCallbackOptions& options) {
   if (!argument->IsObject()) {
     return false;
   }

   // In order to create any Local handles, we first need a HandleScope
   v8::HandleScope HandleScope(options.isolate);

   v8::Local<v8::Object> object = argument.As<v8::Object>();
   v8::Local<v8::Value> value;
   if (!object->Get(options.isolate->GetCurrentContext(),
                    v8::Symbol::GetIterator(options.isolate)).ToLocal(&value)) {
     return false;
   }
   return value->IsFunction();
 }
 ```

 The same applies if the fast callback calls other functions which themselves
 create `v8::Local` handles, unless those functions create their own
 `v8::HandleScope`. In general, if the fast callback interacts with
 `v8::Local` handles within the body of the callback, it likely needs a handle
 scope.

 ## Debug tracking of Fast API callbacks

 In order to allow the test suite to track when a function call uses the Fast
 API path, add the `TRACK_V8_FAST_API_CALL` macro to your fast callback.

 ```cpp
 bool FastIsEven(v8::Local<v8::Value> receiver,
                 const int32_t n) {
   TRACK_V8_FAST_API_CALL("util.isEven");
   return n % 2 == 0;
 }
 ```

 The tracking key must be unique, and should be of the form:

 `<namespace> "." <function> [ "." <subpath> ]`

 The above example assumes that the fast callback is bound to the `isEven`
 method of the `util` module binding. To track specific subpaths within the
 callback, use a key with a subpath specifier, like `"util.isEven.error"`.

 These tracking events can be observed in debug mode, and are used to test that
 the fast path is being correctly invoked. See
 [Testing Fast API callbacks](#testing-fast-api-callbacks) for details.

 ## Handling errors

 It is now possible to throw errors from within fast API calls.

 Any fast callback that might potentially need to throw an error back to the
 JavaScript environment should accept a final `options` argument of type
 `v8::FastApiCallbackOptions&`. V8 will pass the isolate pointer in
 `options.isolate`.

 The callback should then throw a JavaScript error in the standard fashion. It
 also needs to return a dummy value, to satisfy the function signature.

 As above, initializing a `v8::HandleScope` is mandatory before any operations
 which create local handles.

 ```cpp
 static double FastDivide(v8::Local<v8::Value> receiver,
                          const int32_t a,
                          const int32_t b,
                          v8::FastApiCallbackOptions& options) {
   if (b == 0) {
     TRACK_V8_FAST_API_CALL("math.divide.error");
     v8::HandleScope handle_scope(options.isolate);
     THROW_ERR_INVALID_ARG_VALUE(options.isolate,
                                 "cannot divide by zero");
     return 0; // dummy value, ignored by V8
   }

   TRACK_V8_FAST_API_CALL("math.divide.ok");
   return a / b;
 }
 ```

 ## Testing Fast API callbacks

 To force V8 to use a Fast API path in testing, use V8 natives to force
 optimization of the JavaScript function that calls the fast target. If
 importing the binding directly, you will need to wrap the call within a
 JavaScript function first.

 ```js
 // Flags: --allow-natives-syntax --expose-internals --no-warnings

 const common = require('../common');
 const assert = require('node:assert');

 const { internalBinding } = require('internal/test/binding');
 const { isEven } = internalBinding('...');

 function testFastAPICall() {
   assert.strictEqual(isEven(0), true);
 }

 // The first V8 directive prepares the wrapper function for optimization.
 eval('%PrepareFunctionForOptimization(testFastAPICall)');
 // This call will use the slow path.
 testFastAPICall();

 // The second V8 directive will trigger optimization.
 eval('%OptimizeFunctionOnNextCall(testFastAPICall)');
 // This call will use the fast path.
 testFastAPICall();
 ```

 In debug builds, it is possible to observe
 [`TRACK_V8_FAST_API_CALL`](#debug-tracking-of-fast-api-callbacks) events using
 the`getV8FastApiCallCount` function, to verify that the fast path is being
 correctly invoked. All fast callbacks should be tested in this way.

 ```js
 function testFastAPICalls() {
   assert.strictEqual(isEven(1), false);
   assert.strictEqual(isEven(2), true);
 }

 eval('%PrepareFunctionForOptimization(testFastAPICalls)');
 testFastAPICalls();
 eval('%OptimizeFunctionOnNextCall(testFastAPICalls)');
 testFastAPICalls();

 if (common.isDebug) {
   const { getV8FastApiCallCount } = internalBinding('debug');
   assert.strictEqual(getV8FastApiCallCount('util.isEven'), 2);
 }
 ```

 ## 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 "node_debug.h"
   #include "v8-fast-api-calls.h"

   namespace node {
   namespace custom_namespace {

   using v8::FastApiCallbackOptions;
   using v8::FunctionCallbackInfo;
   using v8::HandleScope;
   using v8::Int32;
   using v8::Number;
   using v8::Value;

   static void SlowDivide(const FunctionCallbackInfo<Value>& args) {
     Environment* env = Environment::GetCurrent(args);
     if (!args[0]->IsInt32() || !args[1]->IsInt32()) {
       return THROW_ERR_INVALID_ARG_TYPE(env, "operands must be integers");
     }
     auto a = args[0].As<Int32>();
     auto b = args[1].As<Int32>();

     if (b->Value() == 0) {
       return THROW_ERR_INVALID_ARG_VALUE(env, "cannot divide by zero");
     }

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

   static double FastDivide(v8::Local<v8::Value> receiver,
                            const int32_t a,
                            const int32_t b,
                            FastApiCallbackOptions& options) {
     if (b == 0) {
       TRACK_V8_FAST_API_CALL("custom_namespace.divide.error");
       HandleScope handle_scope(options.isolate);
       THROW_ERR_INVALID_ARG_VALUE(options.isolate, "cannot divide by zero");
       return 0;
     }

     TRACK_V8_FAST_API_CALL("custom_namespace.divide.ok");
     return a / b;
   }

   static CFunction fast_divide(CFunction::Make(FastDivide));

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

   void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
     registry->Register(SlowDivide);
     registry->Register(fast_divide);
   }

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

 * In the unit tests:

   Since the Fast API callback uses `TRACK_V8_FAST_API_CALL`, we can ensure that
   the fast paths are taken and test them by writing tests that force
   V8 optimizations and check the counters.

 In the unit tests, since the fast API function uses `TRACK_V8_FAST_API_CALL`,
 we can ensure that the fast paths are taken and test them by writing tests that
 force V8 optimizations and check the counters.

 ```js
 // Flags: --expose-internals --no-warnings --allow-natives-syntax
 'use strict';
 const common = require('../common');

 const { internalBinding } = require('internal/test/binding');
 // We could also require a function that uses the internal binding internally.
 const { divide } = internalBinding('custom_namespace');

 // The function that will be optimized. It has to be a function written in
 // JavaScript. Since `divide` comes from the C++ side, we need to wrap it.
 function testFastPath(a, b) {
   return divide(a, b);
 }

 eval('%PrepareFunctionForOptimization(testFastPath)');
 // This call will let V8 know about the argument types that the function expects.
 assert.strictEqual(testFastPath(6, 3), 2);

 eval('%OptimizeFunctionOnNextCall(testFastPath)');
 assert.strictEqual(testFastPath(8, 2), 4);
 assert.throws(() => testFastPath(1, 0), {
   code: 'ERR_INVALID_STATE',
 });

 if (common.isDebug) {
   const { getV8FastApiCallCount } = internalBinding('debug');
   assert.strictEqual(getV8FastApiCallCount('custom_namespace.divide.ok'), 1);
   assert.strictEqual(getV8FastApiCallCount('custom_namespace.divide.error'), 1);
 }
 ```
	# Adding V8 Fast API callbacks

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

	Early iterations of the Fast API imposed significant constraints on these
	functions, such as not allowing re-entry into JavaScript execution and not
	throwing errors directly from fast calls. As of V8 12.6, these constraints no
	longer exist; however, a function whose execution cost is far higher than its
	calling cost is unlikely to benefit from having a "fast" variant, so some
	judgement is required when considering whether or not to add a Fast API
	callback.

	## Basics

	A Fast API callback must correspond to a conventional ("slow") implementation
	of the same callback. Compare the two conventions:

	```cpp
	// Conventional ("slow") implementation
	void IsEven(const v8::FunctionCallbackInfo<v8::Value>& args) {
	Environment* env = Environment::GetCurrent(args);
	if (!args[0]->IsInt32()) {
	return THROW_ERR_INVALID_ARG_TYPE(env, "argument must be an integer");
	}

	int32_t n = args[0]->Int32Value(env->context()).FromJust();
	bool result = n % 2 == 0;
	args.GetReturnValue().Set(result);
	}

	// Fast implementation
	bool FastIsEven(v8::Local<v8::Value> receiver,
	const int32_t n) {
	return n % 2 == 0;
	}
	static v8::CFunction fast_is_even(v8::CFunction::Make(FastIsEven));
	```

	The main differences between the two call conventions are:

	* A conventional call passes its arguments as `v8::Value` objects, via a
	`v8::FunctionCallbackInfo` object. A Fast API call passes its arguments
	directly to the C++ function, as native C++ types where possible.
	* A conventional call passes its return value via a `v8::ReturnValue` object,
	accessible via the `v8::FunctionCallbackInfo` object. A Fast API call returns
	its value directly from the C++ function, as a native C++ type.
	* A conventional call can pass any number of arguments of any type, which must
	be validated within the implementation. A Fast API callback will only ever be
	called in compliance with its function signature, so the `FastIsEven` example
	above will only ever be called with a single argument of type `int32_t`. Any
	calls from JavaScript whose arguments do not correspond to a fast callback
	signature will be directed to the slow path by V8, even if the function is
	optimized.
	* The fast callback cannot be bound directly. It must first be used to build a
	`v8::CFunction` handle, which is passed alongside the conventional callback
	when binding the function.

	## Argument and return types

	The following are valid argument types in Fast API callback signatures:

	* `bool`
	* `int32_t`
	* `uint32_t`
	* `int64_t`
	* `uint64_t`
	* `float`
	* `double`
	* `v8::Local<v8::Value>` (analogous to `any`)
	* `v8::FastOneByteString&` (analogous to `string`, but _only_ allows sequential
	one-byte strings, which is often not useful)

	<!--
	Deliberately omitted:
	* `void *` (external object pointers)
	* `v8::Local<v8::Object>` (this is actually treated the same as
	v8::Local<v8::Value> by the API - in other words, V8
	will pass _any_ JS value in an "object" handle,
	whether it's an object or not, which is effectively
	an unsafe cast and can lead to unexpected errors)
	-->

	The list of valid return types is similar:

	* `void`
	* `bool`
	* `int32_t`
	* `uint32_t`
	* `int64_t`
	* `uint64_t`
	* `float`
	* `double`

	<!-- * `void *` -->

	### Prepending a `receiver` argument

	V8 will always pass the "receiver" (the `this` value of the JavaScript function
	call) in the first argument position. The arguments to the JavaScript function
	call are then passed from the second position onwards.

	```cpp
	// Let's say that this function was bound as a method on some object,
	// such that it would be called in JavaScript as `object.hasProperty(foo)`.
	bool FastHasProperty(v8::Local<v8::Value> receiver,
	v8::Local<v8::Value> property,
	v8::FastApiCallbackOptions& options) {
	v8::Isolate* isolate = options.isolate;

	if (!receiver->IsObject()) {
	// invalid `this` value; throw some kind of error here
	}

	bool result;
	if (!receiver.As<v8::Object>()->Has(isolate->GetCurrentContext(),
	property).To(&result)) {
	// error pending in V8, value is ignored
	return false;
	}

	return result;
	}
	```

	Even if your function binding does not need access to the receiver, you must
	still prepend it to your function arguments.

	```cpp
	bool FastIsObject(v8::Local<v8::Value> receiver, // unused
	v8::Local<v8::Value> value) {
	return value->IsObject();
	}
	```

	### Appending an `options` argument (optional)

	Fast callbacks may add an optional final function argument of type
	`v8::FastApiCallbackOptions&`. This is required if the callback interacts with
	the isolate in any way: see
	[Stack-allocated objects and garbage collection](#stack-allocated-objects-and-garbage-collection)
	and [Handling errors](#handling-errors).

	```cpp
	void FastThrowExample(v8::Local<v8::Value> receiver,
	const int32_t n,
	v8::FastApiCallbackOptions& options) {
	if (IsEvilNumber(n)) {
	v8::HandleScope handle_scope(options.isolate);
	THROW_ERR_INVALID_ARG_VALUE(options.isolate, "Begone, foul spirit!");
	}
	}
	```

	## Registering a Fast API callback

	Compare registering a conventional API binding:

	```cpp
	void Initialize(Local<Object> target,
	Local<Value> unused,
	Local<Context> context,
	void* priv) {
	Environment* env = Environment::GetCurrent(context);
	SetMethodNoSideEffect(context, target, "isEven", IsEven);
	}
	```

	with registering an API binding with a fast callback:

	```cpp
	void Initialize(Local<Object> target,
	Local<Value> unused,
	Local<Context> context,
	void* priv) {
	Environment* env = Environment::GetCurrent(context);
	SetFastMethodNoSideEffect(context,
	target,
	"isEven",
	SlowIsEven,
	&fast_is_even);
	}
	```

	The Fast API equivalents of the method binding functions take an additional
	parameter, which specifies the fast callback(s).

	In the majority of cases, there will only be a single fast callback, and the
	additional parameter should be a pointer to the `v8::CFunction` object
	constructed by the call to `CFunction::Make`.

	In rare cases, there may be more than one fast callback, _eg._ if the function
	accepts optional arguments. In this case, the additional parameter should be a
	reference to an array of `v8::CFunction` objects, which is used to initialize a
	`v8::MemorySpan<v8::CFunction>`:

	```cpp
	int32_t FastFuncWithoutArg(v8::Local<v8::Value> receiver) {
	return -1;
	}
	int32_t FastFuncWithArg(v8::Local<v8::Value> receiver,
	const v8::FastOneByteString& s) {
	return s.length;
	}
	static CFunction fast_func_callbacks[] = {CFunction::Make(FastFuncWithoutArg),
	CFunction::Make(FastFuncWithArg)};

	void Initialize(Local<Object> target,
	Local<Value> unused,
	Local<Context> context,
	void* priv) {
	Environment* env = Environment::GetCurrent(context);
	SetFastMethodNoSideEffect(context,
	target,
	"func",
	SlowFunc,
	fast_func_callbacks);
	}
	```

	In addition, all method bindings should be registered with the external
	reference registry. This is done by passing both the conventional callback
	pointer and the `v8::CFunction` handle to `registry->Register`.

	```cpp
	void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
	registry->Register(SlowIsEven);
	registry->Register(fast_is_even);
	}
	```

	Omitting this step can lead to fatal exceptions if the callback ends up in a
	snapshot (either the built-in snapshot, or a user-land one). Refer to the
	[binding functions documentation](../../src/README.md#registering-binding-functions-used-in-bootstrap)
	for more information.

	## Type checking

	A callback argument that is a "primitive" C++ type (for example, `int32_t`)
	does not require type checks, as V8 will only ever invoke the fast callback if
	the argument in the JavaScript function call matches the corresponding argument
	type in the fast callback signature.

	Non-primitive arguments (such as TypedArrays) are passed to Fast API callbacks
	as `v8::Local<v8::Value>`. However, registering a fast callback with this
	argument type signals to the V8 engine that it can invoke the fast callback
	with _any value_ as that argument.

	If using arguments of type `v8::Local<v8::Value>`, then it is the
	implementation's responsibility to ensure that the arguments are validated
	before casting or otherwise consuming them. This can either take place within
	the C++ callbacks themselves, or within a JavaScript wrapper function that
	performs any necessary validation before calling the bound function.

	## Stack-allocated objects and garbage collection

	The Fast API now allows access to the isolate, and allows allocation of
	`v8::Local` handles on the stack.

	A fast callback intending to make use of this functionality should accept a
	final argument of type `v8::FastApiCallbackOptions&`. V8 will pass the isolate
	pointer in `options.isolate`.

	If a fast callback creates any `v8::Local` handles within the fast callback,
	then it must first initialize a new `v8::HandleScope` to ensure that the
	handles are correctly scoped and garbage-collected.

	```cpp
	bool FastIsIterable(v8::Local<v8::Value> receiver,
	v8::Local<v8::Value> argument,
	v8::FastApiCallbackOptions& options) {
	if (!argument->IsObject()) {
	return false;
	}

	// In order to create any Local handles, we first need a HandleScope
	v8::HandleScope HandleScope(options.isolate);

	v8::Local<v8::Object> object = argument.As<v8::Object>();
	v8::Local<v8::Value> value;
	if (!object->Get(options.isolate->GetCurrentContext(),
	v8::Symbol::GetIterator(options.isolate)).ToLocal(&value)) {
	return false;
	}
	return value->IsFunction();
	}
	```

	The same applies if the fast callback calls other functions which themselves
	create `v8::Local` handles, unless those functions create their own
	`v8::HandleScope`. In general, if the fast callback interacts with
	`v8::Local` handles within the body of the callback, it likely needs a handle
	scope.

	## Debug tracking of Fast API callbacks

	In order to allow the test suite to track when a function call uses the Fast
	API path, add the `TRACK_V8_FAST_API_CALL` macro to your fast callback.

	```cpp
	bool FastIsEven(v8::Local<v8::Value> receiver,
	const int32_t n) {
	TRACK_V8_FAST_API_CALL("util.isEven");
	return n % 2 == 0;
	}
	```

	The tracking key must be unique, and should be of the form:

	`<namespace> "." <function> [ "." <subpath> ]`

	The above example assumes that the fast callback is bound to the `isEven`
	method of the `util` module binding. To track specific subpaths within the
	callback, use a key with a subpath specifier, like `"util.isEven.error"`.

	These tracking events can be observed in debug mode, and are used to test that
	the fast path is being correctly invoked. See
	[Testing Fast API callbacks](#testing-fast-api-callbacks) for details.

	## Handling errors

	It is now possible to throw errors from within fast API calls.

	Any fast callback that might potentially need to throw an error back to the
	JavaScript environment should accept a final `options` argument of type
	`v8::FastApiCallbackOptions&`. V8 will pass the isolate pointer in
	`options.isolate`.

	The callback should then throw a JavaScript error in the standard fashion. It
	also needs to return a dummy value, to satisfy the function signature.

	As above, initializing a `v8::HandleScope` is mandatory before any operations
	which create local handles.

	```cpp
	static double FastDivide(v8::Local<v8::Value> receiver,
	const int32_t a,
	const int32_t b,
	v8::FastApiCallbackOptions& options) {
	if (b == 0) {
	TRACK_V8_FAST_API_CALL("math.divide.error");
	v8::HandleScope handle_scope(options.isolate);
	THROW_ERR_INVALID_ARG_VALUE(options.isolate,
	"cannot divide by zero");
	return 0; // dummy value, ignored by V8
	}

	TRACK_V8_FAST_API_CALL("math.divide.ok");
	return a / b;
	}
	```

	## Testing Fast API callbacks

	To force V8 to use a Fast API path in testing, use V8 natives to force
	optimization of the JavaScript function that calls the fast target. If
	importing the binding directly, you will need to wrap the call within a
	JavaScript function first.

	```js
	// Flags: --allow-natives-syntax --expose-internals --no-warnings

	const common = require('../common');
	const assert = require('node:assert');

	const { internalBinding } = require('internal/test/binding');
	const { isEven } = internalBinding('...');

	function testFastAPICall() {
	assert.strictEqual(isEven(0), true);
	}

	// The first V8 directive prepares the wrapper function for optimization.
	eval('%PrepareFunctionForOptimization(testFastAPICall)');
	// This call will use the slow path.
	testFastAPICall();

	// The second V8 directive will trigger optimization.
	eval('%OptimizeFunctionOnNextCall(testFastAPICall)');
	// This call will use the fast path.
	testFastAPICall();
	```

	In debug builds, it is possible to observe
	[`TRACK_V8_FAST_API_CALL`](#debug-tracking-of-fast-api-callbacks) events using
	the`getV8FastApiCallCount` function, to verify that the fast path is being
	correctly invoked. All fast callbacks should be tested in this way.

	```js
	function testFastAPICalls() {
	assert.strictEqual(isEven(1), false);
	assert.strictEqual(isEven(2), true);
	}

	eval('%PrepareFunctionForOptimization(testFastAPICalls)');
	testFastAPICalls();
	eval('%OptimizeFunctionOnNextCall(testFastAPICalls)');
	testFastAPICalls();

	if (common.isDebug) {
	const { getV8FastApiCallCount } = internalBinding('debug');
	assert.strictEqual(getV8FastApiCallCount('util.isEven'), 2);
	}
	```

	## 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 "node_debug.h"
	#include "v8-fast-api-calls.h"

	namespace node {
	namespace custom_namespace {

	using v8::FastApiCallbackOptions;
	using v8::FunctionCallbackInfo;
	using v8::HandleScope;
	using v8::Int32;
	using v8::Number;
	using v8::Value;

	static void SlowDivide(const FunctionCallbackInfo<Value>& args) {
	Environment* env = Environment::GetCurrent(args);
	if (!args[0]->IsInt32() \|\| !args[1]->IsInt32()) {
	return THROW_ERR_INVALID_ARG_TYPE(env, "operands must be integers");
	}
	auto a = args[0].As<Int32>();
	auto b = args[1].As<Int32>();

	if (b->Value() == 0) {
	return THROW_ERR_INVALID_ARG_VALUE(env, "cannot divide by zero");
	}

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

	static double FastDivide(v8::Local<v8::Value> receiver,
	const int32_t a,
	const int32_t b,
	FastApiCallbackOptions& options) {
	if (b == 0) {
	TRACK_V8_FAST_API_CALL("custom_namespace.divide.error");
	HandleScope handle_scope(options.isolate);
	THROW_ERR_INVALID_ARG_VALUE(options.isolate, "cannot divide by zero");
	return 0;
	}

	TRACK_V8_FAST_API_CALL("custom_namespace.divide.ok");
	return a / b;
	}

	static CFunction fast_divide(CFunction::Make(FastDivide));

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

	void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
	registry->Register(SlowDivide);
	registry->Register(fast_divide);
	}

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

	* In the unit tests:

	Since the Fast API callback uses `TRACK_V8_FAST_API_CALL`, we can ensure that
	the fast paths are taken and test them by writing tests that force
	V8 optimizations and check the counters.

	In the unit tests, since the fast API function uses `TRACK_V8_FAST_API_CALL`,
	we can ensure that the fast paths are taken and test them by writing tests that
	force V8 optimizations and check the counters.

	```js
	// Flags: --expose-internals --no-warnings --allow-natives-syntax
	'use strict';
	const common = require('../common');

	const { internalBinding } = require('internal/test/binding');
	// We could also require a function that uses the internal binding internally.
	const { divide } = internalBinding('custom_namespace');

	// The function that will be optimized. It has to be a function written in
	// JavaScript. Since `divide` comes from the C++ side, we need to wrap it.
	function testFastPath(a, b) {
	return divide(a, b);
	}

	eval('%PrepareFunctionForOptimization(testFastPath)');
	// This call will let V8 know about the argument types that the function expects.
	assert.strictEqual(testFastPath(6, 3), 2);

	eval('%OptimizeFunctionOnNextCall(testFastPath)');
	assert.strictEqual(testFastPath(8, 2), 4);
	assert.throws(() => testFastPath(1, 0), {
	code: 'ERR_INVALID_STATE',
	});

	if (common.isDebug) {
	const { getV8FastApiCallCount } = internalBinding('debug');
	assert.strictEqual(getV8FastApiCallCount('custom_namespace.divide.ok'), 1);
	assert.strictEqual(getV8FastApiCallCount('custom_namespace.divide.error'), 1);
	}
	```