Skip to content

Commit 13118f7

Browse files
KevinEadyKevinEady
committed
finish docs
1 parent 6ee1ebf commit 13118f7

File tree

7 files changed

+281
-179
lines changed

7 files changed

+281
-179
lines changed

‎doc/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ The following is the documentation for node-addon-api.
3737
- [Full Class Hierarchy](hierarchy.md)
3838
- [Addon Structure](addon.md)
3939
- Data Types:
40+
- [BasicEnv](basic_env.md)
4041
- [Env](env.md)
4142
- [CallbackInfo](callbackinfo.md)
4243
- [Reference](reference.md)
@@ -70,6 +71,7 @@ The following is the documentation for node-addon-api.
7071
- [Object Lifetime Management](object_lifetime_management.md)
7172
- [HandleScope](handle_scope.md)
7273
- [EscapableHandleScope](escapable_handle_scope.md)
74+
- [Finalization](finalization.md)
7375
- [Memory Management](memory_management.md)
7476
- [Async Operations](async_operations.md)
7577
- [AsyncWorker](async_worker.md)

‎doc/array_buffer.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,13 @@ Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
3131
The `Napi::ArrayBuffer` instance does not assume ownership for the data and
3232
expects it to be valid for the lifetime of the instance. Since the
3333
`Napi::ArrayBuffer` is subject to garbage collection this overload is only
34-
suitable for data which is static and never needs to be freed.
35-
This factory method will not provide the caller with an opportunity to free the
36-
data when the `Napi::ArrayBuffer` gets garbage-collected. If you need to free
37-
the data retained by the `Napi::ArrayBuffer` object please use other
38-
variants of the `Napi::ArrayBuffer::New` factory method that accept
39-
`Napi::Finalizer`, which is a function that will be invoked when the
40-
`Napi::ArrayBuffer` object has been destroyed.
34+
suitable for data which is static and never needs to be freed. This factory
35+
method will not provide the caller with an opportunity to free the data when the
36+
`Napi::ArrayBuffer` gets garbage-collected. If you need to free the data
37+
retained by the `Napi::ArrayBuffer` object please use other variants of the
38+
`Napi::ArrayBuffer::New` factory method that accept `Napi::Finalizer`, which is
39+
a function that will be invoked when the `Napi::ArrayBuffer` object has been
40+
destroyed. See [Finalization]() for more details.
4141
4242
```cpp
4343
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength);
@@ -72,9 +72,9 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
7272
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
7373
- `[in] externalData`: The pointer to the external data to wrap.
7474
- `[in] byteLength`: The length of the `externalData`, in bytes.
75-
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
76-
destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
77-
`externalData` pointer), and return `void`.
75+
- `[in] finalizeCallback`: A function called when the engine destroys the
76+
`Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*)`.
77+
See [Finalization]() for more details.
7878
7979
Returns a new `Napi::ArrayBuffer` instance.
8080
@@ -102,11 +102,10 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
102102
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
103103
- `[in] externalData`: The pointer to the external data to wrap.
104104
- `[in] byteLength`: The length of the `externalData`, in bytes.
105-
- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
106-
destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
107-
`externalData` pointer) and `Hint*`, and return `void`.
108-
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
109-
finalize callback.
105+
- `[in] finalizeCallback`: A function called when the engine destroys the
106+
`Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*,
107+
Hint*)`. See [Finalization]() for more details.
108+
- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
110109

111110
Returns a new `Napi::ArrayBuffer` instance.
112111

@@ -163,3 +162,4 @@ Returns `true` if this `ArrayBuffer` has been detached.
163162

164163
[`Napi::Object`]: ./object.md
165164
[External Buffer]: ./external_buffer.md
165+
[Finalization]: ./finalization.md

‎doc/basic_env.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# BasicEnv
2+
3+
The opaque data structure containing the environment in which the request is
4+
being run.
5+
6+
The `Napi::BasicEnv` object is usually created and passed by the Node.js runtime
7+
or node-addon-api infrastructure.
8+
9+
The `Napi::BasicEnv` object represents an environment that has a limited subset
10+
of APIs when compared to `Napi::Env` and can be used in basic finalizers. See
11+
[Finalization]() for more details.
12+
13+
## Methods
14+
15+
### Constructor
16+
17+
```cpp
18+
Napi::BasicEnv::BasicEnv(node_api_nogc_env env);
19+
```
20+
21+
- `[in] env`: The `node_api_nogc_env` environment from which to construct the
22+
`Napi::BasicEnv` object.
23+
24+
### node_api_nogc_env
25+
26+
```cpp
27+
operator node_api_nogc_env() const;
28+
```
29+
30+
Returns the `node_api_nogc_env` opaque data structure representing the
31+
environment.
32+
33+
### GetInstanceData
34+
```cpp
35+
template <typename T> T* GetInstanceData() const;
36+
```
37+
38+
Returns the instance data that was previously associated with the environment,
39+
or `nullptr` if none was associated.
40+
41+
### SetInstanceData
42+
43+
44+
```cpp
45+
template <typename T> using Finalizer = void (*)(Env, T*);
46+
template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
47+
void SetInstanceData(T* data) const;
48+
```
49+
50+
- `[template] fini`: A function to call when the instance data is to be deleted.
51+
Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
52+
not given, the default finalizer will be used, which simply uses the `delete`
53+
operator to destroy `T*` when the addon instance is unloaded.
54+
- `[in] data`: A pointer to data that will be associated with the instance of
55+
the addon for the duration of its lifecycle.
56+
57+
Associates a data item stored at `T* data` with the current instance of the
58+
addon. The item will be passed to the function `fini` which gets called when an
59+
instance of the addon is unloaded.
60+
61+
### SetInstanceData
62+
63+
```cpp
64+
template <typename DataType, typename HintType>
65+
using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
66+
template <typename DataType,
67+
typename HintType,
68+
FinalizerWithHint<DataType, HintType> fini =
69+
Env::DefaultFiniWithHint<DataType, HintType>>
70+
void SetInstanceData(DataType* data, HintType* hint) const;
71+
```
72+
73+
- `[template] fini`: A function to call when the instance data is to be deleted.
74+
Accepts a function of the form `void CleanupData(Napi::Env env, DataType* data,
75+
HintType* hint)`. If not given, the default finalizer will be used, which simply
76+
uses the `delete` operator to destroy `T*` when the addon instance is unloaded.
77+
- `[in] data`: A pointer to data that will be associated with the instance of
78+
the addon for the duration of its lifecycle.
79+
- `[in] hint`: A pointer to data that will be associated with the instance of
80+
the addon for the duration of its lifecycle and will be passed as a hint to
81+
`fini` when the addon instance is unloaded.
82+
83+
Associates a data item stored at `T* data` with the current instance of the
84+
addon. The item will be passed to the function `fini` which gets called when an
85+
instance of the addon is unloaded. This overload accepts an additional hint to
86+
be passed to `fini`.
87+
88+
### GetModuleFileName
89+
90+
```cpp
91+
const char* Napi::Env::GetModuleFileName() const;
92+
```
93+
94+
Returns a A URL containing the absolute path of the location from which the
95+
add-on was loaded. For a file on the local file system it will start with
96+
`file://`. The string is null-terminated and owned by env and must thus not be
97+
modified or freed. It is only valid while the add-on is loaded.
98+
99+
### AddCleanupHook
100+
101+
```cpp
102+
template <typename Hook>
103+
CleanupHook<Hook> AddCleanupHook(Hook hook);
104+
```
105+
106+
- `[in] hook`: A function to call when the environment exits. Accepts a function
107+
of the form `void ()`.
108+
109+
Registers `hook` as a function to be run once the current Node.js environment
110+
exits. Unlike the underlying C-based Node-API, providing the same `hook`
111+
multiple times **is** allowed. The hooks will be called in reverse order, i.e.
112+
the most recently added one will be called first.
113+
114+
Returns an `Env::CleanupHook` object, which can be used to remove the hook via
115+
its `Remove()` method.
116+
117+
### PostFinalizer
118+
119+
```cpp
120+
template <typename Finalizer>
121+
inline void PostFinalizer(Finalizer finalizeCallback) const;
122+
```
123+
124+
- `[in] finalizeCallback`: The function to queue for execution outside of the GC
125+
finalization, implementing `operator()(Napi::Env)`. See [Finalization]() for
126+
more details.
127+
128+
### PostFinalizer
129+
130+
```cpp
131+
template <typename Finalizer, typename T>
132+
inline void PostFinalizer(Finalizer finalizeCallback, T* data) const;
133+
```
134+
135+
- `[in] finalizeCallback`: The function to queue for execution outside of the GC
136+
finalization, implementing `operator()(Napi::Env, T*)`. See [Finalization]()
137+
for more details.
138+
- `[in] data`: The data to associate with the object.
139+
140+
### PostFinalizer
141+
142+
```cpp
143+
template <typename Finalizer, typename T, typename Hint>
144+
inline void PostFinalizer(Finalizer finalizeCallback,
145+
T* data,
146+
Hint* finalizeHint) const;
147+
```
148+
149+
- `[in] finalizeCallback`: The function to queue for execution outside of the GC
150+
finalization, implementing `operator()(Napi::Env, T*, Hint*)`. See
151+
[Finalization]() for more details.
152+
- `[in] data`: The data to associate with the object.
153+
- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
154+
155+
### AddCleanupHook
156+
157+
```cpp
158+
template <typename Hook, typename Arg>
159+
CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
160+
```
161+
162+
- `[in] hook`: A function to call when the environment exits. Accepts a function
163+
of the form `void (Arg* arg)`.
164+
- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
165+
166+
Registers `hook` as a function to be run with the `arg` parameter once the
167+
current Node.js environment exits. Unlike the underlying C-based Node-API,
168+
providing the same `hook` and `arg` pair multiple times **is** allowed. The
169+
hooks will be called in reverse order, i.e. the most recently added one will be
170+
called first.
171+
172+
Returns an `Env::CleanupHook` object, which can be used to remove the hook via
173+
its `Remove()` method.
174+
175+
# Env::CleanupHook
176+
177+
The `Env::CleanupHook` object allows removal of the hook added via
178+
`Env::AddCleanupHook()`
179+
180+
## Methods
181+
182+
### IsEmpty
183+
184+
```cpp
185+
bool IsEmpty();
186+
```
187+
188+
Returns `true` if the cleanup hook was **not** successfully registered.
189+
190+
### Remove
191+
192+
```cpp
193+
bool Remove(Env env);
194+
```
195+
196+
Unregisters the hook from running once the current Node.js environment exits.
197+
198+
Returns `true` if the hook was successfully removed from the Node.js
199+
environment.
200+
201+
[Finalization]: ./finalization.md

‎doc/buffer.md‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,15 @@ Returns a new `Napi::Buffer` object.
2727
2828
Wraps the provided external data into a new `Napi::Buffer` object.
2929
30-
The `Napi::Buffer` object does not assume ownership for the data and expects it to be
31-
valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
32-
collection this overload is only suitable for data which is static and never
33-
needs to be freed.
34-
This factory method will not provide the caller with an opportunity to free the
35-
data when the `Napi::Buffer` gets garbage-collected. If you need to free the
36-
data retained by the `Napi::Buffer` object please use other variants of the
37-
`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
38-
function that will be invoked when the `Napi::Buffer` object has been
39-
destroyed.
30+
The `Napi::Buffer` object does not assume ownership for the data and expects it
31+
to be valid for the lifetime of the object. Since the `Napi::Buffer` is subject
32+
to garbage collection this overload is only suitable for data which is static
33+
and never needs to be freed. This factory method will not provide the caller
34+
with an opportunity to free the data when the `Napi::Buffer` gets
35+
garbage-collected. If you need to free the data retained by the `Napi::Buffer`
36+
object please use other variants of the `Napi::Buffer::New` factory method that
37+
accept `Finalizer`, which is a function that will be invoked when the
38+
`Napi::Buffer` object has been destroyed. See [Finalization]() for more details.
4039
4140
```cpp
4241
static Napi::Buffer<T> Napi::Buffer::New(napi_env env, T* data, size_t length);
@@ -70,9 +69,9 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
7069
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
7170
- `[in] data`: The pointer to the external data to expose.
7271
- `[in] length`: The number of `T` elements in the external data.
73-
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
74-
destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
75-
external data pointer), and return `void`.
72+
- `[in] finalizeCallback`: The function called when the engine destroys the
73+
`Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
74+
[Finalization]() for more details.
7675
7776
Returns a new `Napi::Buffer` object.
7877
@@ -99,11 +98,10 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
9998
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
10099
- `[in] data`: The pointer to the external data to expose.
101100
- `[in] length`: The number of `T` elements in the external data.
102-
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
103-
destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
104-
external data pointer) and `Hint*`, and return `void`.
105-
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
106-
finalize callback.
101+
- `[in] finalizeCallback`: The function called when the engine destroys the
102+
`Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
103+
See [Finalization]() for more details.
104+
- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
107105

108106
Returns a new `Napi::Buffer` object.
109107

@@ -157,9 +155,9 @@ static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
157155
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
158156
- `[in] data`: The pointer to the external data to expose.
159157
- `[in] length`: The number of `T` elements in the external data.
160-
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
161-
destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
162-
external data pointer), and return `void`.
158+
- `[in] finalizeCallback`: The function called when the engine destroys the
159+
`Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
160+
[Finalization]() for more details.
163161

164162
Returns a new `Napi::Buffer` object.
165163

@@ -186,11 +184,10 @@ static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
186184
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
187185
- `[in] data`: The pointer to the external data to expose.
188186
- `[in] length`: The number of `T` elements in the external data.
189-
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
190-
destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
191-
external data pointer) and `Hint*`, and return `void`.
192-
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
193-
finalize callback.
187+
- `[in] finalizeCallback`: The function called when the engine destroys the
188+
`Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
189+
See [Finalization]() for more details.
190+
- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
194191
195192
Returns a new `Napi::Buffer` object.
196193
@@ -245,3 +242,4 @@ Returns the number of `T` elements in the external data.
245242

246243
[`Napi::Uint8Array`]: ./typed_array_of.md
247244
[External Buffer]: ./external_buffer.md
245+
[Finalization]: ./finalization.md

0 commit comments

Comments
 (0)