From 74c517d186df4568acce653df226d721d32d417a Mon Sep 17 00:00:00 2001 From: Greg Mefford Date: Fri, 9 May 2014 23:51:25 -0400 Subject: [PATCH] Doc: grammar/content fixes in the remote module Mostly minor grammatical issues, but also some content that seems to be incorrect based on the surrounding descriptions and example code. --- docs/api/remote.md | 101 ++++++++++++++++++++++----------------------- 1 file changed, 50 insertions(+), 51 deletions(-) diff --git a/docs/api/remote.md b/docs/api/remote.md index 4440dc8dba97..d8118cc5c6da 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -1,14 +1,14 @@ # remote 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 -process, if users want to call an browser side API in the renderer process -, they usually would have to explicitly send inter-process messages to the -browser process. But with the `remote` module, users can invoke methods of -objects living in browser process without sending inter-process messages -directly, like Java's +In atom-shell, only GUI-related modules are available in the renderer process. +Without the `remote` module, users who wanted to call a browser-side API in +the renderer process would have to explicitly send inter-process messages +to the browser process. With the `remote` module, users can invoke methods of +browser-side 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: @@ -22,47 +22,46 @@ win.loadUrl('https://github.com'); ## Remote objects -Each object (including function) returned by `remote` module represents an -object in browser process (we call it remote object or remote function), when -you invoke methods of a remote object, or call a remote function, or even create +Each object (including functions) returned by the `remote` module represents an +object in the browser process (we call it a remote object or remote function). +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 synchronous inter-process messages. -In the example above, both `BrowserWindow` and `win` were remote objects. And -`new BrowserWindow` didn't create a `BrowserWindow` object in renderer process, -instead it created a `BrowserWindow` object in browser process, and returned the -corresponding remote object in renderer process, namely the `win` object. +In the example above, both `BrowserWindow` and `win` were remote objects and +`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer process. +Instead, it created a `BrowserWindow` object in the browser process and returned the +corresponding remote object in the renderer process, namely the `win` object. ## 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 -in browser process would never be released. And when the remote object has been -garbage collected, the corresponding object in browser process would be +in the browser process would never be released. When the remote object has been +garbage collected, the corresponding object in the browser process would be dereferenced. -But it also means that, if the remote object is leaked in renderer process, like -being stored in a map but never got freed, the corresponding object in browser -process would also be leaked too. So you should be very careful not to leak -remote objects. +If the remote object is leaked in renderer process (e.g. stored in a map but never +freed), the corresponding object in the browser process would 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 browser -Some APIs in browser process accepts callbacks, and it would be attempting to -pass callbacks when calling a remote function. Yes `remote` module does support -doing this, but you should also be extremely careful on this. +Some APIs in the browser process accept callbacks, and it would be attempting to +pass callbacks when calling a remote function. The `remote` module does support +doing this, but you should also be extremely careful with this. -First, in order to avoid dead locks, the callbacks passed to browser process -would be called asynchronously, so you should not expect the browser process to +First, in order to avoid deadlocks, the callbacks passed to the browser process +are called asynchronously, so you should not expect the browser process to get the return value of the passed callbacks. -Second, the callbacks passed to browser process would not get released -automatically after they were called, instead they would persistent until the -browser process garbage collected them. +Second, the callbacks passed to the browser process will not get released +automatically after they are called. Instead, they will persistent until the +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: ```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 -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, -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 -passing callbacks to browser process. +Generally, unless you are clear what you are doing, you should always avoid +passing callbacks to the browser process. ## Remote buffer -An instance of node's `Buffer` is an object, so when you got a `Buffer` from -browser process, what you got was indeed a remote object (let's call it remote +An instance of node's `Buffer` is an object, so when you get a `Buffer` from +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. -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 -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`. -For example you can call `BrowserWindow.capturePage` in renderer process, which -returns a `Buffer` by calling passed callback: +For example, you can call `BrowserWindow.capturePage` in the renderer process, which +returns a `Buffer` by calling the passed callback: ```javascript 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 -because when you called `fs.writeFile`, you thought `buf` was a `Buffer`, but -indeed it was a remote buffer, and it would be converted to string before it was -written to file. Since `buf` contained binary data and could not be represented -by UTF-8 encoded string, the written file would be corrupted. +because when you called `fs.writeFile`, thinking that `buf` was a `Buffer` when +in fact it was a remote buffer, and it was converted to string before it was +written to the file. Since `buf` contained binary data and could not be represented +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`: ```javascript @@ -125,8 +124,8 @@ remote.getCurrentWindow().capturePage(function(buf) { 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 -can be converted to string and APIs accepting `Buffer` usually accept string -too, and data corruption only happens when it contains binary data. +might be converted to string, and APIs accepting `Buffer` usually accept string +too, and data corruption could happen when it contains binary data. ## remote.require(module) @@ -137,7 +136,7 @@ Returns the object returned by `require(module)` in the browser process. ## remote.getCurrentWindow() Returns the [BrowserWindow](browser-window.md) object which -represents current window. +represents the current window. ## remote.getGlobal(name) @@ -148,5 +147,5 @@ process. ## remote.process -Returns the `process` object in the browser process, this is the same with -`remote.getGlobal('process')` but gets cached. +Returns the `process` object in the browser process. This is the same as +`remote.getGlobal('process')`, but gets cached.