From 757eb1f5a368d7f52af6faf279b3075d37cf337f Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 19 Jun 2018 01:44:11 +0200 Subject: [PATCH] doc: add function and function reference doc PR-URL: https://github.com/nodejs/node-addon-api/pull/299 Reviewed-By: Michael Dawson --- doc/function.md | 283 +++++++++++++++++++++++++++++++++++++- doc/function_reference.md | 195 +++++++++++++++++++++++++- 2 files changed, 471 insertions(+), 7 deletions(-) diff --git a/doc/function.md b/doc/function.md index e4d7c92fc..ca85ef05a 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,5 +1,282 @@ # Function -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +The `Napi::Function` class provides a set of methods for creating a function object in +native code that can later be called from JavaScript. The created function is not +automatically visible from JavaScript. Instead it needs to be part of the add-on's +module exports or be returned by one of the module's exported functions. + +In addition the `Function` class also provides methods that can be used to call +functions that were created in JavaScript and passed to the native add-on. + +The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info +see: [`Napi::Object`](object.md)). + +## Example + +```cpp +#include + +using namespace Napi; + +Value Fn(const CallbackInfo& info) { + Env env = info.Env(); + // ... + return String::New(env, "Hello World"); +} + +Object Init(Env env, Object exports) { + exports.Set(String::New(env, "fn"), Function::New(env, Fn)); +} + +NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) +``` + +The above code can be used from JavaScript as follows: + +```js +const addon = require('./addon'); +addon.fn(); +``` + +With the `Napi::Function` class it is possible to call a JavaScript function object +from a native add-on with two different methods: `Call` and `MakeCallback`. +The API of these two methods is very similar, but they are used in different +contexts. The `MakeCallback` method is used to call from native code back into +JavaScript after returning from an [asynchronous operation](async_operations.md) +and in general in situations which don't have an existing JavaScript function on +the stack. The `Call` method is used when there is already a JavaScript function +on the stack (for example when running a native method called from JavaScript). + +## Methods + +### Constructor + +Creates a new empty instance of `Napi::Function`. + +```cpp +Function(); +``` + +### Constructor + +Creates a new instance of the `Napi::Function` object. + +```cpp +Function(napi_env env, napi_value value); +``` + +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. +- `[in] value`: The `napi_value` which is a handle for a JavaScript function. + +Returns a non-empty `Napi::Function` instance. + +### New + +Creates an instance of a `Napi::Function` object. + +```cpp +template +static Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); +``` + +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. +- `[in] cb`: Object that implements `Callable`. +- `[in] utf8name`: Null-terminated string to be used as the name of the function. +- `[in] data`: User-provided data context. This will be passed back into the +function when invoked later. + +Returns an instance of a `Napi::Function` object. + +### New + +```cpp +template +static Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); +``` + +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. +- `[in] cb`: Object that implements `Callable`. +- `[in] utf8name`: String to be used as the name of the function. +- `[in] data`: User-provided data context. This will be passed back into the +function when invoked later. + +Returns an instance of a `Napi::Function` object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Napi::Object New(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the contructor function. + +Returns a new JavaScript object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Napi::Object New(const std::vector& args) const; +``` + +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the constructor function. + +Returns a new JavaScript object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Napi::Object New(size_t argc, const napi_value* args) const; +``` + +- `[in] argc`: The number of the arguments passed to the contructor function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the constructor function. + +Returns a new JavaScript object. + +### Call + +Calls a Javascript function from a native add-on. + +```cpp +Napi::Value Call(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### Call + +Calls a JavaScript function from a native add-on. + +```cpp +Napi::Value Call(const std::vector& args) const; +``` + +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### Call + +Calls a Javascript function from a native add-on. + +```cpp +Napi::Value Call(size_t argc, const napi_value* args) const; +``` + +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### Call + +Calls a Javascript function from a native add-on. + +```cpp +Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### Call + +Calls a Javascript function from a native add-on. + +```cpp +Napi::Value Call(napi_value recv, const std::vector& args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### Call + +Calls a Javascript function from a native add-on. + +```cpp +Napi::Value Call(napi_value recv, size_t argc, const napi_value* args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### MakeCallback + +Calls a Javascript function from a native add-on after an asynchronous operation. + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### MakeCallback + +Calls a Javascript function from a native add-on after an asynchronous operation. + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: List of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +### MakeCallback + +Calls a Javascript function from a native add-on after an asynchronous operation. + +```cpp +Napi::Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; +``` + +- `[in] recv`: The `this` object passed to the called function. +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. + +## Operator + +```cpp +Napi::Value operator ()(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value`. + +Returns a `Napi::Value` representing the JavaScript value returned by the function. diff --git a/doc/function_reference.md b/doc/function_reference.md index 1978b81b4..e555f8b04 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,5 +1,192 @@ -# Function reference +# FunctionReference -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +`Napi::FunctionReference` is a subclass of [`Napi::Reference`](reference.md), and +is equivalent to an instance of `Napi::Reference`. This means +that a `Napi::FunctionReference` holds a [`Napi::Function`](function.md), and a +count of the number of references to that `Napi::Function`. When the count is +greater than 0, a `Napi::FunctionReference` is not eligible for garbage collection. +This ensures that the `Function` will remain accessible, even if the original +reference to it is no longer available. +`Napi::FunctionReference` allows the referenced JavaScript function object to be +called from a native add-on with two different methods: `Call` and `MakeCallback`. +See the documentation for [`Napi::Function`](function.md) for when `Call` should +be used instead of `MakeCallback` and vice-versa. + +The `Napi::FunctionReference` class inherits its behavior from the `Napi::Reference` +class (for more info see: [`Napi::Reference`](reference.md)). + +## Methods + +### Weak + +Creates a "weak" reference to the value, in that the initial reference count is +set to 0. + +```cpp +static FunctionReference Weak(const Function& value); +``` + +- `[in] value`: The value which is to be referenced. + +Returns the newly created reference. + +### Persistent + +Creates a "persistent" reference to the value, in that the initial reference +count is set to 1. + +```cpp +static FunctionReference Persistent(const Function& value); +``` + +- `[in] value`: The value which is to be referenced. + +Returns the newly created reference. + +### Constructor + +Creates a new empty instance of `Napi::FunctionReference`. + +```cpp +FunctionReference(); +``` + +### Constructor + +Creates a new instance of the `Napi::FunctionReference`. + +```cpp +FunctionReference(napi_env env, napi_ref ref); +``` + +- `[in] env`: The environment in which to construct the `Napi::FunctionReference` object. +- `[in] ref`: The N-API reference to be held by the `Napi::FunctionReference`. + +Returns a newly created `Napi::FunctionReference` object. + +### New + +Constructs a new instance by calling the constructor held by this reference. + +```cpp +Napi::Object New(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the contructor function. + +Returns a new JavaScript object. + +### New + +Constructs a new instance by calling the constructor held by this reference. + +```cpp +Napi::Object New(const std::vector& args) const; +``` + +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the constructor function. + +Returns a new JavaScript object. + +### Call + +Calls a referenced Javascript function from a native add-on. + +```cpp +Napi::Value Call(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +### Call + +Calls a referenced Javascript function from a native add-on. + +```cpp +Napi::Value Call(const std::vector& args) const; +``` + +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +### Call + +Calls a referenced Javascript function from a native add-on. + +```cpp +Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +### Call + +Calls a referenced Javascript function from a native add-on. + +```cpp +Napi::Value Call(napi_value recv, const std::vector& args) const; +``` + +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +### MakeCallback + +Calls a referenced Javascript function from a native add-on after an asynchronous +operation. + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +### MakeCallback + +Calls a referenced Javascript function from a native add-on after an asynchronous +operation. + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +``` + +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. + +Returns a `Napi::Value` representing the JavaScript object returned by the referenced +function. + +## Operator + +```cpp +Napi::Value operator ()(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of reference to JavaScript values as `napi_value` + +Returns a `Napi::Value` representing the JavaScript value returned by the referenced +function.