summaryrefslogtreecommitdiffstats
path: root/devtools/server/docs/actor-hierarchy.md
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /devtools/server/docs/actor-hierarchy.md
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'devtools/server/docs/actor-hierarchy.md')
-rw-r--r--devtools/server/docs/actor-hierarchy.md129
1 files changed, 129 insertions, 0 deletions
diff --git a/devtools/server/docs/actor-hierarchy.md b/devtools/server/docs/actor-hierarchy.md
new file mode 100644
index 000000000..28ddd97c4
--- /dev/null
+++ b/devtools/server/docs/actor-hierarchy.md
@@ -0,0 +1,129 @@
+# How actors are organized
+
+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 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 particular context (document, tab, app,
+ | add-on, or worker).
+ | A good example is the preference actor.
+ |
+ \--> "TabActor" (or alike):
+ | 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.
+ |
+ \--> Tab-scoped actors:
+ Actors exposing one particular feature set, this time,
+ specific to a given context (document, tab, app, add-on, or
+ worker). Examples include the console and 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".
+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).
+ |
+ |-- 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 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, 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
+ (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.
+
+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, an add-on, or a worker.