hmz007
README.md
What is this
This file documents high level parts of the sequence manager.
The sequence manager provides a set of prioritized FIFO task queues, which allows funneling multiple sequences of immediate and delayed tasks on a single underlying sequence.
Work Queue and Task selection
Both immediate tasks and delayed tasks are posted to a TaskQueue via an
associated TaskRunner. TaskQueues use distinct primitive FIFO queues, called
WorkQueues, to manage immediate tasks and delayed tasks. Tasks eventually end
up in their assigned WorkQueue which is made directly visible to
SequenceManager through TaskQueueSelector.
SequenceManagerImpl::SelectNextTask() uses
TaskQueueSelector::SelectWorkQueueToService() to select the next work queue
based on various policy e.g. priority, from which 1 task is popped at a time.
Journey of a Task
Task queues have a mechanism to allow efficient cross-thread posting with the
use of 2 work queues, immediate_incoming_queue which is used when posting, and
immediate_work_queue used to pop tasks from. An immediate task posted from the
main thread is pushed on immediate_incoming_queue in
TaskQueueImpl::PostImmediateTaskImpl(). If the work queue was empty,
SequenceManager is notified and the TaskQueue is registered to do
ReloadEmptyImmediateWorkQueue() before SequenceManager selects a task, which
moves tasks from immediate_incoming_queue to immediate_work_queue in batch
for all registered TaskQueues. The tasks then follow the regular work queue
selection mechanism.
Journey of a WakeUp
A WakeUp represents a time at which a delayed task wants to run.
Each TaskQueueImpl maintains its own next wake-up as
main_thread_only().scheduled_wake_up, associated with the earliest pending
delayed task. It communicates its wake up to the WakeUpQueue via
WakeUpQueue::SetNextWakeUpForQueue(). The WakeUpQueue is responsible for
determining the single next wake up time for the thread. This is accessed from
SequenceManagerImpl and may determine the next run time if there's no
immediate work, which ultimately gets passed to the MessagePump, typically via
MessagePump::Delegate::NextWorkInfo (returned by
ThreadControllerWithMessagePumpImpl::DoWork()) or by
MessagePump::ScheduleDelayedWork() (on rare occasions where the next WakeUp is
scheduled on the main thread from outside a DoWork()). When a delayed run time
associated with a wake-up is reached, WakeUpQueue is notified through
WakeUpQueue::MoveReadyDelayedTasksToWorkQueues() and in turn notifies all
TaskQueues whose wake-up can be resolved. This lets each TaskQueues process
ripe delayed tasks.
Journey of a delayed Task
A delayed Task posted cross-thread generates an immediate Task to run
TaskQueueImpl::ScheduleDelayedWorkTask() which eventually calls
TaskQueueImpl::PushOntoDelayedIncomingQueueFromMainThread(), so that it can be
enqueued on the main thread. A delayed Task posted from the main thread skips
this step and calls
TaskQueueImpl::PushOntoDelayedIncomingQueueFromMainThread() directly. The Task
is then pushed on main_thread_only().delayed_incoming_queue and possibly
updates the next task queue wake-up. Once the delayed run time is reached,
possibly because the wake-up is resolved, the delayed task is moved to
main_thread_only().delayed_work_queue and follows the regular work queue
selection mechanism.
TimeDomain and TickClock
SequenceManager and related classes use a common TickClock that can be
injected by specifying a TimeDomain. A TimeDomain is a specialisation of
TickClock that gets notified when the MessagePump is about to go idle via
TimeDomain::MaybeFastForwardToWakeUp(), and can use the signal to fast forward
in time. This is used in TaskEnvironment to support MOCK_TIME, and in
devtools to support virtual time.