Standardize remote
This commit is contained in:
Jessica Lord
parent
b759999272
commit
50736296a7
1 changed files with 48 additions and 37 deletions
|
|
@ -1,29 +1,29 @@
|
|||
# remote
|
||||
|
||||
The `remote` module provides a simple way to do inter-process communication
|
||||
between the renderer process and the main process.
|
||||
between the renderer process (web page) and the main process.
|
||||
|
||||
In Electron, only GUI-unrelated modules are available in the renderer process.
|
||||
Without the `remote` module, users who wanted to call a main process API in
|
||||
Without the `remote` module, users who want to call a main process API in
|
||||
the renderer process would have to explicitly send inter-process messages
|
||||
to the main process. With the `remote` module, users can invoke methods of
|
||||
main process object without explicitly sending inter-process messages,
|
||||
similar to Java's
|
||||
[RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
|
||||
to the main process. With the `remote` module, users can invoke methods of the
|
||||
main process object without explicitly sending inter-process messages, similar
|
||||
to Java's [RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
|
||||
|
||||
An example of creating a browser window in renderer process:
|
||||
An example of creating a browser window from a renderer process:
|
||||
|
||||
```javascript
|
||||
var remote = require('remote');
|
||||
var BrowserWindow = remote.require('browser-window');
|
||||
|
||||
var win = new BrowserWindow({ width: 800, height: 600 });
|
||||
win.loadUrl('https://github.com');
|
||||
```
|
||||
|
||||
Note: for the reverse (access renderer process from main process), you can use
|
||||
[webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code).
|
||||
**Note**: for the reverse (access the renderer process from the main process),
|
||||
you can use [webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code).
|
||||
|
||||
## Remote objects
|
||||
## Remote Objects
|
||||
|
||||
Each object (including functions) returned by the `remote` module represents an
|
||||
object in the main process (we call it a remote object or remote function).
|
||||
|
|
@ -36,30 +36,31 @@ In the example above, both `BrowserWindow` and `win` were remote objects and
|
|||
Instead, it created a `BrowserWindow` object in the main process and returned the
|
||||
corresponding remote object in the renderer process, namely the `win` object.
|
||||
|
||||
## Lifetime of remote objects
|
||||
## Lifetime of Remote Objects
|
||||
|
||||
Electron makes sure that as long as the remote object in the renderer process
|
||||
lives (in other words, has not been garbage collected), the corresponding object
|
||||
in the main process would never be released. When the remote object has been
|
||||
garbage collected, the corresponding object in the main process would be
|
||||
in the main process will never be released. When the remote object has been
|
||||
garbage collected, the corresponding object in the main process will be
|
||||
dereferenced.
|
||||
|
||||
If the remote object is leaked in renderer process (e.g. stored in a map but never
|
||||
freed), the corresponding object in the main process would also be leaked,
|
||||
If the remote object is leaked in the renderer process (e.g. stored in a map but
|
||||
never freed), the corresponding object in the main process will also be leaked,
|
||||
so you should be very careful not to leak remote objects.
|
||||
|
||||
Primary value types like strings and numbers, however, are sent by copy.
|
||||
|
||||
## Passing callbacks to the main process
|
||||
|
||||
Code in the main process can accept callbacks from the renderer - for instance the `remote` module -
|
||||
but you should be extremely careful when using this feature.
|
||||
Code in the main process can accept callbacks from the renderer - for instance
|
||||
the `remote` module - but you should be extremely careful when using this feature.
|
||||
|
||||
First, in order to avoid deadlocks, the callbacks passed to the main process
|
||||
are called asynchronously. You should not expect the main process to
|
||||
get the return value of the passed callbacks.
|
||||
|
||||
For instance you can't use a function from the renderer process in a `Array.map` called in the main process:
|
||||
For instance you can't use a function from the renderer process in an
|
||||
`Array.map` called in the main process:
|
||||
|
||||
```javascript
|
||||
// main process mapNumbers.js
|
||||
|
|
@ -69,10 +70,12 @@ exports.withRendererCallback = function(mapper) {
|
|||
|
||||
exports.withLocalCallback = function() {
|
||||
return exports.mapNumbers(function(x) {
|
||||
return x + 1;
|
||||
return x + 1;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// renderer process
|
||||
var mapNumbers = require("remote").require("mapNumbers");
|
||||
|
||||
|
|
@ -85,8 +88,9 @@ var withLocalCb = mapNumbers.withLocalCallback()
|
|||
console.log(withRendererCb, withLocalCb) // [true, true, true], [2, 3, 4]
|
||||
```
|
||||
|
||||
As you can see, the renderer callback's synchronous return value was not as expected,
|
||||
and didn't match the return value of an indentical callback that lives in the main process.
|
||||
As you can see, the renderer callback's synchronous return value was not as
|
||||
expected, and didn't match the return value of an identical callback that lives
|
||||
in the main process.
|
||||
|
||||
Second, the callbacks passed to the main process will persist until the
|
||||
main process garbage-collects them.
|
||||
|
|
@ -96,45 +100,52 @@ callback for the `close` event on a remote object:
|
|||
|
||||
```javascript
|
||||
var remote = require('remote');
|
||||
|
||||
remote.getCurrentWindow().on('close', function() {
|
||||
// blabla...
|
||||
});
|
||||
```
|
||||
|
||||
But remember the callback is referenced by the main process until you
|
||||
explicitly uninstall it! If you do not, each time you reload your window the callback will
|
||||
be installed again, leaking one callback each restart.
|
||||
explicitly uninstall it. If you do not, each time you reload your window the
|
||||
callback will be installed again, leaking one callback for each restart.
|
||||
|
||||
To make things worse, since the context of previously installed callbacks have been released,
|
||||
when the `close` event was emitted exceptions would be raised in the main process.
|
||||
To make things worse, since the context of previously installed callbacks have
|
||||
been released, when the `close` event was emitted exceptions will be raised in
|
||||
the main process.
|
||||
|
||||
To avoid this problem, ensure you clean up any references to renderer callbacks passed to the main
|
||||
process. This involves cleaning up event handlers, or ensuring the main process is explicitly told to deference
|
||||
callbacks that came from a renderer process that is exiting.
|
||||
To avoid this problem, ensure you clean up any references to renderer callbacks
|
||||
passed to the main process. This involves cleaning up event handlers, or
|
||||
ensuring the main process is explicitly told to deference callbacks that came
|
||||
from a renderer process that is exiting.
|
||||
|
||||
## remote.require(module)
|
||||
## Methods
|
||||
|
||||
The `remote` module has the following methods:
|
||||
|
||||
### `remote.require(module)`
|
||||
|
||||
* `module` String
|
||||
|
||||
Returns the object returned by `require(module)` in the main process.
|
||||
|
||||
## remote.getCurrentWindow()
|
||||
### `remote.getCurrentWindow()`
|
||||
|
||||
Returns the [BrowserWindow](browser-window.md) object which this web page
|
||||
belongs to.
|
||||
Returns the [`BrowserWindow`](browser-window.md) object to which this web page
|
||||
belongs.
|
||||
|
||||
## remote.getCurrentWebContents()
|
||||
### `remote.getCurrentWebContents()`
|
||||
|
||||
Returns the WebContents object of this web page.
|
||||
Returns the [`WebContents`](web-contents.md) object of this web page.
|
||||
|
||||
## remote.getGlobal(name)
|
||||
### `remote.getGlobal(name)`
|
||||
|
||||
* `name` String
|
||||
|
||||
Returns the global variable of `name` (e.g. `global[name]`) in the main
|
||||
process.
|
||||
|
||||
## remote.process
|
||||
### `remote.process`
|
||||
|
||||
Returns the `process` object in the main process. This is the same as
|
||||
`remote.getGlobal('process')`, but gets cached.
|
||||
`remote.getGlobal('process')` but is cached.
|
||||
|
|
|
|||
Loading…
Reference in a new issue