fs: add .ref() and .unref() methods to the StatWatcher and FSWatcher

doc/api/fs.md

@@ -579,6 +579,29 @@ added: v0.5.8
 Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the
 `fs.FSWatcher` object is no longer usable.
 
+### `watcher.ref()`
+<!-- YAML
+added: REPLACEME
+-->
+
+When called, requests that the Node.js event loop *not* exit so long as the
+`FSWatcher` is active. Calling `watcher.ref()` multiple times will have
+no effect.
+
+By default, all `FSWatcher` objects are "ref'ed", making it normally
+unnecessary to call `watcher.ref()` unless `watcher.unref()` had been
+called previously.
+
+### `watcher.unref()`
+<!-- YAML
+added: REPLACEME
+-->
+When called, the active `FSWatcher` object will not require the Node.js
+event loop to remain active. If there is no other activity keeping the
+event loop running, the process may exit before the `FSWatcher` object's
+callback is invoked. Calling `watcher.unref()` multiple times will have
+no effect.
+
 ## Class: `fs.ReadStream`
 <!-- YAML
 added: v0.1.93

lib/fs.js

@@ -1489,6 +1489,9 @@ function watchFile(filename, options, listener) {
     stat[watchers.kFSStatWatcherStart](filename,
                                        options.persistent, options.interval);
     statWatchers.set(filename, stat);
+  } else {
+    stat[watchers.KFSStatWatcherRefCount]++;
+    stat[watchers.KFSStatWatcherMaxRefCount]++;
   }
 
   stat.addListener('change', listener);

lib/internal/fs/watchers.js

@@ -31,6 +31,8 @@ const kUseBigint = Symbol('kUseBigint');
 
 const kFSWatchStart = Symbol('kFSWatchStart');
 const kFSStatWatcherStart = Symbol('kFSStatWatcherStart');
+const KFSStatWatcherRefCount = Symbol('KFSStatWatcherRefCount');
+const KFSStatWatcherMaxRefCount = Symbol('KFSStatWatcherMaxRefCount');
 
 function emitStop(self) {
   self.emit('stop');
@@ -42,6 +44,8 @@ function StatWatcher(bigint) {
   this._handle = null;
   this[kOldStatus] = -1;
   this[kUseBigint] = bigint;
+  this[KFSStatWatcherRefCount] = 1;
+  this[KFSStatWatcherMaxRefCount] = 1;
 }
 ObjectSetPrototypeOf(StatWatcher.prototype, EventEmitter.prototype);
 ObjectSetPrototypeOf(StatWatcher, EventEmitter);
@@ -75,7 +79,7 @@ StatWatcher.prototype[kFSStatWatcherStart] = function(filename,
   this._handle[owner_symbol] = this;
   this._handle.onchange = onchange;
   if (!persistent)
-    this._handle.unref();
+    this.unref();
 
   // uv_fs_poll is a little more powerful than ev_stat but we curb it for
   // the sake of backwards compatibility.
@@ -117,6 +121,21 @@ StatWatcher.prototype.stop = function() {
   this._handle = null;
 };
 
+StatWatcher.prototype.ref = function() {
+  // Avoid refCount calling ref multiple times causing unref to have no effect.
+  if (this[KFSStatWatcherRefCount] === this[KFSStatWatcherMaxRefCount])
+    return;
+  if (this._handle && this[KFSStatWatcherRefCount]++ === 0)
+    this._handle.ref();
+};
+
+StatWatcher.prototype.unref = function() {
+  // Avoid refCount calling unref multiple times causing ref to have no effect.
+  if (this[KFSStatWatcherRefCount] === 0) return;
+  if (this._handle && --this[KFSStatWatcherRefCount] === 0)
+    this._handle.unref();
+};
+
 
 function FSWatcher() {
   EventEmitter.call(this);
@@ -208,6 +227,14 @@ FSWatcher.prototype.close = function() {
   process.nextTick(emitCloseNT, this);
 };
 
+FSWatcher.prototype.ref = function() {
+  if (this._handle) this._handle.ref();
+};
+
+FSWatcher.prototype.unref = function() {
+  if (this._handle) this._handle.unref();
+};
+
 function emitCloseNT(self) {
   self.emit('close');
 }
@@ -223,5 +250,7 @@ module.exports = {
   FSWatcher,
   StatWatcher,
   kFSWatchStart,
-  kFSStatWatcherStart
+  kFSStatWatcherStart,
+  KFSStatWatcherRefCount,
+  KFSStatWatcherMaxRefCount,
 };

src/fs_event_wrap.cc

@@ -101,9 +101,8 @@ void FSEventWrap::Initialize(Local<Object> target,
       FSEventWrap::kInternalFieldCount);
   t->SetClassName(fsevent_string);
 
-  t->Inherit(AsyncWrap::GetConstructorTemplate(env));
+  t->Inherit(HandleWrap::GetConstructorTemplate(env));
   env->SetProtoMethod(t, "start", Start);
-  env->SetProtoMethod(t, "close", Close);
 
   Local<FunctionTemplate> get_initialized_templ =
       FunctionTemplate::New(env->isolate(),

test/parallel/test-fs-watch-ref-unref.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const common = require('../common');
+
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
+const fs = require('fs');
+const assert = require('assert');
+
+let refCount = 0;
+
+const watcher = fs.watch(__filename, common.mustNotCall());
+
+function unref() {
+  watcher.unref();
+  refCount--;
+  assert.strictEqual(refCount, -1);
+}
+
+function ref() {
+  watcher.ref();
+  refCount++;
+  assert.strictEqual(refCount, 0);
+}
+
+unref();
+
+setTimeout(
+  common.mustCall(() => {
+    ref();
+    unref();
+  }),
+  common.platformTimeout(100)
+);

test/parallel/test-fs-watchfile-ref-unref.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const common = require('../common');
+
+const fs = require('fs');
+const assert = require('assert');
+
+let refCount = 0;
+
+const watcher = fs.watchFile(__filename, common.mustNotCall());
+
+function unref() {
+  watcher.unref();
+  refCount--;
+  assert.strictEqual(refCount, -1);
+}
+
+function ref() {
+  watcher.ref();
+  refCount++;
+  assert.strictEqual(refCount, 0);
+}
+
+unref();
+
+setTimeout(
+  common.mustCall(() => {
+    ref();
+    unref();
+    watcher.unref();
+    watcher.ref();
+    watcher.ref();
+    watcher.unref();
+  }),
+  common.platformTimeout(100)
+);