123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299 |
- // 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_TASK_SEQUENCED_TASK_RUNNER_H_
- #define BASE_TASK_SEQUENCED_TASK_RUNNER_H_
- #include <memory>
- #include "base/base_export.h"
- #include "base/callback.h"
- #include "base/task/delay_policy.h"
- #include "base/task/delayed_task_handle.h"
- #include "base/task/sequenced_task_runner_helpers.h"
- #include "base/task/task_runner.h"
- #include "base/types/pass_key.h"
- namespace blink {
- class LowPrecisionTimer;
- class MetronomeSource;
- class TimerBase;
- class WebRtcTaskQueue;
- }
- namespace webrtc {
- class ThreadWrapper;
- } // namespace webrtc
- namespace media {
- class AlsaPcmOutputStream;
- class AlsaPcmInputStream;
- class FakeAudioWorker;
- } // namespace media
- namespace base {
- namespace internal {
- class DelayTimerBase;
- class DelayedTaskManager;
- }
- class DeadlineTimer;
- class MetronomeTimer;
- class TimeDelta;
- class TimeTicks;
- namespace subtle {
- // Used to restrict access to PostCancelableDelayedTaskAt() to authorize
- // callers.
- class PostDelayedTaskPassKey {
- private:
- // Avoid =default to disallow creation by uniform initialization.
- PostDelayedTaskPassKey() {}
- friend class base::internal::DelayTimerBase;
- friend class base::internal::DelayedTaskManager;
- friend class base::DeadlineTimer;
- friend class base::MetronomeTimer;
- friend class blink::LowPrecisionTimer;
- friend class blink::MetronomeSource;
- friend class blink::TimerBase;
- friend class blink::WebRtcTaskQueue;
- friend class PostDelayedTaskPassKeyForTesting;
- friend class webrtc::ThreadWrapper;
- friend class media::AlsaPcmOutputStream;
- friend class media::AlsaPcmInputStream;
- friend class media::FakeAudioWorker;
- };
- class PostDelayedTaskPassKeyForTesting : public PostDelayedTaskPassKey {};
- } // namespace subtle
- // A SequencedTaskRunner is a subclass of TaskRunner that provides
- // additional guarantees on the order that tasks are started, as well
- // as guarantees on when tasks are in sequence, i.e. one task finishes
- // before the other one starts.
- //
- // Summary
- // -------
- // Non-nested tasks with the same delay will run one by one in FIFO
- // order.
- //
- // Detailed guarantees
- // -------------------
- //
- // SequencedTaskRunner also adds additional methods for posting
- // non-nestable tasks. In general, an implementation of TaskRunner
- // may expose task-running methods which are themselves callable from
- // within tasks. A non-nestable task is one that is guaranteed to not
- // be run from within an already-running task. Conversely, a nestable
- // task (the default) is a task that can be run from within an
- // already-running task.
- //
- // The guarantees of SequencedTaskRunner are as follows:
- //
- // - Given two tasks T2 and T1, T2 will start after T1 starts if:
- //
- // * T2 is posted after T1; and
- // * T2 has equal or higher delay than T1; and
- // * T2 is non-nestable or T1 is nestable.
- //
- // - If T2 will start after T1 starts by the above guarantee, then
- // T2 will start after T1 finishes and is destroyed if:
- //
- // * T2 is non-nestable, or
- // * T1 doesn't call any task-running methods.
- //
- // - If T2 will start after T1 finishes by the above guarantee, then
- // all memory changes in T1 and T1's destruction will be visible
- // to T2.
- //
- // - If T2 runs nested within T1 via a call to the task-running
- // method M, then all memory changes in T1 up to the call to M
- // will be visible to T2, and all memory changes in T2 will be
- // visible to T1 from the return from M.
- //
- // Note that SequencedTaskRunner does not guarantee that tasks are run
- // on a single dedicated thread, although the above guarantees provide
- // most (but not all) of the same guarantees. If you do need to
- // guarantee that tasks are run on a single dedicated thread, see
- // SingleThreadTaskRunner (in single_thread_task_runner.h).
- //
- // Some corollaries to the above guarantees, assuming the tasks in
- // question don't call any task-running methods:
- //
- // - Tasks posted via PostTask are run in FIFO order.
- //
- // - Tasks posted via PostNonNestableTask are run in FIFO order.
- //
- // - Tasks posted with the same delay and the same nestable state
- // are run in FIFO order.
- //
- // - A list of tasks with the same nestable state posted in order of
- // non-decreasing delay is run in FIFO order.
- //
- // - A list of tasks posted in order of non-decreasing delay with at
- // most a single change in nestable state from nestable to
- // non-nestable is run in FIFO order. (This is equivalent to the
- // statement of the first guarantee above.)
- //
- // Some theoretical implementations of SequencedTaskRunner:
- //
- // - A SequencedTaskRunner that wraps a regular TaskRunner but makes
- // sure that only one task at a time is posted to the TaskRunner,
- // with appropriate memory barriers in between tasks.
- //
- // - A SequencedTaskRunner that, for each task, spawns a joinable
- // thread to run that task and immediately quit, and then
- // immediately joins that thread.
- //
- // - A SequencedTaskRunner that stores the list of posted tasks and
- // has a method Run() that runs each runnable task in FIFO order
- // that can be called from any thread, but only if another
- // (non-nested) Run() call isn't already happening.
- class BASE_EXPORT SequencedTaskRunner : public TaskRunner {
- public:
- // The two PostNonNestable*Task methods below are like their
- // nestable equivalents in TaskRunner, but they guarantee that the
- // posted task will not run nested within an already-running task.
- //
- // A simple corollary is that posting a task as non-nestable can
- // only delay when the task gets run. That is, posting a task as
- // non-nestable may not affect when the task gets run, or it could
- // make it run later than it normally would, but it won't make it
- // run earlier than it normally would.
- // TODO(akalin): Get rid of the boolean return value for the methods
- // below.
- bool PostNonNestableTask(const Location& from_here, OnceClosure task);
- virtual bool PostNonNestableDelayedTask(const Location& from_here,
- OnceClosure task,
- base::TimeDelta delay) = 0;
- // Posts the given |task| to be run only after |delay| has passed. Returns a
- // handle that can be used to cancel the task. This should not be used
- // directly. Consider using higher level timer primitives in
- // base/timer/timer.h.
- //
- // The handle is only valid while the task is pending execution. This means
- // that it will be invalid if the posting failed, and will be invalid while
- // the task is executing. Calling CancelTask() on an invalid handle is a
- // no-op.
- //
- // This method and the handle it returns are not thread-safe and can only be
- // used from the sequence this task runner runs its tasks on.
- virtual DelayedTaskHandle PostCancelableDelayedTask(
- subtle::PostDelayedTaskPassKey,
- const Location& from_here,
- OnceClosure task,
- TimeDelta delay);
- // Posts the given |task| to be run at |delayed_run_time| (or immediately if
- // in the past), following |delay_policy|. Returns a handle that can be used
- // to cancel the task. This should not be used directly. Consider using higher
- // level timer primitives in base/timer/timer.h.
- [[nodiscard]] virtual DelayedTaskHandle PostCancelableDelayedTaskAt(
- subtle::PostDelayedTaskPassKey,
- const Location& from_here,
- OnceClosure task,
- TimeTicks delayed_run_time,
- subtle::DelayPolicy delay_policy);
- // Posts the given |task| to be run at |delayed_run_time| (or immediately if
- // in the past), following |delay_policy|. This is used by the default
- // implementation of PostCancelableDelayedTaskAt(). The default behavior
- // subtracts TimeTicks::Now() from |delayed_run_time| to get a delay. See
- // base::Timer to post precise/repeating timeouts.
- // TODO(1153139): Make pure virtual once all SequencedTaskRunners implement
- // this.
- virtual bool PostDelayedTaskAt(subtle::PostDelayedTaskPassKey,
- const Location& from_here,
- OnceClosure task,
- TimeTicks delayed_run_time,
- subtle::DelayPolicy delay_policy);
- // Submits a non-nestable task to delete the given object. Returns
- // true if the object may be deleted at some point in the future,
- // and false if the object definitely will not be deleted.
- template <class T>
- bool DeleteSoon(const Location& from_here, const T* object) {
- return DeleteOrReleaseSoonInternal(from_here, &DeleteHelper<T>::DoDelete,
- object);
- }
- template <class T>
- bool DeleteSoon(const Location& from_here, std::unique_ptr<T> object) {
- return DeleteOrReleaseSoonInternal(
- from_here, &DeleteUniquePtrHelper<T>::DoDelete, object.release());
- }
- // Submits a non-nestable task to release the given object.
- //
- // ReleaseSoon makes sure that the object it the scoped_refptr points to gets
- // properly released on the correct thread.
- // We apply ReleaseSoon to the rvalue as the side-effects can be unclear to
- // the caller if an lvalue is used. That being so, the scoped_refptr should
- // always be std::move'd.
- // Example use:
- //
- // scoped_refptr<T> foo_scoped_refptr;
- // ...
- // task_runner->ReleaseSoon(std::move(foo_scoped_refptr));
- template <class T>
- void ReleaseSoon(const Location& from_here, scoped_refptr<T>&& object) {
- if (!object)
- return;
- DeleteOrReleaseSoonInternal(from_here, &ReleaseHelper<T>::DoRelease,
- object.release());
- }
- // Returns true iff tasks posted to this TaskRunner are sequenced
- // with this call.
- //
- // In particular:
- // - Returns true if this is a SequencedTaskRunner to which the
- // current task was posted.
- // - Returns true if this is a SequencedTaskRunner bound to the
- // same sequence as the SequencedTaskRunner to which the current
- // task was posted.
- // - Returns true if this is a SingleThreadTaskRunner bound to
- // the current thread.
- virtual bool RunsTasksInCurrentSequence() const = 0;
- protected:
- ~SequencedTaskRunner() override = default;
- private:
- bool DeleteOrReleaseSoonInternal(const Location& from_here,
- void (*deleter)(const void*),
- const void* object);
- };
- // Sample usage with std::unique_ptr :
- // std::unique_ptr<Foo, base::OnTaskRunnerDeleter> ptr(
- // new Foo, base::OnTaskRunnerDeleter(my_task_runner));
- //
- // For RefCounted see base::RefCountedDeleteOnSequence.
- struct BASE_EXPORT OnTaskRunnerDeleter {
- explicit OnTaskRunnerDeleter(scoped_refptr<SequencedTaskRunner> task_runner);
- ~OnTaskRunnerDeleter();
- OnTaskRunnerDeleter(OnTaskRunnerDeleter&&);
- OnTaskRunnerDeleter& operator=(OnTaskRunnerDeleter&&);
- // For compatibility with std:: deleters.
- template <typename T>
- void operator()(const T* ptr) {
- if (ptr)
- task_runner_->DeleteSoon(FROM_HERE, ptr);
- }
- scoped_refptr<SequencedTaskRunner> task_runner_;
- };
- } // namespace base
- #endif // BASE_TASK_SEQUENCED_TASK_RUNNER_H_
|