Skip to content

Commit

Permalink
doc: describe process API for IPC
Browse files Browse the repository at this point in the history
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
PR-URL: #1978
  • Loading branch information
sam-github committed Sep 9, 2015
1 parent f8152df commit f442904
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 4 deletions.
9 changes: 6 additions & 3 deletions doc/api/child_process.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ you are listening on both events to fire a function, remember to guard against
calling your function twice.

See also [`ChildProcess#kill()`](#child_process_child_kill_signal) and
[`ChildProcess#send()`](#child_process_child_send_message_sendhandle).
[`ChildProcess#send()`](#child_process_child_send_message_sendhandle_callback).

### Event: 'exit'

Expand Down Expand Up @@ -85,8 +85,9 @@ and the `.connected` property is false.

### Event: 'message'

* `message` {Object} a parsed JSON object or primitive value
* `sendHandle` {Handle object} a Socket or Server object
* `message` {Object} a parsed JSON object or primitive value.
* `sendHandle` {Handle object} a [net.Socket][] or [net.Server][] object, or

This comment has been minimized.

Copy link
@ronkorving

ronkorving Sep 10, 2015

Contributor

Ah, thank you so much for this! We should be linking class references in documentation everywhere. What a time saver.

undefined.

Messages sent by `.send(message, [sendHandle])` are obtained using the
`message` event.
Expand Down Expand Up @@ -760,3 +761,5 @@ throw. The `Error` object will contain the entire result from
[`child_process.spawnSync`](#child_process_child_process_spawnsync_command_args_options)

[EventEmitter]: events.html#events_class_events_eventemitter
[net.Server]: net.html#net_class_net_server
[net.Socket]: net.html#net_class_net_socket
4 changes: 3 additions & 1 deletion doc/api/cluster.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -436,7 +436,7 @@ exit, the master may choose not to respawn a worker based on this value.
Send a message to a worker or master, optionally with a handle.

In the master this sends a message to a specific worker. It is identical to
[child.send()](child_process.html#child_process_child_send_message_sendhandle).
[ChildProcess.send()][].

In a worker this sends a message to the master. It is identical to
`process.send()`.
Expand Down Expand Up @@ -646,3 +646,5 @@ Similar to the `cluster.on('exit')` event, but specific to this worker.
This event is the same as the one provided by `child_process.fork()`.

In a worker you can also use `process.on('error')`.

[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
45 changes: 45 additions & 0 deletions doc/api/process.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,16 @@ Example of listening for `exit`:
});


## Event: 'message'

* `message` {Object} a parsed JSON object or primitive value
* `sendHandle` {Handle object} a [net.Socket][] or [net.Server][] object, or
undefined.

Messages sent by [ChildProcess.send()][] are obtained using the `'message'`
event on the child's process object.


## Event: 'beforeExit'

This event is emitted when Node.js empties its event loop and has nothing else to
Expand Down Expand Up @@ -904,6 +914,38 @@ a diff reading, useful for benchmarks and measuring intervals:
}, 1000);


## process.send(message[, sendHandle][, callback])

* `message` {Object}
* `sendHandle` {Handle object}

When Node.js is spawned with an IPC channel attached, it can send messages to its
parent process using `process.send()`. Each will be received as a
['message'](child_process.html#child_process_event_message)
event on the parent's `ChildProcess` object.

If io.js was not spawned with an IPC channel, `process.send()` will be undefined.


## process.disconnect()

Close the IPC channel to the parent process, allowing this child to exit
gracefully once there are no other connections keeping it alive.

Identical to the parent process's
[ChildProcess.disconnect()](child_process.html#child_process_child_disconnect).

If io.js was not spawned with an IPC channel, `process.disconnect()` will be
undefined.


### process.connected

* {Boolean} Set to false after `process.disconnect()` is called

If `process.connected` is false, it is no longer possible to send messages.


## process.mainModule

Alternate way to retrieve
Expand All @@ -915,4 +957,7 @@ to the same module.

As with `require.main`, it will be `undefined` if there was no entry script.

[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
[EventEmitter]: events.html#events_class_events_eventemitter
[net.Server]: net.html#net_class_net_server
[net.Socket]: net.html#net_class_net_socket

0 comments on commit f442904

Please sign in to comment.