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

Merge pull request #1313 from ArtskydJ/browser-side-to-main-process

Browse source 
Renamed browser-side to main process
This commit is contained in:
Cheng Zhao 2015-03-29 15:25:56 +08:00
commit 85838fbf1a
15 changed files with 98 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/README.md
View file

@ -3,7 +3,7 @@
* [Application distribution](tutorial/application-distribution.md)
* [Application packaging](tutorial/application-packaging.md)
* [Using native node modules](tutorial/using-native-node-modules.md)
* [Debugging browser process](tutorial/debugging-browser-process.md)
* [Debugging main process](tutorial/debugging-main-process.md)
* [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
* [DevTools extension](tutorial/devtools-extension.md)
@ -25,7 +25,7 @@ Custom DOM elements:
* [`<webview>` tag](api/web-view-tag.md)
* [`window.open` function](api/window-open.md)
Modules for browser side:
Modules for the main process:
* [app](api/app.md)
* [auto-updater](api/auto-updater.md)
@ -33,20 +33,20 @@ Modules for browser side:
* [content-tracing](api/content-tracing.md)
* [dialog](api/dialog.md)
* [global-shortcut](api/global-shortcut.md)
* [ipc (browser)](api/ipc-browser.md)
* [ipc (main process)](api/ipc-main-process.md)
* [menu](api/menu.md)
* [menu-item](api/menu-item.md)
* [power-monitor](api/power-monitor.md)
* [protocol](api/protocol.md)
* [tray](api/tray.md)
Modules for web page:
Modules for the renderer process (web page):
* [ipc (renderer)](api/ipc-renderer.md)
* [remote](api/remote.md)
* [web-frame](api/web-frame.md)
Modules for both sides:
Modules for both processes:
* [clipboard](api/clipboard.md)
* [crash-reporter](api/crash-reporter.md)

2
docs/api/auto-updater.md
View file

@ -53,7 +53,7 @@ server that you are requesting updates from. A common approach is to use query
parameters, like this:
```javascript
// On browser side
// On the main process
var app = require('app');
var autoUpdater = require('auto-updater');
autoUpdater.setFeedUrl('http://mycompany.com/myapp/latest?version=' + app.getVersion());

22
docs/api/browser-window.md
View file

@ -224,14 +224,14 @@ Remove the devtools extension whose name is `name`.
The `WebContents` object this window owns, all web page related events and
operations would be done via it.
**Note:** Users should never store this object because it may becomes `null`
when the web page has crashed.
**Note:** Users should never store this object because it may become `null`
when the renderer process (web page) has crashed.
### BrowserWindow.devToolsWebContents
Get the `WebContents` of devtools of this window.
**Note:** Users should never store this object because it may becomes `null`
**Note:** Users should never store this object because it may become `null`
when the devtools has been closed.
### BrowserWindow.id
@ -241,10 +241,10 @@ Get the unique ID of this window.
### BrowserWindow.destroy()
Force closing the window, the `unload` and `beforeunload` event won't be emitted
for the web page, and `close` event would also not be emitted for this window,
but it would guarantee the `closed` event to be emitted.
for the web page, and `close` event would also not be emitted
for this window, but it would guarantee the `closed` event to be emitted.
You should only use this method when the web page has crashed.
You should only use this method when the renderer process (web page) has crashed.
### BrowserWindow.close()
@ -810,10 +810,10 @@ Executes editing command `replaceMisspelling` in page.
Send `args..` to the web page via `channel` in asynchronous message, the web
page can handle it by listening to the `channel` event of `ipc` module.
An example of sending messages from browser side to web pages:
An example of sending messages from the main process to the renderer process:
```javascript
// On browser side.
// On the main process.
var window = null;
app.on('ready', function() {
window = new BrowserWindow({width: 800, height: 600});
@ -840,6 +840,6 @@ app.on('ready', function() {
**Note:**
1. The IPC message handler in web pages do not have a `event` parameter, which
is different from the handlers on browser side.
2. There is no way to send synchronous messages from browser side to web pages,
because it would be very easy to cause dead locks.
is different from the handlers on the main process.
2. There is no way to send synchronous messages from the main process to a
renderer process, because it would be very easy to cause dead locks.

4
docs/api/content-tracing.md
View file

@ -63,7 +63,7 @@ combination of `tracing.DEFAULT_OPTIONS`, `tracing.ENABLE_SYSTRACE`,
Stop recording on all processes.
Child processes typically are caching trace data and only rarely flush and send
trace data back to the browser process. That is because it may be an expensive
trace data back to the main process. That is because it may be an expensive
operation to send the trace data over IPC, and we would like to avoid much
runtime overhead of tracing. So, to end tracing, we must asynchronously ask all
child processes to flush any pending trace data.
@ -106,7 +106,7 @@ is called back.
Get the current monitoring traced data.
Child processes typically are caching trace data and only rarely flush and send
trace data back to the browser process. That is because it may be an expensive
trace data back to the main process. That is because it may be an expensive
operation to send the trace data over IPC, and we would like to avoid much
runtime overhead of tracing. So, to end tracing, we must asynchronously ask all
child processes to flush any pending trace data.

6
docs/api/crash-reporter.md
View file

@ -36,10 +36,10 @@ sent or the crash reporter is not started, `null` will be returned.
The crash reporter will send the following data to the `submitUrl` as `POST`:
* `rept` String - eg. atom-shell-crash-service
* `rept` String - e.g. 'atom-shell-crash-service'
* `ver` String - The version of atom-shell
* `platform` String - eg. win32
* `process_type` String - eg. browser
* `platform` String - e.g. 'win32'
* `process_type` String - e.g. 'renderer'
* `ptime` Number
* `_version` String - The version in `package.json`
* `_productName` String - The product name in the crashReporter `options` object

17
docs/api/ipc-browser.md → docs/api/ipc-main-process.md
View file

@ -1,19 +1,20 @@
# ipc (browser)
# ipc (main process)
Handles asynchronous and synchronous message sent from web page.
Handles asynchronous and synchronous message sent from a renderer process (web
page).
The messages sent from web page would be emitted to this module, the event name
The messages sent from a renderer would be emitted to this module, the event name
is the `channel` when sending message. To reply a synchronous message, you need
to set `event.returnValue`, to send an asynchronous back to the sender, you can
use `event.sender.send(...)`.
It's also possible to send messages from browser side to web pages, see
[WebContents.send](browser-window.md#webcontentssendchannel-args) for more.
It's also possible to send messages from main process to the renderer process,
see [WebContents.send](browser-window.md#webcontentssendchannel-args) for more.
An example of sending and handling messages:
```javascript
// In browser.
// In main process.
var ipc = require('ipc');
ipc.on('asynchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
@ -27,7 +28,7 @@ ipc.on('synchronous-message', function(event, arg) {
```
```javascript
// In web page.
// In renderer process (web page).
var ipc = require('ipc');
console.log(ipc.sendSync('synchronous-message', 'ping')); // prints "pong"
@ -45,4 +46,4 @@ Assign to this to return an value to synchronous messages.
### Event.sender
The `WebContents` of the web page that has sent the message.
The `WebContents` that sent the message.

18
docs/api/ipc-renderer.md
View file

@ -1,29 +1,29 @@
# ipc (renderer)
The `ipc` module provides a few methods so you can send synchronous and
asynchronous messages to the browser, and also receive messages sent from
browser. If you want to make use of modules of browser from renderer, you
might consider using the [remote](remote.md) module.
asynchronous messages to the main process, and also receive messages sent from
main process. If you want to make use of modules of main process from renderer
process, you might consider using the [remote](remote.md) module.
See [ipc (browser)](ipc-browser.md) for examples.
See [ipc (main process)](ipc-main-process.md) for examples.
## ipc.send(channel[, args...])
Send `args..` to the web page via `channel` in asynchronous message, the browser
Send `args..` to the renderer via `channel` in asynchronous message, the main
process can handle it by listening to the `channel` event of `ipc` module.
## ipc.sendSync(channel[, args...])
Send `args..` to the web page via `channel` in synchronous message, and returns
the result sent from browser. The browser process can handle it by listening to
Send `args..` to the renderer via `channel` in synchronous message, and returns
the result sent from main process. The main process can handle it by listening to
the `channel` event of `ipc` module, and returns by setting `event.returnValue`.
**Note:** Usually developers should never use this API, since sending
synchronous message would block the whole web page.
synchronous message would block the whole renderer process.
## ipc.sendToHost(channel[, args...])
Like `ipc.send` but the message will be sent to the host page instead of the
browser process.
main process.
This is mainly used by the page in `<webview>` to communicate with host page.

4
docs/api/power-monitor.md
View file

@ -1,7 +1,7 @@
# power-monitor
The `power-monitor` module is used to monitor the power state change, you can
only use it on the browser side.
The `power-monitor` module is used to monitor the power state change. You can
only use it on the main process.
An example is:

2
docs/api/process.md
View file

@ -3,7 +3,7 @@
The `process` object in atom-shell has following differences between the one in
upstream node:
* `process.type` String - Process's type, can be `browser` or `renderer`.
* `process.type` String - Process's type, can be `browser` (i.e. main process) or `renderer`.
* `process.versions['atom-shell']` String - Version of atom-shell.
* `process.versions['chrome']` String - Version of Chromium.
* `process.resourcesPath` String - Path to JavaScript source code.

46
docs/api/remote.md
View file

@ -1,13 +1,13 @@
# remote
The `remote` module provides a simple way to do inter-process communication
between the renderer process and the browser process.
between the renderer process and the main process.
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
Without the `remote` module, users who wanted to call a main process 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,
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).
@ -23,43 +23,43 @@ win.loadUrl('https://github.com');
## Remote objects
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).
object in the main 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 the renderer process.
Instead, it created a `BrowserWindow` object in the browser 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.
## Lifetime of remote objects
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 the browser process would never be released. When the remote object has been
garbage collected, the corresponding object in the browser process would be
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
dereferenced.
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,
freed), the corresponding object in the main 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
## Passing callbacks to the main process
Some APIs in the browser process accept callbacks, and it would be attempting to
Some APIs in the main 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 deadlocks, the callbacks passed to the browser process
are called asynchronously, so you should not expect the browser process to
First, in order to avoid deadlocks, the callbacks passed to the main process
are called asynchronously, so you should not expect the main process to
get the return value of the passed callbacks.
Second, the callbacks passed to the browser process will not get released
Second, the callbacks passed to the main process will not get released
automatically after they are called. Instead, they will persistent until the
browser process garbage-collects them.
main process garbage-collects them.
For example, the following code seems innocent at first glance. It installs a
callback for the `close` event on a remote object:
@ -71,19 +71,19 @@ remote.getCurrentWindow().on('close', function() {
});
```
The problem is that the callback would be stored in the browser process until you
The problem is that the callback would be stored in the main process until you
explicitly uninstall it! So each time you reload your window, the callback would
be installed again and previous callbacks would just leak. 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 browser process.
when the `close` event was emitted, exceptions would be raised in the main process.
Generally, unless you are clear what you are doing, you should always avoid
passing callbacks to the browser process.
passing callbacks to the main process.
## Remote buffer
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
the main 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 although a remote buffer behaves like the real
@ -110,7 +110,7 @@ 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 work-around is to write the `buf` in the browser process, where it is a real
The work-around is to write the `buf` in the main process, where it is a real
`Buffer`:
```javascript
@ -131,7 +131,7 @@ too, and data corruption could happen when it contains binary data.
* `module` String
Returns the object returned by `require(module)` in the browser process.
Returns the object returned by `require(module)` in the main process.
## remote.getCurrentWindow()
@ -142,10 +142,10 @@ belongs to.
* `name` String
Returns the global variable of `name` (e.g. `global[name]`) in the browser
Returns the global variable of `name` (e.g. `global[name]`) in the main
process.
## remote.process
Returns the `process` object in the browser 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.

13
docs/api/synopsis.md
View file

@ -5,14 +5,14 @@ atom-shell, and third-party node modules are fully supported too (including the
[native modules](../tutorial/using-native-node-modules.md)).
Atom-shell also provides some extra built-in modules for developing native
desktop applications. Some modules are only available on the browser side, some
are only available on the client (renderer) side, and some can be used on both sides.
desktop applications. Some modules are only available on the main process, some
are only available on the renderer process, and some can be used on both processes.
The basic rule is: if a module is GUI or low-level system related, then it should
be only available on the browser side. You need to be familiar with the concept of
[browser-side vs. client-side](../tutorial/quick-start.md#the-browser-side) scripts
to be able to use those modules.
be only available on the main process. You need to be familiar with the concept of
[main process vs. renderer process](../tutorial/quick-start.md#the-main-process)
scripts to be able to use those modules.
The browser-side script is just like a normal `node.js` script:
The main process script is just like a normal `node.js` script:
```javascript
var app = require('app');
@ -24,7 +24,6 @@ app.on('ready', function() {
window = new BrowserWindow({width: 800, height: 600});
window.loadUrl('https://github.com');
});
```
The web page is no different than a normal web page, except for the extra

16
docs/development/source-code-directory-structure.md
View file

@ -13,27 +13,27 @@ to understand the source code better.
* **atom** - Source code of atom-shell.
* **app** - System entry code.
* **browser** - The frontend including the main window, UI, and all browser
side things. This talks to the renderer to manage web pages.
* **lib** - Javascript part of browser side initialization code.
* **browser** - The frontend including the main window, UI, and all of the
main process things. This talks to the renderer to manage web pages.
* **lib** - Javascript part of the main process initialization code.
* **ui** - Implementation of UI stuff for different platforms.
* **cocoa** - Cocoa specific source code.
* **gtk** - GTK+ specific source code.
* **win** - Windows GUI specific source code.
* **default_app** - The default page to show when atom-shell is started
without providing an app.
* **api** - The implementation of browser side APIs.
* **api** - The implementation of the main process APIs.
* **lib** - Javascript part of the API implementation.
* **net** - Network related code.
* **mac** - Mac specific Objective-C source code.
* **resources** - Icons, platform-dependent files, etc.
* **renderer** - Code that runs in renderer process.
* **lib** - Javascript part of renderer initialization code.
* **api** - The implementation of renderer side APIs.
* **api** - The implementation of renderer process APIs.
* **lib** - Javascript part of the API implementation.
* **common** - Code that used by both browser and renderer, including some
utility functions and code to integrate node's message loop into Chromium's
message loop.
* **common** - Code that used by both the main and renderer processes,
including some utility functions and code to integrate node's message
loop into Chromium's message loop.
* **lib** - Common Javascript initialization code.
* **api** - The implementation of common APIs, and foundations of
atom-shell's built-in modules.

12
docs/tutorial/debugging-browser-process.md → docs/tutorial/debugging-main-process.md
View file

@ -1,9 +1,9 @@
# Debugging browser process
# Debugging the main process
The devtools of browser window can only debug the scripts of the web pages
(e.g. the renderer process), in order to provide a way to debug the scripts of
the browser side (e.g. the browser process), atom-shell has provided the
`--debug` and `--debug-brk` switches.
The devtools of browser window can only debug the renderer process scripts.
(I.e. the web pages.) In order to provide a way to debug the scripts of
the main process, atom-shell has provided the `--debug` and `--debug-brk`
switches.
## Command line switches
@ -19,7 +19,7 @@ Like `--debug` but pauses the script on the first line.
## Use node-inspector for debugging
__Note:__ Atom Shell uses node v0.11.13, which currently doesn't work very well
with node-inspector, and the browser process would crash if you inspect the
with node-inspector, and the main process would crash if you inspect the
`process` object under node-inspector's console.
### 1. Start the [node-inspector][node-inspector] server

4
docs/tutorial/online-offline-events.md
View file

@ -37,10 +37,10 @@ _online-status.html_
```
There may be instances where one wants to respond to these events in the
browser process as well. The browser process however does not have a
main process as well. The main process however does not have a
`navigator` object and thus cannot detect these events directly. Using
Atom-shell's inter-process communication utilities, the events can be forwarded
to the browser process and handled as needed, as shown in the following example.
to the main process and handled as needed, as shown in the following example.
_main.js_

29
docs/tutorial/quick-start.md
View file

@ -11,26 +11,17 @@ It doesn't mean atom-shell is a JavaScript binding to GUI libraries. Instead,
atom-shell uses web pages as its GUI, so you could also see it as a minimal
Chromium browser, controlled by JavaScript.
### The browser side
### The main process
If you have experience with Node.js web applications, you will know that there
are two types of JavaScript scripts: the server side scripts and the client side
scripts. Server-side JavaScript is that which runs on the Node.js
runtime, while client-side JavaScript runs inside the user's browser.
The main atom-shell process displays a GUI by creating web pages. We have
**scripts that run in the atom-shell runtime**, that create **scripts
that run in the web page**.
In atom-shell we have similar concepts: Since atom-shell displays a GUI by
showing web pages, we have **scripts that run in the web page**, and also
**scripts run by the atom-shell runtime**, which creates those web pages.
Like Node.js, we call them **client scripts**, and **browser scripts**
(meaning the browser replaces the concept of the server here).
In atom-shell, we have provided the [ipc](../api/ipc-renderer.md) module for
communication from the main process to the renderer process, and the
[remote](../api/remote.md) module for easy RPC support.
In traditional Node.js applications, communication between server and
client is usually facilitated via web sockets. In atom-shell, we have provided
the [ipc](../api/ipc-renderer.md) module for browser to client
communication, and the [remote](../api/remote.md) module for easy RPC
support.
### Web page and Node.js
### The renderer process
Normal web pages are designed to not reach outside of the browser, which makes
them unsuitable for interacting with native systems. Atom-shell provides Node.js
@ -38,7 +29,7 @@ APIs in web pages so you can access native resources from web pages, just like
[nw.js](https://github.com/nwjs/nw.js).
But unlike nw.js, you cannot do native GUI related operations in web
pages. Instead you need to do them on the browser side by sending messages to
pages. Instead you need to do them on the main process by sending messages to
it, or using the easy [remote](../api/remote.md) module.
@ -56,7 +47,7 @@ your-app/
The format of `package.json` is exactly the same as that of Node's modules, and
the script specified by the `main` field is the startup script of your app,
which will run on the browser side. An example of your `package.json` might look
which will run on the main process. An example of your `package.json` might look
like this:
```json