Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add added: information for cluster #7640

Closed
wants to merge 1 commit into from
Closed

doc: add added: information for cluster #7640

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions doc/api/cluster.md
View file
Open in desktop
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.exitedAfterDisconnect
<!-- YAML
added: v6.0.0
-->

* {Boolean}

Expand All @@ -314,6 +341,9 @@ worker.kill();
```

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

* {Number}

Expand All @@ -324,17 +354,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 @@ -351,6 +390,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 @@ -365,6 +407,9 @@ on `process` and `.exitedAfterDisconnect` 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 @@ -394,6 +439,10 @@ if (cluster.isMaster) {
```

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

Stability: 0 - Deprecated: Use [`worker.exitedAfterDisconnect`][] instead.

Expand All @@ -420,6 +469,9 @@ This API only exists for backwards compatibility and will be removed in the
future.

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

* `worker` {cluster.Worker}

Expand All @@ -438,6 +490,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 @@ -459,6 +514,9 @@ cluster.on('exit', (worker, code, signal) => {
See [child_process event: 'exit'][].

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

* `worker` {cluster.Worker}

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

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

* `worker` {cluster.Worker}
* `address` {Object}
Expand Down Expand Up @@ -538,6 +599,9 @@ cluster.on('message', function(worker, message, handle) {
```

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

* `worker` {cluster.Worker}

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

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

* `settings` {Object}

Expand All @@ -565,6 +632,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 @@ -579,6 +649,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 @@ -588,6 +661,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 @@ -596,12 +672,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 @@ -617,6 +699,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 @@ -635,6 +720,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 @@ -675,6 +763,9 @@ cluster.fork(); // http worker
This can only be called from the master process.

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

* {Object}

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

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

* {Object}

Expand Down