content/browser/scheduler/responsiveness/README

The classes in this folder estimate the responsiveness of Chrome by measuring
execution duration of individual work items on the UI and IO threads of the
browser process.

There are four types of work items executed on the UI and IO threads.
1) Both the UI and IO threads can have tasks posted to them via the Task
   Scheduler [e.g. via content::Get(UI|IO)ThreadTaskRunner()].
2) The UI thread processes native events directly from the message loop
   [NSEvents on macOS, MSGs on Windows, InputEvents on Android, XEvents on
   X11, etc.]
3) The IO thread's message pump processes IPCs by listening on data channels
   [e.g. fds] and waking up on available data.
4) The UI thread's message loop may process other platform-specific sources.
   This is currently not monitored because there is no consistent way to
   instrument. If individual sources prove to be a source of non-responsiveness,
   they will need to be addressed on a case-by-case basis.

The classes in this folder do not monitor the queuing time of work items. The
work to monitor this is tracked in https://crbug.com/1029137. This is how the
queuing time of each work item type could be monitored:

1) Compute the delta between TimeTicks::Now() when the task starts execution and
   |PendingTask::queue_time|. The queuing time of low priority tasks should
   probably be ignored, since it can be long by design.
2) All native events have a creation timestamp which could be compared to
   TimeTicks::Now() when the event starts execution. However, we have evidence
   on Windows, macOS and Linux that the timestamp on native events is not
   reliable. See https://crbug.com/859155#c39.
3) There's no good solution here, since the current wire format for IPCs does
   not record the time at which the IPC was written to the data channel. The
   time between reading from the data channel and finishing execution is
   typically small, as heavy tasks are supposed to be dispatched off the IO
   thread.
4) As explained above, individual sources should be investigated on a
   case-by-case basis if they prove to be a source of non-responsiveness.

Design doc: https://docs.google.com/document/d/1vDSGFvJblh7yJ3U3RVB_7qZLubyfTbQdQjuN1GoUNkc/edit