Skip to content

Commit

Permalink
doc: add added: information for cluster
Browse files Browse the repository at this point in the history
Ref: #6578
PR-URL: #7640
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
addaleax authored and Myles Borins committed Oct 10, 2016
1 parent fa5a12d commit 28d2271
Showing 1 changed file with 91 additions and 0 deletions.
91 changes: 91 additions & 0 deletions doc/api/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,12 +108,18 @@ responsibility to manage the worker pool for your application's needs.


## Class: Worker
<!-- YAML
added: v0.7.0
-->

A Worker object contains all public information and method about a worker.
In the master it can be obtained using `cluster.workers`. In a worker
it can be obtained using `cluster.worker`.

### Event: 'disconnect'
<!-- YAML
added: v0.7.7
-->

Similar to the `cluster.on('disconnect')` event, but specific to this worker.

Expand All @@ -124,12 +130,18 @@ cluster.fork().on('disconnect', () => {
```

### Event: 'error'
<!-- YAML
added: v0.7.3
-->

This event is the same as the one provided by [`child_process.fork()`][].

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

### Event: 'exit'
<!-- YAML
added: v0.11.2
-->

* `code` {Number} the exit code, if it exited normally.
* `signal` {String} the name of the signal (eg. `'SIGHUP'`) that caused
Expand All @@ -151,6 +163,9 @@ worker.on('exit', (code, signal) => {
```

### Event: 'listening'
<!-- YAML
added: v0.7.0
-->

* `address` {Object}

Expand All @@ -165,6 +180,9 @@ cluster.fork().on('listening', (address) => {
It is not emitted in the worker.

### Event: 'message'
<!-- YAML
added: v0.7.0
-->

* `message` {Object}
* `handle` {undefined|Object}
Expand Down Expand Up @@ -220,6 +238,9 @@ if (cluster.isMaster) {
```

### Event: 'online'
<!-- YAML
added: v0.7.0
-->

Similar to the `cluster.on('online')` event, but specific to this worker.

Expand All @@ -232,6 +253,9 @@ cluster.fork().on('online', () => {
It is not emitted in the worker.

### worker.disconnect()
<!-- YAML
added: v0.7.7
-->

In a worker, this function will close all servers, wait for the `'close'` event on
those servers, and then disconnect the IPC channel.
Expand Down Expand Up @@ -293,6 +317,9 @@ if (cluster.isMaster) {
```

### worker.id
<!-- YAML
added: v0.8.0
-->

* {Number}

Expand All @@ -303,17 +330,26 @@ While a worker is alive, this is the key that indexes it in
cluster.workers

### worker.isConnected()
<!-- YAML
added: v0.11.14
-->

This function returns `true` if the worker is connected to its master via its IPC
channel, `false` otherwise. A worker is connected to its master after it's been
created. It is disconnected after the `'disconnect'` event is emitted.

### worker.isDead()
<!-- YAML
added: v0.11.14
-->

This function returns `true` if the worker's process has terminated (either
because of exiting or being signaled). Otherwise, it returns `false`.

### worker.kill([signal='SIGTERM'])
<!-- YAML
added: v0.9.12
-->

* `signal` {String} Name of the kill signal to send to the worker
process.
Expand All @@ -330,6 +366,9 @@ Note that in a worker, `process.kill()` exists, but it is not this function,
it is [`kill`][].

### worker.process
<!-- YAML
added: v0.7.0
-->

* {ChildProcess}

Expand All @@ -344,6 +383,9 @@ on `process` and `.suicide` is not `true`. This protects against accidental
disconnection.

### worker.send(message[, sendHandle][, callback])
<!-- YAML
added: v0.7.0
-->

* `message` {Object}
* `sendHandle` {Handle}
Expand Down Expand Up @@ -373,6 +415,10 @@ if (cluster.isMaster) {
```

### worker.suicide
<!-- YAML
added: v0.7.0
deprecated: v6.0.0
-->

* {Boolean}

Expand All @@ -393,6 +439,9 @@ worker.kill();
```

## Event: 'disconnect'
<!-- YAML
added: v0.7.9
-->

* `worker` {cluster.Worker}

Expand All @@ -411,6 +460,9 @@ cluster.on('disconnect', (worker) => {
```

## Event: 'exit'
<!-- YAML
added: v0.7.9
-->

* `worker` {cluster.Worker}
* `code` {Number} the exit code, if it exited normally.
Expand All @@ -432,6 +484,9 @@ cluster.on('exit', (worker, code, signal) => {
See [child_process event: 'exit'][].

## Event: 'fork'
<!-- YAML
added: v0.7.0
-->

* `worker` {cluster.Worker}

Expand All @@ -457,6 +512,9 @@ cluster.on('exit', (worker, code, signal) => {
```

## Event: 'listening'
<!-- YAML
added: v0.7.0
-->

* `worker` {cluster.Worker}
* `address` {Object}
Expand Down Expand Up @@ -493,6 +551,9 @@ Emitted when the cluster master receives a message from any worker.
See [child_process event: 'message'][].

## Event: 'online'
<!-- YAML
added: v0.7.0
-->

* `worker` {cluster.Worker}

Expand All @@ -508,6 +569,9 @@ cluster.on('online', (worker) => {
```

## Event: 'setup'
<!-- YAML
added: v0.7.1
-->

* `settings` {Object}

Expand All @@ -520,6 +584,9 @@ The `settings` object is the `cluster.settings` object at the time
If accuracy is important, use `cluster.settings`.

## cluster.disconnect([callback])
<!-- YAML
added: v0.7.7
-->

* `callback` {Function} called when all workers are disconnected and handles are
closed
Expand All @@ -534,6 +601,9 @@ The method takes an optional callback argument which will be called when finishe
This can only be called from the master process.

## cluster.fork([env])
<!-- YAML
added: v0.6.0
-->

* `env` {Object} Key/value pairs to add to worker process environment.
* return {cluster.Worker}
Expand All @@ -543,6 +613,9 @@ Spawn a new worker process.
This can only be called from the master process.

## cluster.isMaster
<!-- YAML
added: v0.8.1
-->

* {Boolean}

Expand All @@ -551,12 +624,18 @@ by the `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is
undefined, then `isMaster` is `true`.

## cluster.isWorker
<!-- YAML
added: v0.6.0
-->

* {Boolean}

True if the process is not a master (it is the negation of `cluster.isMaster`).

## cluster.schedulingPolicy
<!-- YAML
added: v0.11.2
-->

The scheduling policy, either `cluster.SCHED_RR` for round-robin or
`cluster.SCHED_NONE` to leave it to the operating system. This is a
Expand All @@ -572,6 +651,9 @@ distribute IOCP handles without incurring a large performance hit.
values are `"rr"` and `"none"`.

## cluster.settings
<!-- YAML
added: v0.7.1
-->

* {Object}
* `execArgv` {Array} list of string arguments passed to the Node.js
Expand All @@ -590,6 +672,9 @@ the settings, including the default values.
This object is not supposed to be changed or set manually, by you.

## cluster.setupMaster([settings])
<!-- YAML
added: v0.7.1
-->

* `settings` {Object}
* `exec` {String} file path to worker file. (Default=`process.argv[1]`)
Expand Down Expand Up @@ -630,6 +715,9 @@ cluster.fork(); // http worker
This can only be called from the master process.

## cluster.worker
<!-- YAML
added: v0.7.0
-->

* {Object}

Expand All @@ -648,6 +736,9 @@ if (cluster.isMaster) {
```

## cluster.workers
<!-- YAML
added: v0.7.0
-->

* {Object}

Expand Down

0 comments on commit 28d2271

Please sign in to comment.