base/sequenced_task_runner.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_SEQUENCED_TASK_RUNNER_H_
   6 #define BASE_SEQUENCED_TASK_RUNNER_H_
   7
   8 #include <memory>
   9
  10 #include "base/base_export.h"
  11 #include "base/callback.h"
  12 #include "base/sequenced_task_runner_helpers.h"
  13 #include "base/task_runner.h"
  14
  15 namespace base {
  16
  17 // A SequencedTaskRunner is a subclass of TaskRunner that provides
  18 // additional guarantees on the order that tasks are started, as well
  19 // as guarantees on when tasks are in sequence, i.e. one task finishes
  20 // before the other one starts.
  21 //
  22 // Summary
  23 // -------
  24 // Non-nested tasks with the same delay will run one by one in FIFO
  25 // order.
  26 //
  27 // Detailed guarantees
  28 // -------------------
  29 //
  30 // SequencedTaskRunner also adds additional methods for posting
  31 // non-nestable tasks.  In general, an implementation of TaskRunner
  32 // may expose task-running methods which are themselves callable from
  33 // within tasks.  A non-nestable task is one that is guaranteed to not
  34 // be run from within an already-running task.  Conversely, a nestable
  35 // task (the default) is a task that can be run from within an
  36 // already-running task.
  37 //
  38 // The guarantees of SequencedTaskRunner are as follows:
  39 //
  40 //   - Given two tasks T2 and T1, T2 will start after T1 starts if:
  41 //
  42 //       * T2 is posted after T1; and
  43 //       * T2 has equal or higher delay than T1; and
  44 //       * T2 is non-nestable or T1 is nestable.
  45 //
  46 //   - If T2 will start after T1 starts by the above guarantee, then
  47 //     T2 will start after T1 finishes and is destroyed if:
  48 //
  49 //       * T2 is non-nestable, or
  50 //       * T1 doesn't call any task-running methods.
  51 //
  52 //   - If T2 will start after T1 finishes by the above guarantee, then
  53 //     all memory changes in T1 and T1's destruction will be visible
  54 //     to T2.
  55 //
  56 //   - If T2 runs nested within T1 via a call to the task-running
  57 //     method M, then all memory changes in T1 up to the call to M
  58 //     will be visible to T2, and all memory changes in T2 will be
  59 //     visible to T1 from the return from M.
  60 //
  61 // Note that SequencedTaskRunner does not guarantee that tasks are run
  62 // on a single dedicated thread, although the above guarantees provide
  63 // most (but not all) of the same guarantees.  If you do need to
  64 // guarantee that tasks are run on a single dedicated thread, see
  65 // SingleThreadTaskRunner (in single_thread_task_runner.h).
  66 //
  67 // Some corollaries to the above guarantees, assuming the tasks in
  68 // question don't call any task-running methods:
  69 //
  70 //   - Tasks posted via PostTask are run in FIFO order.
  71 //
  72 //   - Tasks posted via PostNonNestableTask are run in FIFO order.
  73 //
  74 //   - Tasks posted with the same delay and the same nestable state
  75 //     are run in FIFO order.
  76 //
  77 //   - A list of tasks with the same nestable state posted in order of
  78 //     non-decreasing delay is run in FIFO order.
  79 //
  80 //   - A list of tasks posted in order of non-decreasing delay with at
  81 //     most a single change in nestable state from nestable to
  82 //     non-nestable is run in FIFO order. (This is equivalent to the
  83 //     statement of the first guarantee above.)
  84 //
  85 // Some theoretical implementations of SequencedTaskRunner:
  86 //
  87 //   - A SequencedTaskRunner that wraps a regular TaskRunner but makes
  88 //     sure that only one task at a time is posted to the TaskRunner,
  89 //     with appropriate memory barriers in between tasks.
  90 //
  91 //   - A SequencedTaskRunner that, for each task, spawns a joinable
  92 //     thread to run that task and immediately quit, and then
  93 //     immediately joins that thread.
  94 //
  95 //   - A SequencedTaskRunner that stores the list of posted tasks and
  96 //     has a method Run() that runs each runnable task in FIFO order
  97 //     that can be called from any thread, but only if another
  98 //     (non-nested) Run() call isn't already happening.
  99 class BASE_EXPORT SequencedTaskRunner : public TaskRunner {
 100  public:
 101   // The two PostNonNestable*Task methods below are like their
 102   // nestable equivalents in TaskRunner, but they guarantee that the
 103   // posted task will not run nested within an already-running task.
 104   //
 105   // A simple corollary is that posting a task as non-nestable can
 106   // only delay when the task gets run.  That is, posting a task as
 107   // non-nestable may not affect when the task gets run, or it could
 108   // make it run later than it normally would, but it won't make it
 109   // run earlier than it normally would.
 110
 111   // TODO(akalin): Get rid of the boolean return value for the methods
 112   // below.
 113
 114   bool PostNonNestableTask(const Location& from_here, OnceClosure task);
 115
 116   virtual bool PostNonNestableDelayedTask(const Location& from_here,
 117                                           OnceClosure task,
 118                                           base::TimeDelta delay) = 0;
 119
 120   // Submits a non-nestable task to delete the given object.  Returns
 121   // true if the object may be deleted at some point in the future,
 122   // and false if the object definitely will not be deleted.
 123   template <class T>
 124   bool DeleteSoon(const Location& from_here, const T* object) {
 125     return DeleteOrReleaseSoonInternal(from_here, &DeleteHelper<T>::DoDelete,
 126                                        object);
 127   }
 128
 129   template <class T>
 130   bool DeleteSoon(const Location& from_here, std::unique_ptr<T> object) {
 131     return DeleteSoon(from_here, object.release());
 132   }
 133
 134   // Submits a non-nestable task to release the given object.
 135   //
 136   // ReleaseSoon makes sure that the object it the scoped_refptr points to gets
 137   // properly released on the correct thread.
 138   // We apply ReleaseSoon to the rvalue as the side-effects can be unclear to
 139   // the caller if an lvalue is used. That being so, the scoped_refptr should
 140   // always be std::move'd.
 141   // Example use:
 142   //
 143   // scoped_refptr<T> foo_scoped_refptr;
 144   // ...
 145   // task_runner->ReleaseSoon(std::move(foo_scoped_refptr));
 146   template <class T>
 147   void ReleaseSoon(const Location& from_here, scoped_refptr<T>&& object) {
 148     if (!object)
 149       return;
 150
 151     DeleteOrReleaseSoonInternal(from_here, &ReleaseHelper<T>::DoRelease,
 152                                 object.release());
 153   }
 154
 155  protected:
 156   ~SequencedTaskRunner() override = default;
 157
 158  private:
 159   bool DeleteOrReleaseSoonInternal(const Location& from_here,
 160                                    void (*deleter)(const void*),
 161                                    const void* object);
 162 };
 163
 164 // Sample usage with std::unique_ptr :
 165 // std::unique_ptr<Foo, base::OnTaskRunnerDeleter> ptr(
 166 //     new Foo, base::OnTaskRunnerDeleter(my_task_runner));
 167 //
 168 // For RefCounted see base::RefCountedDeleteOnSequence.
 169 struct BASE_EXPORT OnTaskRunnerDeleter {
 170   explicit OnTaskRunnerDeleter(scoped_refptr<SequencedTaskRunner> task_runner);
 171   ~OnTaskRunnerDeleter();
 172
 173   OnTaskRunnerDeleter(OnTaskRunnerDeleter&&);
 174   OnTaskRunnerDeleter& operator=(OnTaskRunnerDeleter&&);
 175
 176   // For compatibility with std:: deleters.
 177   template <typename T>
 178   void operator()(const T* ptr) {
 179     if (ptr)
 180       task_runner_->DeleteSoon(FROM_HERE, ptr);
 181   }
 182
 183   scoped_refptr<SequencedTaskRunner> task_runner_;
 184 };
 185
 186 }  // namespace base
 187
 188 #endif  // BASE_SEQUENCED_TASK_RUNNER_H_