Confirmed users, Bureaucrats and Sysops emeriti
969
edits
Quantum/DOM: Difference between revisions
Jump to navigation
Jump to search
Move some of the text into sections where it better belongs
(Request clarity in the TabGroup definition) |
(Move some of the text into sections where it better belongs) |
||
| Line 13: | Line 13: | ||
A <b>DocGroup</b> is the collection of documents from a given TabGroup that share the same eTLD+1 part of their origins. So if a TabGroup contains tabs with documents {x.a.com, y.a.com, x.b.com, y.b.com}, then these documents will belong to two DocGroups: {x.a.com, y.a.com}, {x.b.com, y.b.com}. DocGroups are essentially a refinement of TabGroups to account for the fact that only same-origin documents can synchronously communicate. (The eTLD+1 part is to account for pages changing their origin by modifying document.domain.) So a runnable from one DocGroup can run while a runnable from a different DocGroup is paused. | A <b>DocGroup</b> is the collection of documents from a given TabGroup that share the same eTLD+1 part of their origins. So if a TabGroup contains tabs with documents {x.a.com, y.a.com, x.b.com, y.b.com}, then these documents will belong to two DocGroups: {x.a.com, y.a.com}, {x.b.com, y.b.com}. DocGroups are essentially a refinement of TabGroups to account for the fact that only same-origin documents can synchronously communicate. (The eTLD+1 part is to account for pages changing their origin by modifying document.domain.) So a runnable from one DocGroup can run while a runnable from a different DocGroup is paused. | ||
The <b>SystemGroup</b> is a group for runnables that do not affect web content. | |||
= Labeling = | |||
A major task for the Quantum DOM project is to label runnables with | A major task for the Quantum DOM project is to label runnables with a DocGroup, TabGroup, or the SystemGroup. Using a DocGroup is preferred over using a TabGroup since TabGroup is less specific, but for some runnables the best we can do is give it a TabGroup. Runnables that do not affect web content at all should be labeled using the <b>SystemGroup</b>. However, only use the system group if you are absolutely sure that the runnable will not run any content JS code or have any affect on content DOM or layout. | ||
In addition to labeling runnables with a group, it is preferred to name them at the same time to aid in debugging. | |||
You can help by taking one of the unowned bugs to label runnables from the following list: | |||
<bugzilla> | <bugzilla> | ||
| Line 31: | Line 31: | ||
} | } | ||
</bugzilla> | </bugzilla> | ||
== Obtaining the correct group == | |||
Given a document, you can find its DocGroup via nsIDocument::GetDocGroup. | |||
Given an inner or outer window, you can find its TabGroup and DocGroup via nsPIDOMWindow::{TabGroup,GetDocGroup}. These methods should only be called on the main thread. | |||
== Dispatching == | == Dispatching == | ||
Based on how it is dispatched, there are multiple ways to label a runnable. The simplest way is to provide the DocGroup or TabGroup when dispatching the runnable. | |||
Both the TabGroup and DocGroup classes have Dispatch methods to dispatch runnables. Runnables dispatched in this way will always run on the main thread. You can call Dispatch from any thread. Both TabGroup and DocGroup are threadsafe refcounted. The Dispatch method requires you to name the runnable and provide a "task category". For now, these are for debugging purposes, but the category may be used for scheduling purposes later on. | Both the TabGroup and DocGroup classes have Dispatch methods to dispatch runnables. Runnables dispatched in this way will always run on the main thread. You can call Dispatch from any thread. Both TabGroup and DocGroup are threadsafe refcounted. The Dispatch method requires you to name the runnable and provide a "task category". For now, these are for debugging purposes, but the category may be used for scheduling purposes later on. | ||