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: document the return value of process.send() and worker.send() #27003

Closed
wants to merge 4 commits into from
Closed

doc: document the return value of process.send() and worker.send() #27003

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
782e702
doc: document the return value of {process,worker}.send()
shree-y Mar 29, 2019
9426474
doc: document the return value of {process,worker}.send()
shree-y Apr 2, 2019
6fccf84
doc: document the return value of {process,worker}.send()
shree-y Apr 26, 2019
9101de7
Re-arranged Worker and Error in alphabetical order
shree-y May 24, 2019
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
17 changes: 17 additions & 0 deletions doc/api/cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,6 +459,21 @@ if (cluster.isMaster) {
}
```

The optional `callback` is a function that is invoked after the message is
sent but before the worker or master may have received it.
The function is called with a single argument: `null` on success,
or an [`Error`][] object on failure.

If no `callback` function is provided and the message cannot be sent, an
`'error'` event will be emitted by the [`Worker`][] object. This can
happen, for instance, when the worker has already exited.


`worker.send()` will throw an error if the channel has closed or when the
backlog of unsent messages exceeds a threshold that makes it unwise to send
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't correct. For master, worker.send basically goes through a couple layers, and ends up being a direct call of https://nodejs.org/api/child_process.html#child_process_subprocess_send_message_sendhandle_options_callback. I suggest redirecting to those docs from here.

I'd have to go spelunking through the code, but I strongly suspect that in child processes, .send() is same as process.send(), and that ends up at an internal function that also has the same interface as the ChildProcess.send(). forking a child and doing console.log(process.send) might be easier than reading the code.

That .send throws when unsent messages exceeds a backlog is definitely not the case, unless I very, very much misread the code.

more. Otherwise, the method returns `true`. The `callback` function can be
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you are going to describe the callback function, probably best to say when it is called (after the message has been sent), then describe what it could be used for.

used to implement flow control.

## Event: 'disconnect'
<!-- YAML
added: v0.7.9
Expand Down Expand Up @@ -847,8 +862,10 @@ socket.on('data', (id) => {
[`child_process` event: `'message'`]: child_process.html#child_process_event_message
[`cluster.settings`]: #cluster_cluster_settings
[`disconnect`]: child_process.html#child_process_subprocess_disconnect
[`Error`]: errors.html#errors_class_error
[`kill`]: process.html#process_process_kill_pid_signal
[`process` event: `'message'`]: process.html#process_event_message
[`server.close()`]: net.html#net_event_close
[`Worker`]: #cluster_class_worker
[`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect
[Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options
16 changes: 16 additions & 0 deletions doc/api/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1840,6 +1840,21 @@ If Node.js was not spawned with an IPC channel, `process.send()` will be
The message goes through serialization and parsing. The resulting message might
not be the same as what is originally sent.

The optional `callback` is a function that is invoked after the message is sent
but before the parent process may have received it.
The function is called with a single argument: `null` on success,
or an [`Error`][] object on failure.

If no `callback` function is provided and the message cannot be sent, an
`'error'` event will be emitted by the [`Process`][] object. This can
happen, for instance, when the process has already exited.


`process.send()` will return false if the channel has closed or when the
shree-y marked this conversation as resolved.
Show resolved Hide resolved
shree-y marked this conversation as resolved.
Show resolved Hide resolved
backlog of unsent messages exceeds a threshold that makes it unwise to send
more. Otherwise, the method returns `true`. The `callback` function can be
used to implement flow control.

## process.setegid(id)
<!-- YAML
added: v2.0.0
Expand Down Expand Up @@ -2335,3 +2350,4 @@ cases:
[process_emit_warning]: #process_process_emitwarning_warning_type_code_ctor
[process_warning]: #process_event_warning
[report documentation]: report.html
[`Process`]: #process_process