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 instance data APIs #708

Closed
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
doc: add instance data APIs
Signed-off-by: Gabriel Schulhof <[email protected]>
Re: #567 (comment)
Gabriel Schulhof committed May 1, 2020
commit e2e2b8450eb7e53981ec1ba1d42ef01ca3f88ba0
55 changes: 55 additions & 0 deletions doc/env.md
Original file line number Diff line number Diff line change
@@ -75,3 +75,58 @@ The `script` can be any of the following types:
- [`Napi::String`](string.md)
- `const char *`
- `const std::string &`

### GetInstanceData
```cpp
template <typename T> T* GetInstanceData();
```

Returns the instance data that was previously associated with the environment,
or `nullptr` if none was associated.

### SetInstanceData

```cpp
template <typename T> using Finalizer = void (*)(Env, T*);
template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
void SetInstanceData(T* data);
```

- `[template] fini`: A function to call when the instance data is to be deleted.
Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
not given, the default finalizer will be used, which simply uses the `delete`
operator to destroy `T*` when the addon instance is unloaded.
- `[in] data`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle.

Associates a data item stored at `T* data` with the current instance of the
addon. The item will be passed to the function `fini` which gets called when an
instance of the addon is unloaded.

### SetInstanceData

```cpp
template <typename DataType, typename HintType>
using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
template <typename DataType,
typename HintType,
FinalizerWithHint<DataType, HintType> fini =
Env::DefaultFiniWithHint<DataType, HintType>>
void SetInstanceData(DataType* data, HintType* hint);
```

- `[template] fini`: A function to call when the instance data is to be deleted.
Accepts a function of the form
`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
the default finalizer will be used, which simply uses the `delete` operator to
destroy `T*` when the addon instance is unloaded.
- `[in] data`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle.
- `[in] hint`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle and will be passed as a hint to
`fini` when the addon instance is unloaded.

Associates a data item stored at `T* data` with the current instance of the
addon. The item will be passed to the function `fini` which gets called when an
instance of the addon is unloaded. This overload accepts an additional hint to
be passed to `fini`.