add docs; update tests

doc/env.md

@@ -130,3 +130,41 @@ 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`.
+
+### AddCleanupHook
+
+```cpp
+template <typename Hook>
+CleanupHook<Hook> AddCleanupHook(Hook hook);
+```
+
+- `[in] hook`: A function to call when the environment exists. Accepts a
+  function of the form `void ()`.
+
+Registers `hook` as a function to be run once the current Node.js environment
+exits. Unlike the underlying C-based Node-API, providing the same `hook`
+multiple times **is** allowed. The hooks will be called in reverse order, i.e.
+the most recently added one will be called first.
+
+Returns an `Env::CleanupHook` object, which can be used to remove the hook via
+its `Remove()` method.
+
+### AddCleanupHook
+
+```cpp
+template <typename Hook, typename Arg>
+CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
+```
+
+- `[in] hook`: A function to call when the environment exists. Accepts a
+  function of the form `void (Arg* arg)`.
+- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
+
+Registers `hook` as a function to be run with the `arg` parameter once the
+current Node.js environment exits. Unlike the underlying C-based Node-API,
+providing the same `hook` and `arg` pair multiple times **is** allowed. The
+hooks will be called in reverse order, i.e. the most recently added one will be
+called first.
+
+Returns an `Env::CleanupHook` object, which can be used to remove the hook via
+its `Remove()` method.

test/env_cleanup.cc

@@ -24,12 +24,16 @@ Value AddHooks(const CallbackInfo& info) {
 
   // hook: void (*)(void *arg), hint: int
   auto hook1 = env.AddCleanupHook(cleanup, &secret1);
+  // test using same hook+arg pair
+  auto hook1b = env.AddCleanupHook(cleanup, &secret1);
 
   // hook: void (*)(int *arg), hint: int
   auto hook2 = env.AddCleanupHook(cleanupInt, &secret2);
 
-  // hook: void (*)(int *arg), hint: void
+  // hook: void (*)(int *arg), hint: void (default)
   auto hook3 = env.AddCleanupHook(cleanupVoid);
+  // test using the same hook
+  auto hook3b = env.AddCleanupHook(cleanupVoid);
 
   // hook: lambda []void (int *arg)->void, hint: int
   auto hook4 = env.AddCleanupHook(
@@ -45,8 +49,10 @@ Value AddHooks(const CallbackInfo& info) {
 
   if (shouldRemove) {
     hook1.Remove(env);
+    hook1b.Remove(env);
     hook2.Remove(env);
     hook3.Remove(env);
+    hook3b.Remove(env);
     hook4.Remove(env);
     hook5.Remove(env);
     hook6.Remove(env);

test/env_cleanup.js

@@ -4,7 +4,7 @@ const assert = require('assert');
 
 if (process.argv[2] === 'runInChildProcess') {
     const binding_path = process.argv[3];
-    const remove_hooks = process.argv[4] === "true";
+    const remove_hooks = process.argv[4] === 'true';
 
     const binding = require(binding_path);
     binding.env_cleanup.addHooks(remove_hooks);
@@ -27,20 +27,27 @@ function test(bindingPath) {
         );
 
         const stdout = output[1].trim();
-        const lines = stdout.split(/[\r\n]+/).sort();
+        /**
+         * There is no need to sort the lines, as per Node-API documentation:
+         *  > The hooks will be called in reverse order, i.e. the most recently
+         *  > added one will be called first.
+        */
+        const lines = stdout.split(/[\r\n]+/);
 
         assert(status === 0, `Process aborted with status ${status}`);
 
         if (remove_hooks) {
             assert.deepStrictEqual(lines, [''], 'Child process had console output when none expected')
         } else {
             assert.deepStrictEqual(lines, [
-                "lambda cleanup()",
-                "lambda cleanup(42)",
-                "lambda cleanup(void)",
-                "static cleanup()",
-                "static cleanup(42)",
-                "static cleanup(43)",
+                'lambda cleanup()',
+                'lambda cleanup(void)',
+                'lambda cleanup(42)',
+                'static cleanup()',
+                'static cleanup()',
+                'static cleanup(43)',
+                'static cleanup(42)',
+                'static cleanup(42)'
             ],  'Child process console output mismisatch')
         }
     }