--- a/devtools/server/docs/actor-hierarchy.md
+++ b/devtools/server/docs/actor-hierarchy.md
@@ -2,31 +2,32 @@
To start with, actors are living within /devtools/server/actors/ folder.
They are organized in a hierarchy for easier lifecycle/memory management:
once a parent is removed from the pool, its children are removed as well.
(See actor-registration.md for more information about how to implement one)
The overall hierarchy of actors looks like this:
- RootActor: First one, automatically instanciated when we start connecting.
- | Mostly meant to instanciate new actors.
+ RootActor: First one, automatically instantiated when we start connecting.
+ | Mostly meant to instantiate new actors.
|
|--> Global-scoped actors:
| Actors exposing features related to the main process,
- | that are not specific to any document/app/addon.
+ | that are not specific to any document/tab/app/add-on/worker.
| A good example is the preference actor.
|
\--> "TabActor" (or alike):
- | Actors meant to designate one document, tab, app, addon
- | and track its lifetime.
+ | Actors meant to designate one document, tab, app, add-on, or
+ | worker and track its lifetime. Generally, there is one of these
+ | for each are thing you can point a toolbox at.
|
\--> Tab-scoped actors:
Actors exposing one particular feature set, this time,
- specific to a given document/app/addon.
+ specific to a given document/tab/app/add-on/worker.
Like console, inspector actors.
These actors may extend this hierarchy by having their
own children, like LongStringActor, WalkerActor, etc.
## RootActor
The root actor is special. It is automatically created when a client connects.
It has a special `actorID` which is unique and is "root".
@@ -47,44 +48,53 @@ and returns its `actorID`. That's the ma
| that lives in the child process.
| Returned by "listTabs" or "getTab" requests.
| |
| \-> ContentActor (childtab.js)
| Targets tabs living out-of-process (e10s) or apps (on firefox OS).
| Returned by "connect" on RemoteBrowserActor (for tabs) or
| "getAppActor" on the Webapps actor (for apps).
|
+ |-- WorkerActor (worker.js)
+ | Targets a worker (applies to various kinds like web worker, service
+ | worker, etc.).
+ | Returned by "listWorkers" request to the root actor to get all workers.
+ | Returned by "listWorkers" request to a BrowserTabActor to get workers for
+ | a specific tab.
+ | Returned by "listWorkers" request to a ChildProcessActor to get workers
+ | for the chrome of the child process.
+ |
|-- ChromeActor (chrome.js)
| Targets all resources in the parent process of firefox
| (chrome documents, JSM, JS XPCOM, etc.).
| Returned by "getProcess" request without any argument.
|
|-- ChildProcessActor (child-process.js)
| Targets the chrome of the child process (e10s).
| Returned by "getProcess" request with a id argument,
| matching the targeted process.
|
\-- BrowserAddonActor (addon.js)
- Targets the javascript of addons.
+ Targets the javascript of add-ons.
Returned by "listAddons" request.
## "TabActor"
Those are the actors exposed by the root actors which are meant to track the
-lifetime of a given context: tab, app, process or addon. It also allows
-to fetch the tab-scoped actors connected to this context. Actors like console,
-inspector, thread (for debugger), styleinspector, etc. Most of them inherit
-from TabActor (defined in webbrowser.js) which is document centric.
-It automatically tracks the lifetime of the targeted document, but it also
-tracks its iframes and allows switching the context to one of its iframes.
-For historical reasons, these actors also handle creating the ThreadActor,
-used to manage breakpoints in the debugger. All the other tab-scoped actors are
-created when we access the TabActor's grip. We return the tab-scoped actors
-`actorID` in it. Actors inheriting from TabActor expose `attach`/`detach`
-requests, that allows to start/stop the ThreadActor.
+lifetime of a given context: tab, app, process, add-on, or worker. It also
+allows to fetch the tab-scoped actors connected to this context. Actors like
+console, inspector, thread (for debugger), styleinspector, etc. Most of them
+inherit from TabActor (defined in webbrowser.js) which is document centric. It
+automatically tracks the lifetime of the targeted document, but it also tracks
+its iframes and allows switching the context to one of its iframes. For
+historical reasons, these actors also handle creating the ThreadActor, used to
+manage breakpoints in the debugger. All the other tab-scoped actors are created
+when we access the TabActor's grip. We return the tab-scoped actors `actorID` in
+it. Actors inheriting from TabActor expose `attach`/`detach` requests, that
+allows to start/stop the ThreadActor.
The tab-scoped actors expect to find the following properties on the "TabActor":
- threadActor:
ThreadActor instance for the given context,
only defined once `attach` request is called, or on construction.
- isRootActor: (historical name)
Always false, except on ChromeActor.
Despite the attribute name, it is being used to accept all resources
@@ -103,16 +113,16 @@ attributes and events:
List of all document globals including the main window object and all iframes.
- docShell:
DocShell reference for the targeted context.
- docShells:
List of all docshells for the targeted document and all its iframes.
- chromeEventHandler:
The chrome event handler for the current context. Allows to listen to events
that can be missing/cancelled on this document itself.
+
See TabActor documentation for events definition.
-
## Tab-scoped actors
-Each of these actors focuses on providing one particular feature set, specific to one context,
-that can be a web page, an app, a top level firefox window, a process or an addon resource.
-
+Each of these actors focuses on providing one particular feature set, specific
+to one context, that can be a web page, an app, a top level firefox window, a
+process, an add-on, or a worker.