| // Copyright 2016 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_SCHEDULER_SCHEDULER_WORKER_H_ |
| #define BASE_TASK_SCHEDULER_SCHEDULER_WORKER_H_ |
| |
| #include <memory> |
| |
| #include "base/base_export.h" |
| #include "base/macros.h" |
| #include "base/memory/ref_counted.h" |
| #include "base/synchronization/atomic_flag.h" |
| #include "base/synchronization/waitable_event.h" |
| #include "base/task_scheduler/scheduler_lock.h" |
| #include "base/task_scheduler/sequence.h" |
| #include "base/threading/platform_thread.h" |
| #include "base/time/time.h" |
| |
| namespace base { |
| namespace internal { |
| |
| class TaskTracker; |
| |
| // A worker that manages a single thread to run Tasks from Sequences returned |
| // by a delegate. |
| // |
| // A SchedulerWorker starts out sleeping. It is woken up by a call to WakeUp(). |
| // After a wake-up, a SchedulerWorker runs Tasks from Sequences returned by the |
| // GetWork() method of its delegate as long as it doesn't return nullptr. It |
| // also periodically checks with its TaskTracker whether shutdown has completed |
| // and exits when it has. |
| // |
| // The worker is free to release and reallocate the platform thread with |
| // guidance from the delegate. |
| // |
| // This class is thread-safe. |
| class BASE_EXPORT SchedulerWorker { |
| public: |
| // Delegate interface for SchedulerWorker. The methods are always called from |
| // the thread managed by the SchedulerWorker instance. |
| class Delegate { |
| public: |
| virtual ~Delegate() = default; |
| |
| // Called by a thread managed by |worker| when it enters its main function. |
| // If a thread is recreated after detachment, |detach_duration| is the time |
| // elapsed since detachment. Otherwise, if this is the first thread created |
| // for |worker|, |detach_duration| is TimeDelta::Max(). |
| virtual void OnMainEntry(SchedulerWorker* worker) = 0; |
| |
| // Called by a thread managed by |worker| to get a Sequence from which to |
| // run a Task. |
| virtual scoped_refptr<Sequence> GetWork(SchedulerWorker* worker) = 0; |
| |
| // Called by the SchedulerWorker after it ran a task with |task_priority|. |
| // |task_latency| is the time elapsed between when the task was posted and |
| // when it started to run. |
| virtual void DidRunTaskWithPriority(TaskPriority task_priority, |
| const TimeDelta& task_latency) = 0; |
| |
| // Called when |sequence| isn't empty after the SchedulerWorker pops a Task |
| // from it. |sequence| is the last Sequence returned by GetWork(). |
| virtual void ReEnqueueSequence(scoped_refptr<Sequence> sequence) = 0; |
| |
| // Called by a thread to determine how long to sleep before the next call to |
| // GetWork(). GetWork() may be called before this timeout expires if the |
| // worker's WakeUp() method is called. |
| virtual TimeDelta GetSleepTimeout() = 0; |
| |
| // Called by a thread if it is allowed to detach if the last call to |
| // GetWork() returned nullptr. |
| // |
| // It is the responsibility of the delegate to determine if detachment is |
| // safe. If the delegate is responsible for thread-affine work, detachment |
| // is generally not safe. |
| // |
| // When true is returned: |
| // - The next WakeUp() could be more costly due to new thread creation. |
| // - The worker will take this as a signal that it can detach, but it is not |
| // obligated to do so. |
| // This MUST return false if SchedulerWorker::JoinForTesting() is in |
| // progress. |
| virtual bool CanDetach(SchedulerWorker* worker) = 0; |
| |
| // Called by a thread before it detaches. This method is not allowed to |
| // acquire a SchedulerLock because it is called within the scope of another |
| // SchedulerLock. |
| virtual void OnDetach() = 0; |
| }; |
| |
| enum class InitialState { ALIVE, DETACHED }; |
| |
| // Creates a SchedulerWorker that runs Tasks from Sequences returned by |
| // |delegate|. |priority_hint| is the preferred thread priority; the actual |
| // thread priority depends on shutdown state and platform capabilities. |
| // |task_tracker| is used to handle shutdown behavior of Tasks. If |
| // |worker_state| is DETACHED, the thread will be created upon a WakeUp(). |
| // Returns nullptr if creating the underlying platform thread fails during |
| // Create(). |
| static std::unique_ptr<SchedulerWorker> Create( |
| ThreadPriority priority_hint, |
| std::unique_ptr<Delegate> delegate, |
| TaskTracker* task_tracker, |
| InitialState initial_state); |
| |
| // Destroying a SchedulerWorker in production is not allowed; it is always |
| // leaked. In tests, it can only be destroyed after JoinForTesting() has |
| // returned. |
| ~SchedulerWorker(); |
| |
| // Wakes up this SchedulerWorker if it wasn't already awake. After this |
| // is called, this SchedulerWorker will run Tasks from Sequences |
| // returned by the GetWork() method of its delegate until it returns nullptr. |
| // WakeUp() may fail if the worker is detached and it fails to allocate a new |
| // worker. If this happens, there will be no call to GetWork(). |
| void WakeUp(); |
| |
| SchedulerWorker::Delegate* delegate() { return delegate_.get(); } |
| |
| // Joins this SchedulerWorker. If a Task is already running, it will be |
| // allowed to complete its execution. This can only be called once. |
| void JoinForTesting(); |
| |
| // Returns true if the worker is alive. |
| bool ThreadAliveForTesting() const; |
| |
| private: |
| class Thread; |
| |
| SchedulerWorker(ThreadPriority thread_priority, |
| std::unique_ptr<Delegate> delegate, |
| TaskTracker* task_tracker); |
| |
| // Returns the thread instance if the detach was successful so that it can be |
| // freed upon termination of the thread. |
| // If the detach is not possible, returns nullptr. |
| std::unique_ptr<SchedulerWorker::Thread> Detach(); |
| |
| void CreateThread(); |
| |
| void CreateThreadAssertSynchronized(); |
| |
| // Synchronizes access to |thread_|. |
| mutable SchedulerLock thread_lock_; |
| |
| // The underlying thread for this SchedulerWorker. |
| std::unique_ptr<Thread> thread_; |
| |
| const ThreadPriority priority_hint_; |
| const std::unique_ptr<Delegate> delegate_; |
| TaskTracker* const task_tracker_; |
| |
| // Set once JoinForTesting() has been called. |
| AtomicFlag should_exit_for_testing_; |
| |
| DISALLOW_COPY_AND_ASSIGN(SchedulerWorker); |
| }; |
| |
| } // namespace internal |
| } // namespace base |
| |
| #endif // BASE_TASK_SCHEDULER_SCHEDULER_WORKER_H_ |