unplugged-system/external/cronet/base/task/sequence_manager

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.