// 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 #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 bool DeleteSoon(const Location& from_here, const T* object) { return DeleteOrReleaseSoonInternal(from_here, &DeleteHelper::DoDelete, object); } template bool DeleteSoon(const Location& from_here, std::unique_ptr object) { return DeleteOrReleaseSoonInternal( from_here, &DeleteUniquePtrHelper::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 foo_scoped_refptr; // ... // task_runner->ReleaseSoon(std::move(foo_scoped_refptr)); template void ReleaseSoon(const Location& from_here, scoped_refptr&& object) { if (!object) return; DeleteOrReleaseSoonInternal(from_here, &ReleaseHelper::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 ptr( // new Foo, base::OnTaskRunnerDeleter(my_task_runner)); // // For RefCounted see base::RefCountedDeleteOnSequence. struct BASE_EXPORT OnTaskRunnerDeleter { explicit OnTaskRunnerDeleter(scoped_refptr task_runner); ~OnTaskRunnerDeleter(); OnTaskRunnerDeleter(OnTaskRunnerDeleter&&); OnTaskRunnerDeleter& operator=(OnTaskRunnerDeleter&&); // For compatibility with std:: deleters. template void operator()(const T* ptr) { if (ptr) task_runner_->DeleteSoon(FROM_HERE, ptr); } scoped_refptr task_runner_; }; } // namespace base #endif // BASE_TASK_SEQUENCED_TASK_RUNNER_H_