69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
|
# 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`. `TaskQueue`s use distinct primitive FIFO queues, called
|
||
|
|
`WorkQueue`s, 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 `TaskQueue`s. 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
|
||
|
|
`TaskQueue`s whose wake-up can be resolved. This lets each `TaskQueue`s 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.
|