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

Doc: grammar/content fixes in the remote module

Browse source 
Mostly minor grammatical issues, but also some content that seems to be incorrect based on the surrounding descriptions and example code.
This commit is contained in:
Greg Mefford 2014-05-09 23:51:25 -04:00
parent d9e1861aff
commit 74c517d186
1 changed files with 50 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

101
docs/api/remote.md
View file

@ -1,14 +1,14 @@
# 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 renderer process and browser process. between the renderer process and the browser process.
In atom-shell, all GUI related modules are only available in the browser In atom-shell, only GUI-related modules are available in the renderer process.
process, if users want to call an browser side API in the renderer process Without the `remote` module, users who wanted to call a browser-side API in
, they usually would have to explicitly send inter-process messages to the the renderer process would have to explicitly send inter-process messages
browser process. But with the `remote` module, users can invoke methods of to the browser process. With the `remote` module, users can invoke methods of
objects living in browser process without sending inter-process messages browser-side object without explicitly sending inter-process messages,
directly, like Java's similar 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 in renderer process:
@ -22,47 +22,46 @@ win.loadUrl('https://github.com');
## Remote objects ## Remote objects
Each object (including function) returned by `remote` module represents an Each object (including functions) returned by the `remote` module represents an
object in browser process (we call it remote object or remote function), when object in the browser process (we call it a remote object or remote function).
you invoke methods of a remote object, or call a remote function, or even create When you invoke methods of a remote object, call a remote function, or create
a new object with the remote constructor (function), you are actually sending a new object with the remote constructor (function), you are actually sending
synchronous inter-process messages. synchronous inter-process messages.
In the example above, both `BrowserWindow` and `win` were remote objects. And In the example above, both `BrowserWindow` and `win` were remote objects and
`new BrowserWindow` didn't create a `BrowserWindow` object in renderer process, `new BrowserWindow` didn't create a `BrowserWindow` object in the renderer process.
instead it created a `BrowserWindow` object in browser process, and returned the Instead, it created a `BrowserWindow` object in the browser process and returned the
corresponding remote object in 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
Atom-shell makes sure that as long as the remote object in renderer process Atom-shell 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 browser process would never be released. And when the remote object has been in the browser process would never be released. When the remote object has been
garbage collected, the corresponding object in browser process would be garbage collected, the corresponding object in the browser process would be
dereferenced. dereferenced.
But it also means that, if the remote object is leaked in renderer process, like If the remote object is leaked in renderer process (e.g. stored in a map but never
being stored in a map but never got freed, the corresponding object in browser freed), the corresponding object in the browser process would also be leaked,
process would also be leaked too. So you should be very careful not to leak so you should be very careful not to leak remote objects.
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 browser ## Passing callbacks to browser
Some APIs in browser process accepts callbacks, and it would be attempting to Some APIs in the browser process accept callbacks, and it would be attempting to
pass callbacks when calling a remote function. Yes `remote` module does support pass callbacks when calling a remote function. The `remote` module does support
doing this, but you should also be extremely careful on this. doing this, but you should also be extremely careful with this.
First, in order to avoid dead locks, the callbacks passed to browser process First, in order to avoid deadlocks, the callbacks passed to the browser process
would be called asynchronously, so you should not expect the browser process to are called asynchronously, so you should not expect the browser process to
get the return value of the passed callbacks. get the return value of the passed callbacks.
Second, the callbacks passed to browser process would not get released Second, the callbacks passed to the browser process will not get released
automatically after they were called, instead they would persistent until the automatically after they are called. Instead, they will persistent until the
browser process garbage collected them. browser process garbage-collects them.
For example, following code seems innocent at first glance, It installed a For example, the following code seems innocent at first glance. It installs a
callback for the `close` event on a remote object: callback for the `close` event on a remote object:
```javascript ```javascript
@ -72,28 +71,28 @@ remote.getCurrentWindow().on('close', function() {
}); });
``` ```
But the callback would be stored in the browser process persistently until you The problem is that the callback would be stored in the browser process until you
explicitly uninstall it! So each time you reload your window, the callback would explicitly uninstall it! So each time you reload your window, the callback would
be installed for once and previous callbacks were just leak. To make things be installed again and previous callbacks would just leak. To make things
worse, since the context of previously installed callbacks have been released, worse, since the context of previously installed callbacks have been released,
when `close` event was emitted exceptions would happen in browser process. when the `close` event was emitted, exceptions would be raised in the browser process.
So generally, unless you are clear what you are doing, you should always avoid Generally, unless you are clear what you are doing, you should always avoid
passing callbacks to browser process. passing callbacks to the browser process.
## Remote buffer ## Remote buffer
An instance of node's `Buffer` is an object, so when you got a `Buffer` from An instance of node's `Buffer` is an object, so when you get a `Buffer` from
browser process, what you got was indeed a remote object (let's call it remote the browser process, what you get is indeed a remote object (let's call it remote
buffer), and everything would just follow the rules of remote objects. buffer), and everything would just follow the rules of remote objects.
However you should remember that though a remote buffer behaves like the real However you should remember that although a remote buffer behaves like the real
`Buffer`, it's not a `Buffer` at all. If you pass a remote buffer to node APIs `Buffer`, it's not a `Buffer` at all. If you pass a remote buffer to node APIs
that accepting `Buffer`, you should assume the remote buffer would be treated that accept a `Buffer`, you should assume the remote buffer would be treated
like a normal object, instead of a `Buffer`. like a normal object, instead of a `Buffer`.
For example you can call `BrowserWindow.capturePage` in renderer process, which For example, you can call `BrowserWindow.capturePage` in the renderer process, which
returns a `Buffer` by calling passed callback: returns a `Buffer` by calling the passed callback:
```javascript ```javascript
var remote = require('remote'); var remote = require('remote');
@ -106,12 +105,12 @@ remote.getCurrentWindow().capturePage(function(buf) {
``` ```
But you may be surprised to find that the file written was corrupted. This is But you may be surprised to find that the file written was corrupted. This is
because when you called `fs.writeFile`, you thought `buf` was a `Buffer`, but because when you called `fs.writeFile`, thinking that `buf` was a `Buffer` when
indeed it was a remote buffer, and it would be converted to string before it was in fact it was a remote buffer, and it was converted to string before it was
written to file. Since `buf` contained binary data and could not be represented written to the file. Since `buf` contained binary data and could not be represented
by UTF-8 encoded string, the written file would be corrupted. by a UTF-8 encoded string, the written file was corrupted.
The workaround is to write the `buf` in browser process, where it is a real The work-around is to write the `buf` in the browser process, where it is a real
`Buffer`: `Buffer`:
```javascript ```javascript
@ -125,8 +124,8 @@ remote.getCurrentWindow().capturePage(function(buf) {
The same thing could happen for all native types, but usually it would just The same thing could happen for all native types, but usually it would just
throw a type error. The `Buffer` deserves your special attention because it throw a type error. The `Buffer` deserves your special attention because it
can be converted to string and APIs accepting `Buffer` usually accept string might be converted to string, and APIs accepting `Buffer` usually accept string
too, and data corruption only happens when it contains binary data. too, and data corruption could happen when it contains binary data.
## remote.require(module) ## remote.require(module)
@ -137,7 +136,7 @@ Returns the object returned by `require(module)` in the browser process.
## remote.getCurrentWindow() ## remote.getCurrentWindow()
Returns the [BrowserWindow](browser-window.md) object which Returns the [BrowserWindow](browser-window.md) object which
represents current window. represents the current window.
## remote.getGlobal(name) ## remote.getGlobal(name)
@ -148,5 +147,5 @@ process.
## remote.process ## remote.process
Returns the `process` object in the browser process, this is the same with Returns the `process` object in the browser process. This is the same as
`remote.getGlobal('process')` but gets cached. `remote.getGlobal('process')`, but gets cached.