From 94e0ff94f0c20d6295747564f13a622878c87328 Mon Sep 17 00:00:00 2001
From: Andrea Marchesini <amarchesini@mozilla.com>
Date: Thu, 8 Feb 2018 08:26:05 +0100
Subject: [PATCH] Bug 1435196 - Move the webidl binding interfaces out of
 WorkerPrivate - part 3 - Comments, r=bkelly

---
 dom/workers/WorkerHolder.h  | 43 +++++++++++++++++--------------------
 dom/workers/WorkerPrivate.h | 10 +++++++++
 2 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/dom/workers/WorkerHolder.h b/dom/workers/WorkerHolder.h
index f9819606311a..b5c0d69fb4a8 100644
--- a/dom/workers/WorkerHolder.h
+++ b/dom/workers/WorkerHolder.h
@@ -18,19 +18,19 @@ class WorkerPrivate;
  * Use this chart to help figure out behavior during each of the closing
  * statuses. Details below.
  *
- * +==============================================================+
- * |                       Closing Statuses                       |
- * +=============+=============+=================+================+
- * |    status   | clear queue | abort execution |  close handler |
- * +=============+=============+=================+================+
- * |   Closing   |     yes     |       no        |   no timeout   |
- * +-------------+-------------+-----------------+----------------+
- * | Terminating |     yes     |       yes       |   no timeout   |
- * +-------------+-------------+-----------------+----------------+
- * |  Canceling  |     yes     |       yes       | short duration |
- * +-------------+-------------+-----------------+----------------+
- * |   Killing   |     yes     |       yes       |   doesn't run  |
- * +-------------+-------------+-----------------+----------------+
+ * +=============================================+
+ * |             Closing Statuses                |
+ * +=============+=============+=================+
+ * |    status   | clear queue | abort execution |
+ * +=============+=============+=================+
+ * |   Closing   |     yes     |       no        |
+ * +-------------+-------------+-----------------+
+ * | Terminating |     yes     |       yes       |
+ * +-------------+-------------+-----------------+
+ * |  Canceling  |     yes     |       yes       |
+ * +-------------+-------------+-----------------+
+ * |   Killing   |     yes     |       yes       |
+ * +-------------+-------------+-----------------+
  */
 
 #ifdef Status
@@ -43,32 +43,29 @@ enum WorkerStatus
   // Not yet scheduled.
   Pending = 0,
 
-  // This status means that the close handler has not yet been scheduled.
+  // This status means that the worker is active.
   Running,
 
   // Inner script called close() on the worker global scope. Setting this
   // status causes the worker to clear its queue of events but does not abort
-  // the currently running script. The close handler is also scheduled with
-  // no expiration time.
+  // the currently running script.
   Closing,
 
   // Outer script called terminate() on the worker or the worker object was
   // garbage collected in its outer script. Setting this status causes the
-  // worker to abort immediately, clear its queue of events, and schedules the
-  // close handler with no expiration time.
+  // worker to abort immediately and clear its queue of events.
   Terminating,
 
   // Either the user navigated away from the owning page or the owning page fell
-  // out of bfcache. Setting this status causes the worker to abort immediately
-  // and schedules the close handler with a short expiration time. Since the
-  // page has gone away the worker may not post any messages.
+  // out of bfcache. Setting this status causes the worker to abort immediately.
+  // Since the page has gone away the worker may not post any messages.
   Canceling,
 
   // The application is shutting down. Setting this status causes the worker to
-  // abort immediately and the close handler is never scheduled.
+  // abort immediately.
   Killing,
 
-  // The close handler has run and the worker is effectively dead.
+  // The worker is effectively dead.
   Dead
 };
 
diff --git a/dom/workers/WorkerPrivate.h b/dom/workers/WorkerPrivate.h
index e4ae27ee8ddf..c82e8e586ce8 100644
--- a/dom/workers/WorkerPrivate.h
+++ b/dom/workers/WorkerPrivate.h
@@ -182,6 +182,16 @@ protected:
   // The worker is owned by its thread, which is represented here.  This is set
   // in Constructor() and emptied by WorkerFinishedRunnable, and conditionally
   // traversed by the cycle collector if the busy count is zero.
+  //
+  // There are 4 ways a worker can be terminated:
+  // 1. GC/CC - When the worker is in idle state (busycount == 0), it allows to
+  //    traverse the 'hidden' mParentEventTargetRef pointer. This is the exposed
+  //    Worker webidl object. Doing this, CC will be able to detect a cycle and
+  //    Unlink is called. In Unlink, Worker calls Terminate().
+  // 2. Worker::Terminate() is called - the shutdown procedure starts
+  //    immediately.
+  // 3. WorkerScope::Close() is called - Similar to point 2.
+  // 4. xpcom-shutdown notification - We call Kill().
   RefPtr<Worker> mParentEventTargetRef;
   RefPtr<WorkerPrivate> mSelfRef;