2015-06-30 11:15:00 +00:00
|
|
|
# How actors are organized
|
|
|
|
|
2015-09-21 17:07:31 +00:00
|
|
|
To start with, actors are living within /devtools/server/actors/ folder.
|
2015-06-30 11:15:00 +00:00
|
|
|
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:
|
|
|
|
|
2016-02-09 23:53:30 +00:00
|
|
|
RootActor: First one, automatically instantiated when we start connecting.
|
|
|
|
| Mostly meant to instantiate new actors.
|
2015-06-30 11:15:00 +00:00
|
|
|
|
|
|
|
|
|--> Global-scoped actors:
|
|
|
|
| Actors exposing features related to the main process,
|
2016-02-09 23:53:30 +00:00
|
|
|
| that are not specific to any particular context (document, tab, app,
|
|
|
|
| add-on, or worker).
|
2015-06-30 11:15:00 +00:00
|
|
|
| A good example is the preference actor.
|
|
|
|
|
|
|
|
|
\--> "TabActor" (or alike):
|
2016-02-09 23:53:30 +00:00
|
|
|
| Actors meant to designate one context (document, tab, app,
|
|
|
|
| add-on, or worker) and track its lifetime. Generally, there is
|
|
|
|
| one of these for each thing you can point a toolbox at.
|
2015-06-30 11:15:00 +00:00
|
|
|
|
|
|
|
|
\--> Tab-scoped actors:
|
|
|
|
Actors exposing one particular feature set, this time,
|
2016-02-09 23:53:30 +00:00
|
|
|
specific to a given context (document, tab, app, add-on, or
|
|
|
|
worker). Examples include the console and inspector actors.
|
2015-06-30 11:15:00 +00:00
|
|
|
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".
|
|
|
|
All other actors have an `actorID` which is computed dynamically,
|
|
|
|
so that you need to ask an existing actor to create an Actor
|
|
|
|
and returns its `actorID`. That's the main role of RootActor.
|
|
|
|
|
|
|
|
RootActor (root.js)
|
|
|
|
|
|
|
|
|
|-- BrowserTabActor (webbrowser.js)
|
|
|
|
| Targets tabs living in the parent process when e10s (multiprocess)
|
|
|
|
| is turned off for this tab.
|
|
|
|
| Returned by "listTabs" or "getTab" requests.
|
|
|
|
|
|
|
|
|
|-- RemoteBrowserActor (webbrowser.js)
|
|
|
|
| Targets tabs living in the child process when e10s (multiprocess) is
|
|
|
|
| turned on for this tab. Note that this is just a proxy for ContentActor,
|
|
|
|
| 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).
|
|
|
|
|
|
2016-02-09 23:53:30 +00:00
|
|
|
|-- 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.
|
|
|
|
|
|
2015-06-30 11:15:00 +00:00
|
|
|
|-- 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)
|
2016-02-09 23:53:30 +00:00
|
|
|
Targets the javascript of add-ons.
|
2015-06-30 11:15:00 +00:00
|
|
|
Returned by "listAddons" request.
|
|
|
|
|
|
|
|
## "TabActor"
|
|
|
|
|
|
|
|
Those are the actors exposed by the root actors which are meant to track the
|
2016-02-09 23:53:30 +00:00
|
|
|
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.
|
2015-06-30 11:15:00 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
(like chrome one) instead of limiting only to content resources.
|
|
|
|
- makeDebugger:
|
|
|
|
Helper function used to create Debugger object for the targeted context.
|
|
|
|
(See actors/utils/make-debugger.js for more info)
|
|
|
|
|
|
|
|
In addition to this, the actors inheriting from TabActor, expose many other
|
|
|
|
attributes and events:
|
|
|
|
- window:
|
|
|
|
Reference to the window global object currently targeted.
|
|
|
|
It can change over time if we switch context to an iframe, so it
|
|
|
|
shouldn't be stored in a variable, but always retrieved from the actor.
|
|
|
|
- windows:
|
|
|
|
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.
|
|
|
|
|
2016-02-09 23:53:30 +00:00
|
|
|
See TabActor documentation for events definition.
|
2015-06-30 11:15:00 +00:00
|
|
|
|
|
|
|
## Tab-scoped actors
|
|
|
|
|
2016-02-09 23:53:30 +00:00
|
|
|
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.
|