blob: 072516087f91f6b10a6f5767e49d883b74fc168d [file] [log] [blame]
// Copyright 2018 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_SEQUENCE_MANAGER_TASK_QUEUE_H_
#define BASE_TASK_SEQUENCE_MANAGER_TASK_QUEUE_H_
#include <memory>
#include "base/macros.h"
#include "base/memory/weak_ptr.h"
#include "base/message_loop/message_loop.h"
#include "base/optional.h"
#include "base/single_thread_task_runner.h"
#include "base/synchronization/lock.h"
#include "base/task/sequence_manager/lazy_now.h"
#include "base/task/sequence_manager/moveable_auto_lock.h"
#include "base/task/sequence_manager/tasks.h"
#include "base/threading/platform_thread.h"
#include "base/time/time.h"
namespace base {
namespace trace_event {
class BlameContext;
}
namespace sequence_manager {
namespace internal {
struct AssociatedThreadId;
class GracefulQueueShutdownHelper;
class SequenceManagerImpl;
class TaskQueueImpl;
} // namespace internal
class TimeDomain;
// TODO(kraynov): Make TaskQueue to actually be an interface for TaskQueueImpl
// and stop using ref-counting because we're no longer tied to task runner
// lifecycle and there's no other need for ref-counting either.
// NOTE: When TaskQueue gets automatically deleted on zero ref-count,
// TaskQueueImpl gets gracefully shutdown. It means that it doesn't get
// unregistered immediately and might accept some last minute tasks until
// SequenceManager will unregister it at some point. It's done to ensure that
// task queue always gets unregistered on the main thread.
class BASE_EXPORT TaskQueue : public RefCountedThreadSafe<TaskQueue> {
public:
class Observer {
public:
virtual ~Observer() = default;
// Notify observer that the time at which this queue wants to run
// the next task has changed. |next_wakeup| can be in the past
// (e.g. TimeTicks() can be used to notify about immediate work).
// Can be called on any thread
// All methods but SetObserver, SetTimeDomain and GetTimeDomain can be
// called on |queue|.
//
// TODO(altimin): Make it Optional<TimeTicks> to tell
// observer about cancellations.
virtual void OnQueueNextWakeUpChanged(TaskQueue* queue,
TimeTicks next_wake_up) = 0;
};
// Prepare the task queue to get released.
// All tasks posted after this call will be discarded.
virtual void ShutdownTaskQueue();
// TODO(scheduler-dev): Could we define a more clear list of priorities?
// See https://crbug.com/847858.
enum QueuePriority {
// Queues with control priority will run before any other queue, and will
// explicitly starve other queues. Typically this should only be used for
// private queues which perform control operations.
kControlPriority = 0,
// The selector will prioritize highest over high, normal and low; and
// high over normal and low; and normal over low. However it will ensure
// neither of the lower priority queues can be completely starved by higher
// priority tasks. All three of these queues will always take priority over
// and can starve the best effort queue.
kHighestPriority = 1,
kHighPriority = 2,
// Queues with normal priority are the default.
kNormalPriority = 3,
kLowPriority = 4,
// Queues with best effort priority will only be run if all other queues are
// empty. They can be starved by the other queues.
kBestEffortPriority = 5,
// Must be the last entry.
kQueuePriorityCount = 6,
kFirstQueuePriority = kControlPriority,
};
// Can be called on any thread.
static const char* PriorityToString(QueuePriority priority);
// Options for constructing a TaskQueue.
struct Spec {
explicit Spec(const char* name)
: name(name),
should_monitor_quiescence(false),
time_domain(nullptr),
should_notify_observers(true) {}
Spec SetShouldMonitorQuiescence(bool should_monitor) {
should_monitor_quiescence = should_monitor;
return *this;
}
Spec SetShouldNotifyObservers(bool run_observers) {
should_notify_observers = run_observers;
return *this;
}
Spec SetTimeDomain(TimeDomain* domain) {
time_domain = domain;
return *this;
}
const char* name;
bool should_monitor_quiescence;
TimeDomain* time_domain;
bool should_notify_observers;
};
// Information about task execution.
//
// Wall-time related methods (start_time, end_time, wall_duration) can be
// called only when |has_wall_time()| is true.
// Thread-time related mehtods (start_thread_time, end_thread_time,
// thread_duration) can be called only when |has_thread_time()| is true.
//
// start_* should be called after RecordTaskStart.
// end_* and *_duration should be called after RecordTaskEnd.
class BASE_EXPORT TaskTiming {
public:
TaskTiming(bool has_wall_time, bool has_thread_time);
bool has_wall_time() const { return has_wall_time_; }
bool has_thread_time() const { return has_thread_time_; }
base::TimeTicks start_time() const {
DCHECK(has_wall_time());
return start_time_;
}
base::TimeTicks end_time() const {
DCHECK(has_wall_time());
return end_time_;
}
base::TimeDelta wall_duration() const {
DCHECK(has_wall_time());
return end_time_ - start_time_;
}
base::ThreadTicks start_thread_time() const {
DCHECK(has_thread_time());
return start_thread_time_;
}
base::ThreadTicks end_thread_time() const {
DCHECK(has_thread_time());
return end_thread_time_;
}
base::TimeDelta thread_duration() const {
DCHECK(has_thread_time());
return end_thread_time_ - start_thread_time_;
}
void RecordTaskStart(LazyNow* now);
void RecordTaskEnd(LazyNow* now);
// Protected for tests.
protected:
bool has_wall_time_;
bool has_thread_time_;
base::TimeTicks start_time_;
base::TimeTicks end_time_;
base::ThreadTicks start_thread_time_;
base::ThreadTicks end_thread_time_;
};
// An interface that lets the owner vote on whether or not the associated
// TaskQueue should be enabled.
class QueueEnabledVoter {
public:
QueueEnabledVoter() = default;
virtual ~QueueEnabledVoter() = default;
// Votes to enable or disable the associated TaskQueue. The TaskQueue will
// only be enabled if all the voters agree it should be enabled, or if there
// are no voters.
// NOTE this must be called on the thread the associated TaskQueue was
// created on.
virtual void SetQueueEnabled(bool enabled) = 0;
private:
DISALLOW_COPY_AND_ASSIGN(QueueEnabledVoter);
};
// Returns an interface that allows the caller to vote on whether or not this
// TaskQueue is enabled. The TaskQueue will be enabled if there are no voters
// or if all agree it should be enabled.
// NOTE this must be called on the thread this TaskQueue was created by.
std::unique_ptr<QueueEnabledVoter> CreateQueueEnabledVoter();
// NOTE this must be called on the thread this TaskQueue was created by.
bool IsQueueEnabled() const;
// Returns true if the queue is completely empty.
bool IsEmpty() const;
// Returns the number of pending tasks in the queue.
size_t GetNumberOfPendingTasks() const;
// Returns true if the queue has work that's ready to execute now.
// NOTE: this must be called on the thread this TaskQueue was created by.
bool HasTaskToRunImmediately() const;
// Returns requested run time of next scheduled wake-up for a delayed task
// which is not ready to run. If there are no such tasks (immediate tasks
// don't count) or the queue is disabled it returns nullopt.
// NOTE: this must be called on the thread this TaskQueue was created by.
Optional<TimeTicks> GetNextScheduledWakeUp();
// Can be called on any thread.
virtual const char* GetName() const;
// Set the priority of the queue to |priority|. NOTE this must be called on
// the thread this TaskQueue was created by.
void SetQueuePriority(QueuePriority priority);
// Returns the current queue priority.
QueuePriority GetQueuePriority() const;
// These functions can only be called on the same thread that the task queue
// manager executes its tasks on.
void AddTaskObserver(MessageLoop::TaskObserver* task_observer);
void RemoveTaskObserver(MessageLoop::TaskObserver* task_observer);
// Set the blame context which is entered and left while executing tasks from
// this task queue. |blame_context| must be null or outlive this task queue.
// Must be called on the thread this TaskQueue was created by.
void SetBlameContext(trace_event::BlameContext* blame_context);
// Removes the task queue from the previous TimeDomain and adds it to
// |domain|. This is a moderately expensive operation.
void SetTimeDomain(TimeDomain* domain);
// Returns the queue's current TimeDomain. Can be called from any thread.
TimeDomain* GetTimeDomain() const;
enum class InsertFencePosition {
kNow, // Tasks posted on the queue up till this point further may run.
// All further tasks are blocked.
kBeginningOfTime, // No tasks posted on this queue may run.
};
// Inserts a barrier into the task queue which prevents tasks with an enqueue
// order greater than the fence from running until either the fence has been
// removed or a subsequent fence has unblocked some tasks within the queue.
// Note: delayed tasks get their enqueue order set once their delay has
// expired, and non-delayed tasks get their enqueue order set when posted.
//
// Fences come in three flavours:
// - Regular (InsertFence(NOW)) - all tasks posted after this moment
// are blocked.
// - Fully blocking (InsertFence(kBeginningOfTime)) - all tasks including
// already posted are blocked.
// - Delayed (InsertFenceAt(timestamp)) - blocks all tasks posted after given
// point in time (must be in the future).
//
// Only one fence can be scheduled at a time. Inserting a new fence
// will automatically remove the previous one, regardless of fence type.
void InsertFence(InsertFencePosition position);
void InsertFenceAt(TimeTicks time);
// Removes any previously added fence and unblocks execution of any tasks
// blocked by it.
void RemoveFence();
// Returns true if the queue has a fence but it isn't necessarily blocking
// execution of tasks (it may be the case if tasks enqueue order hasn't
// reached the number set for a fence).
bool HasActiveFence();
// Returns true if the queue has a fence which is blocking execution of tasks.
bool BlockedByFence() const;
void SetObserver(Observer* observer);
// Create a task runner for this TaskQueue which will annotate all
// posted tasks with the given task type.
// May be called on any thread.
// NOTE: Task runners don't hold a reference to a TaskQueue, hence,
// it's required to retain that reference to prevent automatic graceful
// shutdown. Unique ownership of task queues will fix this issue soon.
scoped_refptr<SingleThreadTaskRunner> CreateTaskRunner(int task_type);
// Default task runner which doesn't annotate tasks with a task type.
scoped_refptr<SingleThreadTaskRunner> task_runner() const {
return default_task_runner_;
}
protected:
TaskQueue(std::unique_ptr<internal::TaskQueueImpl> impl,
const TaskQueue::Spec& spec);
virtual ~TaskQueue();
internal::TaskQueueImpl* GetTaskQueueImpl() const { return impl_.get(); }
private:
friend class RefCountedThreadSafe<TaskQueue>;
friend class internal::SequenceManagerImpl;
friend class internal::TaskQueueImpl;
bool IsOnMainThread() const;
Optional<MoveableAutoLock> AcquireImplReadLockIfNeeded() const;
// TaskQueue has ownership of an underlying implementation but in certain
// cases (e.g. detached frames) their lifetime may diverge.
// This method should be used to take away the impl for graceful shutdown.
// TaskQueue will disregard any calls or posting tasks thereafter.
std::unique_ptr<internal::TaskQueueImpl> TakeTaskQueueImpl();
// |impl_| can be written to on the main thread but can be read from
// any thread.
// |impl_lock_| must be acquired when writing to |impl_| or when accessing
// it from non-main thread. Reading from the main thread does not require
// a lock.
mutable Lock impl_lock_;
std::unique_ptr<internal::TaskQueueImpl> impl_;
const WeakPtr<internal::SequenceManagerImpl> sequence_manager_;
const scoped_refptr<internal::GracefulQueueShutdownHelper>
graceful_queue_shutdown_helper_;
scoped_refptr<internal::AssociatedThreadId> associated_thread_;
scoped_refptr<SingleThreadTaskRunner> default_task_runner_;
DISALLOW_COPY_AND_ASSIGN(TaskQueue);
};
} // namespace sequence_manager
} // namespace base
#endif // BASE_TASK_SEQUENCE_MANAGER_TASK_QUEUE_H_