Ensure SequencedWorkerPool::Shutdown() blocks for already-started SKIP_ON_SHUTDOWN tasks

base/threading/sequenced_worker_pool.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_THREADING_SEQUENCED_WORKER_POOL_H_
 #define BASE_THREADING_SEQUENCED_WORKER_POOL_H_
 
 #include <cstddef>
 #include <string>
 
@@ skipping 44 matching lines @@
 //
 // Implementation note: This does not use a base::WorkerPool since that does
 // not enforce shutdown semantics or allow us to specify how many worker
 // threads to run. For the typical use case of random background work, we don't
 // necessarily want to be super aggressive about creating threads.
 //
 // Note that SequencedWorkerPool is RefCountedThreadSafe (inherited
 // from TaskRunner).
 class BASE_EXPORT SequencedWorkerPool : public TaskRunner {
  public:
-  // Defines what should happen to a task posted to the worker pool on shutdown.
+  // Defines what should happen to a task posted to the worker pool on
+  // shutdown.
   enum WorkerShutdown {
     // Tasks posted with this mode which have not run at shutdown will be
     // deleted rather than run, and any tasks with this mode running at
     // shutdown will be ignored (the worker thread will not be joined).
     //
     // This option provides a nice way to post stuff you don't want blocking
     // shutdown. For example, you might be doing a slow DNS lookup and if it's
     // blocked on the OS, you may not want to stop shutdown, since the result
     // doesn't really matter at that point.
     //
     // However, you need to be very careful what you do in your callback when
     // you use this option. Since the thread will continue to run until the OS
     // terminates the process, the app can be in the process of tearing down
     // when you're running. This means any singletons or global objects you
     // use may suddenly become invalid out from under you. For this reason,
     // it's best to use this only for slow but simple operations like the DNS
     // example.
     CONTINUE_ON_SHUTDOWN,
 
-    // Tasks posted with this mode that have not started executing at shutdown
-    // will be deleted rather than executed. However, tasks already in progress
-    // will be completed.
+    // Tasks posted with this mode that have not started executing at
+    // shutdown will be deleted rather than executed. However, any tasks that
+    // have already begun executing when shutdown is called will be allowed
+    // to continue, and will block shutdown until completion.
+    //
+    // Note: Because Shutdown() may block while these tasks are executing,
+    // care must be taken to ensure that they do not block on the thread that
+    // called Shutdown(), as this may lead to deadlock.
     SKIP_ON_SHUTDOWN,
 
-    // Tasks posted with this mode will block browser shutdown until they're
-    // executed. Since this can have significant performance implications, use
-    // sparingly.
+    // Tasks posted with this mode will block shutdown until they're
+    // executed. Since this can have significant performance implications,
+    // use sparingly.
     //
     // Generally, this should be used only for user data, for example, a task
     // writing a preference file.
     //
     // If a task is posted during shutdown, it will not get run since the
     // workers may already be stopped. In this case, the post operation will
     // fail (return false) and the task will be deleted.
     BLOCK_SHUTDOWN,
   };
 
@@ skipping 171 matching lines @@
   // Avoid pulling in too many headers by putting (almost) everything
   // into |inner_|.
   const scoped_ptr<Inner> inner_;
 
   DISALLOW_COPY_AND_ASSIGN(SequencedWorkerPool);
 };
 
 }  // namespace base
 
 #endif  // BASE_THREADING_SEQUENCED_WORKER_POOL_H_