koffi 1.1.0-beta.1 → 1.1.0-beta.4

package/vendor/node-addon-api/doc/object_lifetime_management.md

@@ -0,0 +1,83 @@
+# Object lifetime management
+
+A handle may be created when any new node-addon-api Value and
+its subclasses is created or returned.
+
+As the methods and classes within the node-addon-api are used,
+handles to objects in the heap for the underlying
+VM may be created. A handle may be created when any new
+node-addon-api Value or one of its subclasses is created or returned.
+These handles must hold the objects 'live' until they are no
+longer required by the native code, otherwise the objects could be
+collected by the garbage collector before the native code was
+finished using them.
+
+As handles are created they are associated with a
+'scope'. The lifespan for the default scope is tied to the lifespan
+of the native method call. The result is that, by default, handles
+remain valid and the objects associated with these handles will be
+held live for the lifespan of the native method call.
+
+In many cases, however, it is necessary that the handles remain valid for
+either a shorter or longer lifespan than that of the native method.
+The sections which follow describe the node-addon-api classes and
+methods that than can be used to change the handle lifespan from
+the default.
+
+## Making handle lifespan shorter than that of the native method
+
+It is often necessary to make the lifespan of handles shorter than
+the lifespan of a native method. For example, consider a native method
+that has a loop which creates a number of values and does something
+with each of the values, one at a time:
+
+```C++
+for (int i = 0; i < LOOP_MAX; i++) {
+  std::string name = std::string("inner-scope") + std::to_string(i);
+  Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
+  // do something with newValue
+};
+```
+
+This would result in a large number of handles being created, consuming
+substantial resources. In addition, even though the native code could only
+use the most recently created value, all of the previously created
+values would also be kept alive since they all share the same scope.
+
+To handle this case, node-addon-api provides the ability to establish
+a new 'scope' to which newly created handles will be associated. Once those
+handles are no longer required, the scope can be deleted and any handles
+associated with the scope are invalidated. The `Napi::HandleScope`
+and `Napi::EscapableHandleScope` classes are provided by node-addon-api for
+creating additional scopes.
+
+node-addon-api only supports a single nested hierarchy of scopes. There is
+only one active scope at any time, and all new handles will be associated
+with that scope while it is active. Scopes must be deleted in the reverse
+order from which they are opened. In addition, all scopes created within
+a native method must be deleted before returning from that method. Since
+`Napi::HandleScopes` are typically stack allocated the compiler will take care of
+deletion, however, care must be taken to create the scope in the right
+place such that you achieve the desired lifetime.
+
+Taking the earlier example, creating a `Napi::HandleScope` in the inner loop
+would ensure that at most a single new value is held alive throughout the
+execution of the loop:
+
+```C
+for (int i = 0; i < LOOP_MAX; i++) {
+  Napi::HandleScope scope(info.Env());
+  std::string name = std::string("inner-scope") + std::to_string(i);
+  Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
+  // do something with newValue
+};
+```
+
+When nesting scopes, there are cases where a handle from an
+inner scope needs to live beyond the lifespan of that scope. node-addon-api
+provides the `Napi::EscapableHandleScope` with the `Escape` method
+in order to support this case. An escapable scope
+allows one object to be 'promoted' so that it 'escapes' the
+current scope and the lifespan of the handle changes from the current
+scope to that of the outer scope. The `Escape` method can only be called
+once for a given `Napi::EscapableHandleScope`.

package/vendor/node-addon-api/doc/object_reference.md

@@ -0,0 +1,117 @@
+# Object Reference
+
+`Napi::ObjectReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference<Object>`. This means that a `Napi::ObjectReference` holds a [`Napi::Object`](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference.
+
+For more general information on references, please consult [`Napi::Reference`](reference.md).
+
+## Example
+```cpp
+#include <napi.h>
+
+using namespace Napi;
+
+void Init(Env env) {
+
+    // Create an empty ObjectReference that has an initial reference count of 2.
+    ObjectReference obj_ref = Reference<Object>::New(Object::New(env), 2);
+
+    // Set a couple of different properties on the reference.
+    obj_ref.Set("hello", String::New(env, "world"));
+    obj_ref.Set(42, "The Answer to Life, the Universe, and Everything");
+
+    // Get the properties using the keys.
+    Value val1 = obj_ref.Get("hello");
+    Value val2 = obj_ref.Get(42);
+}
+```
+
+## Methods
+
+### Initialization
+
+```cpp
+static Napi::ObjectReference Napi::ObjectReference::New(const Napi::Object& value, uint32_t initialRefcount = 0);
+```
+
+* `[in] value`: The `Napi::Object` which is to be referenced.
+
+* `[in] initialRefcount`: The initial reference count.
+
+Returns the newly created reference.
+
+```cpp
+static Napi::ObjectReference Napi::Weak(const Napi::Object& value);
+```
+
+Creates a "weak" reference to the value, in that the initial count of number of references is set to 0.
+
+* `[in] value`: The value which is to be referenced.
+
+Returns the newly created reference.
+
+```cpp
+static Napi::ObjectReference Napi::Persistent(const Napi::Object& value);
+```
+
+Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1.
+
+* `[in] value`: The value which is to be referenced.
+
+Returns the newly created reference.
+
+### Empty Constructor
+
+```cpp
+Napi::ObjectReference::ObjectReference();
+```
+
+Returns a new _empty_ `Napi::ObjectReference` instance.
+
+### Constructor
+
+```cpp
+Napi::ObjectReference::ObjectReference(napi_env env, napi_value value);
+```
+
+* `[in] env`: The `napi_env` environment in which to construct the `Napi::ObjectReference` object.
+
+* `[in] value`: The Node-API primitive value to be held by the `Napi::ObjectReference`.
+
+Returns the newly created reference.
+
+### Set
+```cpp
+bool Napi::ObjectReference::Set(___ key, ___ value);
+```
+
+* `[in] key`: The name for the property being assigned.
+
+* `[in] value`: The value being assigned to the property.
+
+The `key` can be any of the following types:
+- `const char*`
+- `const std::string`
+- `uint32_t`
+
+The `value` can be any of the following types:
+- `napi_value`
+- `Napi::Value`
+- `const char*`
+- `bool`
+- `double`
+
+### Get
+
+```cpp
+Napi::Value Napi::ObjectReference::Get(___ key) const;
+```
+
+* `[in] key`: The name of the property to return the value for.
+
+Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists.
+
+The `key` can be any of the following types:
+- `const char*`
+- `const std::string`
+- `uint32_t`
+