From bb8580f66c4416d24b546b12f6f6eeb786231b5a Mon Sep 17 00:00:00 2001
From: rickyes <mail@zhoumq.cn>
Date: Wed, 29 Apr 2020 02:00:35 +0800
Subject: [PATCH 1/3] fs: add .ref() and .unref() methods to the StatWatcher
 and FSWatcher classes

---
 doc/api/fs.md                                | 23 +++++++++++++
 lib/fs.js                                    |  3 ++
 lib/internal/fs/watchers.js                  | 33 ++++++++++++++++--
 src/fs_event_wrap.cc                         |  3 +-
 test/parallel/test-fs-watch-ref-unref.js     | 35 +++++++++++++++++++
 test/parallel/test-fs-watchfile-ref-unref.js | 36 ++++++++++++++++++++
 6 files changed, 129 insertions(+), 4 deletions(-)
 create mode 100644 test/parallel/test-fs-watch-ref-unref.js
 create mode 100644 test/parallel/test-fs-watchfile-ref-unref.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index ec8e49d5b12adc..733ff6b4bc19e9 100644
--- a/doc/api/fs.md
+++ b/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
diff --git a/lib/fs.js b/lib/fs.js
index b0581927514888..28337bc5191836 100644
--- a/lib/fs.js
+++ b/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);
diff --git a/lib/internal/fs/watchers.js b/lib/internal/fs/watchers.js
index 118f85d9ada181..3769e789b46a66 100644
--- a/lib/internal/fs/watchers.js
+++ b/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,
 };
diff --git a/src/fs_event_wrap.cc b/src/fs_event_wrap.cc
index b4b110cc2c839c..91c3a267b33937 100644
--- a/src/fs_event_wrap.cc
+++ b/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(),
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
new file mode 100644
index 00000000000000..77993e254a74fe
--- /dev/null
+++ b/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)
+);
diff --git a/test/parallel/test-fs-watchfile-ref-unref.js b/test/parallel/test-fs-watchfile-ref-unref.js
new file mode 100644
index 00000000000000..0c6d61a00bec9a
--- /dev/null
+++ b/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)
+);

From 5cb73d42d3ee71afd2483d10051370e05610ca19 Mon Sep 17 00:00:00 2001
From: rickyes <mail@zhoumq.cn>
Date: Wed, 29 Apr 2020 15:34:20 +0800
Subject: [PATCH 2/3] fs: Add unwatchFile to handle reference counting

---
 doc/api/fs.md                                | 36 ++++++++++++++++++
 lib/fs.js                                    |  7 +++-
 lib/internal/fs/watchers.js                  | 30 +++++++++++++--
 test/parallel/test-fs-watch-ref-unref.js     | 21 ++---------
 test/parallel/test-fs-watchfile-ref-unref.js | 39 ++++++++++----------
 tools/doc/type-parser.js                     |  1 +
 6 files changed, 90 insertions(+), 44 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 733ff6b4bc19e9..ef9db8807dfcab 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -596,12 +596,47 @@ called previously.
 <!-- 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.StatWatcher`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Extends {EventEmitter}
+
+A successful call to `fs.watchFile()` method will return a new `fs.StatWatcher`
+object.
+
+### `watcher.ref()`
+<!-- YAML
+added: REPLACEME
+-->
+
+When called, requests that the Node.js event loop *not* exit so long as the
+`StatWatcher` is active. Calling `watcher.ref()` multiple times will have
+no effect.
+
+By default, all `StatWatcher` 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 `StatWatcher` 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 `StatWatcher` object's
+callback is invoked. Calling `watcher.unref()` multiple times will have
+no effect.
+
 ## Class: `fs.ReadStream`
 <!-- YAML
 added: v0.1.93
@@ -3981,6 +4016,7 @@ changes:
 * `listener` {Function}
   * `current` {fs.Stats}
   * `previous` {fs.Stats}
+* Returns: {fs.StatWatcher}
 
 Watch for changes on `filename`. The callback `listener` will be called each
 time the file is accessed.
diff --git a/lib/fs.js b/lib/fs.js
index 28337bc5191836..d08b74db62077d 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -1490,8 +1490,7 @@ function watchFile(filename, options, listener) {
                                        options.persistent, options.interval);
     statWatchers.set(filename, stat);
   } else {
-    stat[watchers.KFSStatWatcherRefCount]++;
-    stat[watchers.KFSStatWatcherMaxRefCount]++;
+    stat[watchers.kFSStatWatcherAddOrCleanRef]('add');
   }
 
   stat.addListener('change', listener);
@@ -1506,9 +1505,13 @@ function unwatchFile(filename, listener) {
   if (stat === undefined) return;
 
   if (typeof listener === 'function') {
+    const beforeListenerCount = stat.listenerCount('change');
     stat.removeListener('change', listener);
+    if (stat.listenerCount('change') < beforeListenerCount)
+      stat[watchers.kFSStatWatcherAddOrCleanRef]('clean');
   } else {
     stat.removeAllListeners('change');
+    stat[watchers.kFSStatWatcherAddOrCleanRef]('cleanAll');
   }
 
   if (stat.listenerCount('change') === 0) {
diff --git a/lib/internal/fs/watchers.js b/lib/internal/fs/watchers.js
index 3769e789b46a66..01db66c551c9d3 100644
--- a/lib/internal/fs/watchers.js
+++ b/lib/internal/fs/watchers.js
@@ -33,6 +33,7 @@ const kFSWatchStart = Symbol('kFSWatchStart');
 const kFSStatWatcherStart = Symbol('kFSStatWatcherStart');
 const KFSStatWatcherRefCount = Symbol('KFSStatWatcherRefCount');
 const KFSStatWatcherMaxRefCount = Symbol('KFSStatWatcherMaxRefCount');
+const kFSStatWatcherAddOrCleanRef = Symbol('kFSStatWatcherAddOrCleanRef');
 
 function emitStop(self) {
   self.emit('stop');
@@ -121,19 +122,39 @@ StatWatcher.prototype.stop = function() {
   this._handle = null;
 };
 
+// Clean up or add ref counters.
+StatWatcher.prototype[kFSStatWatcherAddOrCleanRef] = function(operate) {
+  if (operate === 'add') {
+    // Add a Ref
+    this[KFSStatWatcherRefCount]++;
+    this[KFSStatWatcherMaxRefCount]++;
+  } else if (operate === 'clean') {
+    // Clean up a single
+    this[KFSStatWatcherMaxRefCount]--;
+    this.unref();
+  } else if (operate === 'cleanAll') {
+    // Clean up all
+    this[KFSStatWatcherMaxRefCount] = 0;
+    this[KFSStatWatcherRefCount] = 0;
+    this._handle && this._handle.unref();
+  }
+};
+
 StatWatcher.prototype.ref = function() {
   // Avoid refCount calling ref multiple times causing unref to have no effect.
   if (this[KFSStatWatcherRefCount] === this[KFSStatWatcherMaxRefCount])
-    return;
+    return this;
   if (this._handle && this[KFSStatWatcherRefCount]++ === 0)
     this._handle.ref();
+  return this;
 };
 
 StatWatcher.prototype.unref = function() {
   // Avoid refCount calling unref multiple times causing ref to have no effect.
-  if (this[KFSStatWatcherRefCount] === 0) return;
+  if (this[KFSStatWatcherRefCount] === 0) return this;
   if (this._handle && --this[KFSStatWatcherRefCount] === 0)
     this._handle.unref();
+  return this;
 };
 
 
@@ -229,10 +250,12 @@ FSWatcher.prototype.close = function() {
 
 FSWatcher.prototype.ref = function() {
   if (this._handle) this._handle.ref();
+  return this;
 };
 
 FSWatcher.prototype.unref = function() {
   if (this._handle) this._handle.unref();
+  return this;
 };
 
 function emitCloseNT(self) {
@@ -251,6 +274,5 @@ module.exports = {
   StatWatcher,
   kFSWatchStart,
   kFSStatWatcherStart,
-  KFSStatWatcherRefCount,
-  KFSStatWatcherMaxRefCount,
+  kFSStatWatcherAddOrCleanRef,
 };
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
index 77993e254a74fe..e51ecaf5b2fcc1 100644
--- a/test/parallel/test-fs-watch-ref-unref.js
+++ b/test/parallel/test-fs-watch-ref-unref.js
@@ -6,30 +6,15 @@ 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();
+watcher.unref();
 
 setTimeout(
   common.mustCall(() => {
-    ref();
-    unref();
+    watcher.ref();
+    watcher.unref();
   }),
   common.platformTimeout(100)
 );
diff --git a/test/parallel/test-fs-watchfile-ref-unref.js b/test/parallel/test-fs-watchfile-ref-unref.js
index 0c6d61a00bec9a..4ac2691ea9d702 100644
--- a/test/parallel/test-fs-watchfile-ref-unref.js
+++ b/test/parallel/test-fs-watchfile-ref-unref.js
@@ -5,32 +5,31 @@ const common = require('../common');
 const fs = require('fs');
 const assert = require('assert');
 
-let refCount = 0;
+const uncalledListener = common.mustNotCall();
+const uncalledListener2 = common.mustNotCall();
+const watcher = fs.watchFile(__filename, uncalledListener);
 
-const watcher = fs.watchFile(__filename, common.mustNotCall());
+watcher.unref();
+watcher.unref();
+watcher.ref();
+watcher.unref();
+watcher.ref();
+watcher.ref();
+watcher.unref();
 
-function unref() {
-  watcher.unref();
-  refCount--;
-  assert.strictEqual(refCount, -1);
-}
+fs.unwatchFile(__filename, uncalledListener);
 
-function ref() {
-  watcher.ref();
-  refCount++;
-  assert.strictEqual(refCount, 0);
-}
-
-unref();
+// Watch the file with two different listeners.
+fs.watchFile(__filename, uncalledListener);
+const watcher2 = fs.watchFile(__filename, uncalledListener2);
 
 setTimeout(
   common.mustCall(() => {
-    ref();
-    unref();
-    watcher.unref();
-    watcher.ref();
-    watcher.ref();
-    watcher.unref();
+    fs.unwatchFile(__filename, common.mustNotCall());
+    assert.strictEqual(watcher2.listenerCount('change'), 2);
+    fs.unwatchFile(__filename, uncalledListener);
+    assert.strictEqual(watcher2.listenerCount('change'), 1);
+    watcher2.unref();
   }),
   common.platformTimeout(100)
 );
diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js
index 6f98197a741653..1a687719338b12 100644
--- a/tools/doc/type-parser.js
+++ b/tools/doc/type-parser.js
@@ -84,6 +84,7 @@ const customTypesMap = {
   'fs.FSWatcher': 'fs.html#fs_class_fs_fswatcher',
   'fs.ReadStream': 'fs.html#fs_class_fs_readstream',
   'fs.Stats': 'fs.html#fs_class_fs_stats',
+  'fs.StatWatcher': 'fs.html#fs_class_fs_statwatcher',
   'fs.WriteStream': 'fs.html#fs_class_fs_writestream',
 
   'http.Agent': 'http.html#http_class_http_agent',

From 922912374d9cedb496df72aa041e1f1786dbcf9b Mon Sep 17 00:00:00 2001
From: rickyes <mail@zhoumq.cn>
Date: Fri, 1 May 2020 09:25:18 +0800
Subject: [PATCH 3/3] doc: document the return value

---
 doc/api/fs.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index ef9db8807dfcab..3b0a7e17a1044c 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -584,6 +584,8 @@ Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the
 added: REPLACEME
 -->
 
+* Returns: {fs.FSWatcher}
+
 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.
@@ -597,6 +599,8 @@ called previously.
 added: REPLACEME
 -->
 
+* Returns: {fs.FSWatcher}
+
 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
@@ -618,6 +622,8 @@ object.
 added: REPLACEME
 -->
 
+* Returns: {fs.StatWatcher}
+
 When called, requests that the Node.js event loop *not* exit so long as the
 `StatWatcher` is active. Calling `watcher.ref()` multiple times will have
 no effect.
@@ -631,6 +637,8 @@ called previously.
 added: REPLACEME
 -->
 
+* Returns: {fs.StatWatcher}
+
 When called, the active `StatWatcher` 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 `StatWatcher` object's