Add m-esr52 at 52.6.0

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.