Worker: Add more comments about WorkerThread shutdown

Bug: n/a
Change-Id: I801524511be42b3e47c04ca93d7914c7df94968c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2034384Reviewed-by: Makoto Shimazu <shimazu@chromium.org>
Reviewed-by: Matt Falkenhagen <falken@chromium.org>
Reviewed-by: Kenichi Ishibashi <bashi@chromium.org>
Commit-Queue: Hiroki Nakagawa <nhiroki@chromium.org>
Cr-Commit-Position: refs/heads/master@{#738086}

third_party/blink/renderer/core/workers/worker_thread.cc

@@ -338,7 +338,14 @@ void WorkerThread::DidProcessTask(const base::PendingTask& pending_task) {
     // This WorkerThread will eventually be requested to terminate.
     GetWorkerReportingProxy().DidCloseWorkerGlobalScope();
 
-    // Stop further worker tasks to run after this point.
+    // Stop further worker tasks to run after this point based on the spec:
+    // https://html.spec.whatwg.org/C/#close-a-worker
+    //
+    // "To close a worker, given a workerGlobal, run these steps:"
+    // Step 1: "Discard any tasks that have been added to workerGlobal's event
+    // loop's task queues."
+    // Step 2: "Set workerGlobal's closing flag to true. (This prevents any
+    // further tasks from being queued.)"
     PrepareForShutdownOnWorkerThread();
   } else if (IsForciblyTerminated()) {
     // The script has been terminated forcibly, which means we need to

third_party/blink/renderer/core/workers/worker_thread.h

@@ -343,7 +343,35 @@ class CORE_EXPORT WorkerThread : public Thread::TaskObserver {
       WorkerResourceTimingNotifier* outside_resource_timing_notifier,
       network::mojom::CredentialsMode);
 
-  // These are called in this order during worker thread termination.
+  // PrepareForShutdownOnWorkerThread() notifies that the context will be
+  // destroyed, discards queued tasks to prevent running further tasks, and
+  // initiates termination of nested workers. It runs on the worker thread. It
+  // can be called due to the parent thread posting a task to run it on the
+  // worker thread, or the worker thread calling it itself synchronously.
+  //
+  // PerformShutdownOnWorkerThread() destroys the global scope, and notifies the
+  // parent thread of completion of worker shutdown. A call of this function can
+  // be postponed until all nested workers are terminated. It runs on the worker
+  // thread. It can be called due to the parent thread posting a task to run it
+  // on the worker thread, or the worker thread calling it itself synchronously
+  // after all nested workers are terminated.
+  //
+  // These are called in this order during worker shutdown.
+  //
+  // The reason why worker shutdown is separated into these 2 functions:
+  // Workers can simultaneously be requested to terminate for various reasons.
+  // To serialize the termination requests, worker shutdown is supposed to be
+  // initiated from the parent thread (i.e., Terminate()). On the other hand,
+  // queued tasks etc must be discarded as soon as possible after shutdown is
+  // requested to prevent running further tasks. To be specific, when close() is
+  // called on the worker global scope, queued tasks must be discarded soon
+  // before worker shutdown is formally requested via the parent thread. The
+  // HTML spec defines this behavior (see spec comments in DidProcessTask()).
+  // To achieve this, the worker thread runs PrepareForShutdownOnWorkerThread()
+  // immediately after the task that called close() (see DidProcessTask()), and
+  // then posts a task to the parent thread to request termination. In addition
+  // to that, separate functions are useful for waiting until all nested workers
+  // are terminated before the parent thread shut down.
   void PrepareForShutdownOnWorkerThread() LOCKS_EXCLUDED(mutex_);
   void PerformShutdownOnWorkerThread() LOCKS_EXCLUDED(mutex_);