1# How actors are organized 2 3To start with, actors are living within /devtools/server/actors/ folder. 4They are organized in a hierarchy for easier lifecycle/memory management: 5once a parent is removed from the pool, its children are removed as well. 6(See actor-registration.md for more information about how to implement one) 7 8The overall hierarchy of actors looks like this: 9 10 RootActor: First one, automatically instantiated when we start connecting. 11 | Mostly meant to instantiate new actors. 12 | 13 |--> Global-scoped actors: 14 | Actors exposing features related to the main process, 15 | that are not specific to any particular context (document, tab, app, 16 | add-on, or worker). 17 | A good example is the preference actor. 18 | 19 \--> "TabActor" (or alike): 20 | Actors meant to designate one context (document, tab, app, 21 | add-on, or worker) and track its lifetime. Generally, there is 22 | one of these for each thing you can point a toolbox at. 23 | 24 \--> Tab-scoped actors: 25 Actors exposing one particular feature set, this time, 26 specific to a given context (document, tab, app, add-on, or 27 worker). Examples include the console and inspector actors. 28 These actors may extend this hierarchy by having their 29 own children, like LongStringActor, WalkerActor, etc. 30 31## RootActor 32 33The root actor is special. It is automatically created when a client connects. 34It has a special `actorID` which is unique and is "root". 35All other actors have an `actorID` which is computed dynamically, 36so that you need to ask an existing actor to create an Actor 37and returns its `actorID`. That's the main role of RootActor. 38 39 RootActor (root.js) 40 | 41 |-- BrowserTabActor (webbrowser.js) 42 | Targets tabs living in the parent process when e10s (multiprocess) 43 | is turned off for this tab. 44 | Returned by "listTabs" or "getTab" requests. 45 | 46 |-- RemoteBrowserActor (webbrowser.js) 47 | Targets tabs living in the child process when e10s (multiprocess) is 48 | turned on for this tab. Note that this is just a proxy for ContentActor, 49 | that lives in the child process. 50 | Returned by "listTabs" or "getTab" requests. 51 | | 52 | \-> ContentActor (childtab.js) 53 | Targets tabs living out-of-process (e10s) or apps (on firefox OS). 54 | Returned by "connect" on RemoteBrowserActor (for tabs) or 55 | "getAppActor" on the Webapps actor (for apps). 56 | 57 |-- WorkerActor (worker.js) 58 | Targets a worker (applies to various kinds like web worker, service 59 | worker, etc.). 60 | Returned by "listWorkers" request to the root actor to get all workers. 61 | Returned by "listWorkers" request to a BrowserTabActor to get workers for 62 | a specific tab. 63 | Returned by "listWorkers" request to a ChildProcessActor to get workers 64 | for the chrome of the child process. 65 | 66 |-- ChromeActor (chrome.js) 67 | Targets all resources in the parent process of firefox 68 | (chrome documents, JSM, JS XPCOM, etc.). 69 | Returned by "getProcess" request without any argument. 70 | 71 |-- ChildProcessActor (child-process.js) 72 | Targets the chrome of the child process (e10s). 73 | Returned by "getProcess" request with a id argument, 74 | matching the targeted process. 75 | 76 \-- BrowserAddonActor (addon.js) 77 Targets the javascript of add-ons. 78 Returned by "listAddons" request. 79 80## "TabActor" 81 82Those are the actors exposed by the root actors which are meant to track the 83lifetime of a given context: tab, app, process, add-on, or worker. It also 84allows to fetch the tab-scoped actors connected to this context. Actors like 85console, inspector, thread (for debugger), styleinspector, etc. Most of them 86inherit from TabActor (defined in webbrowser.js) which is document centric. It 87automatically tracks the lifetime of the targeted document, but it also tracks 88its iframes and allows switching the context to one of its iframes. For 89historical reasons, these actors also handle creating the ThreadActor, used to 90manage breakpoints in the debugger. All the other tab-scoped actors are created 91when we access the TabActor's grip. We return the tab-scoped actors `actorID` in 92it. Actors inheriting from TabActor expose `attach`/`detach` requests, that 93allows to start/stop the ThreadActor. 94 95The tab-scoped actors expect to find the following properties on the "TabActor": 96 - threadActor: 97 ThreadActor instance for the given context, 98 only defined once `attach` request is called, or on construction. 99 - isRootActor: (historical name) 100 Always false, except on ChromeActor. 101 Despite the attribute name, it is being used to accept all resources 102 (like chrome one) instead of limiting only to content resources. 103 - makeDebugger: 104 Helper function used to create Debugger object for the targeted context. 105 (See actors/utils/make-debugger.js for more info) 106 107In addition to this, the actors inheriting from TabActor, expose many other 108attributes and events: 109 - window: 110 Reference to the window global object currently targeted. 111 It can change over time if we switch context to an iframe, so it 112 shouldn't be stored in a variable, but always retrieved from the actor. 113 - windows: 114 List of all document globals including the main window object and all iframes. 115 - docShell: 116 DocShell reference for the targeted context. 117 - docShells: 118 List of all docshells for the targeted document and all its iframes. 119 - chromeEventHandler: 120 The chrome event handler for the current context. Allows to listen to events 121 that can be missing/cancelled on this document itself. 122 123See TabActor documentation for events definition. 124 125## Tab-scoped actors 126 127Each of these actors focuses on providing one particular feature set, specific 128to one context, that can be a web page, an app, a top level firefox window, a 129process, an add-on, or a worker. 130