diff options
Diffstat (limited to 'tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md')
| -rw-r--r-- | tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md | 218 |
1 files changed, 0 insertions, 218 deletions
diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md b/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md deleted file mode 100644 index 3e2f047..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md +++ /dev/null @@ -1,218 +0,0 @@ -<span class="aside"> -For a high-level overview of out-of-process add-ons, see the -[Out-of-Process Add-ons][] internals guide. -</span> - -The `e10s` module allows add-ons to execute in a separate process from Firefox -itself. - -## Adapters ## - -As explained in the [Out-of-Process Add-ons][] internals guide, an *e10s -adapter* is the primary mechanism through which chrome functionality is exposed -to add-on processes. It is a single piece of code evaluated *twice*—once -in each process—and typically has the following form: - - if (this.chrome) { - /* We're being evaluated in the add-on process. Export the - * module's API, proxying all calls to the chrome process - * as necessary. */ - } else exports.register = function register(addon) { - /* We're being evaluated in the chrome process. - * Set up chrome process listeners to communicate with - * the given add-on process. */ - }; - -In the above code, the `chrome` global is only visible to this code when it is -executed in the add-on process. It is an instance of `ChromeProcess`. - -The `register()` function, on the other hand, is only defined and called in the -chrome process, and the `addon` argument passed to it is an instance of -`AddonProcess`. - -`ChromeProcess` and `AddonProcess` instances come in pairs, and represent -opposite sides of an inter-process communication mechanism. - - [Out-of-Process Add-ons]: dev-guide/module-development/e10s.html - -## Events ## - -Chrome and add-on processes can asynchronously send arbitrary events to each -other. The <code>[EventEmitter][]</code> interface has been overloaded to make -handling these events simple and intuitive. For instance, here's a trivial e10s -adapter that uses events: - - if (this.chrome) { - exports.sendFoo = function(x) { - chrome.send('foo', x); - }; - } else exports.register = function register(addon) { - addon.on('foo', function(type, x) { - console.log("foo called with argument", x); - }); - }; - - [EventEmitter]: packages/api-utils/docs/events.html - -## Remote Function Calls ## - -The add-on process can synchronously call a function on the chrome process, but -not vice versa. Here's a trivial example of an e10s adapter using this -mechanism: - - if (this.chrome) { - exports.bar = function(x) { - return chrome.call('bar', x); - }; - } else exports.register = function register(addon) { - addon.registerCall('bar', function(name, x) { - return x * 3; - }); - }; - -## Arguments ## - -When sending events or calling functions in another process, the chrome and -add-on processes are allowed to send JSON-serializable arguments. Additionally, -they can send a special type of object called a *handle*. See the -[MDN Handle Documentation][] for more information on these. - -Here's a simple example of a handle being used to remember a callback function -on the add-on side: - - if (this.chrome) { - exports.baz = function(callback) { - var handle = chrome.createHandle(); - handle.callback = callback; - chrome.send('baz', handle); - }; - chrome.on('bazCallback', function(name, handle) { - try { handle.callback(); } except (e) { console.exception(e); } - handle.invalidate(); - }); - } else exports.register = function register(addon) { - addon.on('baz', function(name, handle) { - require('timer').setTimeout(function() { - addon.send('bazCallback', handle); - }, 1000); - }); - }; - - [MDN Handle Documentation]: https://developer.mozilla.org/en/Jetpack_Processes#Handles - -<api name="ChromeProcess"> -@class - In an add-on process, this represents the parent chrome process. This class is - a singleton and has no constructor. It is automatically injected into the - global scope of all `-e10s-adapter` modules as the `chrome` object. - -<api name="on"> -@method - Registers an event listener with the chrome process. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. Its first argument is always - `type`, and additional arguments vary depending on the event's originating - `addon.send()` call in the chrome process. -</api> - -<api name="removeListener"> -@method - Removes an event listener from the chrome process. -@param type {string} - The type of event for which `listener` was registered. -@param listener {function} - The listener function that was registered. -</api> - -<api name="send"> -@method - Sends an event asynchronously to the chrome process. Any additional arguments - after `type` are passed as arguments to event listeners in the chrome process. -@param type {string} - The type of event to send. -</api> - -<api name="call"> -@method - Synchronously calls a remote function in the chrome process and returns its - result. Any additional arguments after `name` are passed as arguments to the - function in the chrome process. -@param name {string} - The name of the function to call. -</api> - -<api name="createHandle"> -@method - Creates a [handle][] object, which can be passed to the chrome process via - `send()` or `call()`. - - [handle]: https://developer.mozilla.org/en/Jetpack_Processes#Handles -</api> - -</api> - -<api name="AddonProcess"> -@class - In the chrome process, this represents a child add-on process. - -<api name="AddonProcess"> -@constructor - Creates a new add-on process. - -@param options {object} - An optional object with the following keys, all of which are optional: - - @prop [console] {object} - An object whose interface corresponds to that of the `console` global. All - logging messages to the `console` object of the addon will be redirected to - this object. If this object isn't provided, then the global `console` object - of the chrome process will be used. -</api> - -<api name="destroy"> -@method - Terminates the add-on process. -</api> - -<api name="on"> -@method - Registers an event listener with the add-on process. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. Its first argument is always - `type`, and additional arguments vary depending on the event's originating - `chrome.send()` call in the add-on process. -</api> - -<api name="registerCall"> -@method - Registers a synchronous call handler with the add-on process. -@param name {string} - The name of the function. -@param handler {function} - The call handler. Its first argument is always `name`, and additional - arguments vary depending on the call's originating `chrome.call()` invocation - in the add-on process. The handler's return value is also passed back to the - original caller in the add-on process. -</api> - -<api name="send"> -@method - Sends an event asynchronously to the add-on process. Any additional arguments - after `type` are passed as arguments to event listeners in the add-on process. -@param type {string} - The type of event to send. -</api> - -<api name="createHandle"> -@method - Creates a [handle][] object, which can be passed to the add-on process via - `send()`. - - [handle]: https://developer.mozilla.org/en/Jetpack_Processes#Handles -</api> - -</api> |