package.doc.buffers.md Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of nan Show documentation

Native Abstractions for Node.js: C++ header for Node 0.8 -> 18 compatibility

There is a newer version: 2.19.0

## Buffers

NAN's `node::Buffer` helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility.

 - Nan::NewBuffer()
 - Nan::CopyBuffer()
 - Nan::FreeCallback()


### Nan::NewBuffer()

Allocate a new `node::Buffer` object with the specified size and optional data. Calls `node::Buffer::New()`.

Note that when creating a `Buffer` using `Nan::NewBuffer()` and an existing `char*`, it is assumed that the ownership of the pointer is being transferred to the new `Buffer` for management.
When a `node::Buffer` instance is garbage collected and a `FreeCallback` has not been specified, `data` will be disposed of via a call to `free()`.
You _must not_ free the memory space manually once you have created a `Buffer` in this way.

Signature:

```c++
Nan::MaybeLocal Nan::NewBuffer(uint32_t size)
Nan::MaybeLocal Nan::NewBuffer(char* data, uint32_t size)
Nan::MaybeLocal Nan::NewBuffer(char *data,
                                           size_t length,
                                           Nan::FreeCallback callback,
                                           void *hint)
```



### Nan::CopyBuffer()

Similar to [`Nan::NewBuffer()`](#api_nan_new_buffer) except that an implicit memcpy will occur within Node. Calls `node::Buffer::Copy()`.

Management of the `char*` is left to the user, you should manually free the memory space if necessary as the new `Buffer` will have its own copy.

Signature:

```c++
Nan::MaybeLocal Nan::CopyBuffer(const char *data, uint32_t size)
```



### Nan::FreeCallback()

A free callback that can be provided to [`Nan::NewBuffer()`](#api_nan_new_buffer).
The supplied callback will be invoked when the `Buffer` undergoes garbage collection.

Signature:

```c++
typedef void (*FreeCallback)(char *data, void *hint);
```