Add WebTaskRunner::postCancellableTask

third_party/WebKit/Source/platform/scheduler/CancellableTaskFactory.h

 // Copyright 2015 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 CancellableTaskFactory_h
 #define CancellableTaskFactory_h
 
 #include "platform/PlatformExport.h"
 #include "platform/heap/Handle.h"
 #include "public/platform/WebTaskRunner.h"
 #include "wtf/Allocator.h"
 #include "wtf/Functional.h"
 #include "wtf/Noncopyable.h"
 #include "wtf/PtrUtil.h"
 #include "wtf/WeakPtr.h"
 #include <memory>
 #include <type_traits>
 
+// WebTaskRunner::postCancellableTask will replace CancellableTaskFactory.
+// Use postCancellableTask in new code.
+// Example: For |task_runner| and |foo| below.
+//   WebTaskRunner* task_runner;
+//   Foo* foo;
+//
+//   CancellableTaskFactory factory(foo, &Foo::bar);
+//   task_runner->postTask(BLINK_FROM_HERE, factory.cancelAndCreate());
+//   factory.cancel();
+//
+// Above is equivalent to below:
+//
+//   std::unique_ptr<WTF::Closure> task =
+//       WTF::bind(wrapPersistent(foo), &Foo::bar);
+//   RefPtr<TaskHandle> handle =
+//       task_runner->postCancellableTask(BLINK_FROM_HERE, std::move(task));
+//   handle->cancel();
+//
+// Note that the task is not automatically cancelled on the scope out of
+// RefPtr<TaskHandle>, since the wrapped task has a reference to the TaskHandle.
+
 namespace blink {
 
 class TraceLocation;
 
 class PLATFORM_EXPORT CancellableTaskFactory {
   WTF_MAKE_NONCOPYABLE(CancellableTaskFactory);
   USING_FAST_MALLOC(CancellableTaskFactory);
 
  public:
   // A pair of mutually exclusive factory methods are provided for constructing
@@ skipping 60 matching lines @@
     WeakPtr<CancellableTaskFactory> m_weakPtr;
   };
 
   std::unique_ptr<WTF::Closure> m_closure;
   WeakPtrFactory<CancellableTaskFactory> m_weakPtrFactory;
 };
 
 }  // namespace blink
 
 #endif  // CancellableTaskFactory_h