mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Standardize remote

Browse source
This commit is contained in:
Jessica Lord 2015-08-28 22:17:35 -07:00
parent b759999272
commit 50736296a7
1 changed files with 48 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
docs/api/remote.md
View file

@ -1,29 +1,29 @@
# remote # remote
The `remote` module provides a simple way to do inter-process communication 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. 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 the renderer process would have to explicitly send inter-process messages
to the main process. With the `remote` module, users can invoke methods of to the main process. With the `remote` module, users can invoke methods of the
main process object without explicitly sending inter-process messages, main process object without explicitly sending inter-process messages, similar
similar to Java's to Java's [RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
[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 ```javascript
var remote = require('remote'); var remote = require('remote');
var BrowserWindow = remote.require('browser-window'); var BrowserWindow = remote.require('browser-window');
var win = new BrowserWindow({ width: 800, height: 600 }); var win = new BrowserWindow({ width: 800, height: 600 });
win.loadUrl('https://github.com'); win.loadUrl('https://github.com');
``` ```
Note: for the reverse (access renderer process from main process), you can use **Note**: for the reverse (access the renderer process from the main process),
[webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code). 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 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). 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 Instead, it created a `BrowserWindow` object in the main process and returned the
corresponding remote object in the renderer process, namely the `win` object. 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 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 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 in the main process will never be released. When the remote object has been
garbage collected, the corresponding object in the main process would be garbage collected, the corresponding object in the main process will be
dereferenced. dereferenced.
If the remote object is leaked in renderer process (e.g. stored in a map but never If the remote object is leaked in the renderer process (e.g. stored in a map but
freed), the corresponding object in the main process would also be leaked, never freed), the corresponding object in the main process will also be leaked,
so you should be very careful not to leak remote objects. so you should be very careful not to leak remote objects.
Primary value types like strings and numbers, however, are sent by copy. Primary value types like strings and numbers, however, are sent by copy.
## Passing callbacks to the main process ## Passing callbacks to the main process
Code in the main process can accept callbacks from the renderer - for instance the `remote` module - Code in the main process can accept callbacks from the renderer - for instance
but you should be extremely careful when using this feature. 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 First, in order to avoid deadlocks, the callbacks passed to the main process
are called asynchronously. You should not expect the main process to are called asynchronously. You should not expect the main process to
get the return value of the passed callbacks. 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 ```javascript
// main process mapNumbers.js // main process mapNumbers.js
@ -72,7 +73,9 @@ exports.withLocalCallback = function() {
return x + 1; return x + 1;
}); });
} }
```
```javascript
// renderer process // renderer process
var mapNumbers = require("remote").require("mapNumbers"); var mapNumbers = require("remote").require("mapNumbers");
@ -85,8 +88,9 @@ var withLocalCb = mapNumbers.withLocalCallback()
console.log(withRendererCb, withLocalCb) // [true, true, true], [2, 3, 4] 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, As you can see, the renderer callback's synchronous return value was not as
and didn't match the return value of an indentical callback that lives in the main process. 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 Second, the callbacks passed to the main process will persist until the
main process garbage-collects them. main process garbage-collects them.
@ -96,45 +100,52 @@ callback for the `close` event on a remote object:
```javascript ```javascript
var remote = require('remote'); var remote = require('remote');
remote.getCurrentWindow().on('close', function() { remote.getCurrentWindow().on('close', function() {
// blabla... // blabla...
}); });
``` ```
But remember the callback is referenced by the main process until you 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 explicitly uninstall it. If you do not, each time you reload your window the
be installed again, leaking one callback each restart. 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, To make things worse, since the context of previously installed callbacks have
when the `close` event was emitted exceptions would be raised in the main process. 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 To avoid this problem, ensure you clean up any references to renderer callbacks
process. This involves cleaning up event handlers, or ensuring the main process is explicitly told to deference passed to the main process. This involves cleaning up event handlers, or
callbacks that came from a renderer process that is exiting. 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 * `module` String
Returns the object returned by `require(module)` in the main process. 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 Returns the [`BrowserWindow`](browser-window.md) object to which this web page
belongs to. 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 * `name` String
Returns the global variable of `name` (e.g. `global[name]`) in the main Returns the global variable of `name` (e.g. `global[name]`) in the main
process. process.
## remote.process ### `remote.process`
Returns the `process` object in the main process. This is the same as 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.