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.

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

docs: add note about using cluster networking-less #17031

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
8 participants
@pimlie
Contributor

pimlie commented Nov 14, 2017

Although the primary use-case for the cluster module is networking, the module provides a generic master/worker interface that could also be used if you dont use networking at all. Currently the docs are a bit ambiguous about this as only the primary use-case is ever mentioned, this remark should clarify that the cluster module can also be used without disadvantages if you dont use networking.

Refs: nodejs/help#970

Checklist
Affected core subsystem(s)

doc

@devsnek

This comment has been minimized.

Show comment
Hide comment
@devsnek

devsnek Nov 14, 2017

Member

networking-less is kinda awk, maybe just without networking

Member

devsnek commented Nov 14, 2017

networking-less is kinda awk, maybe just without networking

@pimlie

This comment has been minimized.

Show comment
Hide comment
@pimlie

pimlie Nov 14, 2017

Contributor

Thanks, you are probably right. Changed both the commit as the commit message

Contributor

pimlie commented Nov 14, 2017

Thanks, you are probably right. Changed both the commit as the commit message

@pimlie

This comment has been minimized.

Show comment
Hide comment
@pimlie

pimlie Nov 15, 2017

Contributor

@Trott Strange, I received an email with your comment about not thinking that networking is the primary use-case for cluster but don't see your comment listed here on github?

The main reason I wrote that networking is the primary use-case is because I have been startled by the current documentation for weeks and @bnoordhuis confirmed this in the referenced nodejs/help issue. Maybe otherwise the Cluster docs could use more of an overhaul then just adding this sentence?

Let me give you a few examples of why I think the current documentation is quite ambiguous if networking isn't the primary use-case:

  • The first/introduction paragraph says The cluster module allows easy creation of child processes that all share server ports. To me this is much more a statement then an introduction for the listed example that uses networking. Although nowhere is said that you can only use cluster with networking, it also doesn't specifically state the inverse which could imply that only the listed example use-case is supported. Hence the ambiguity.

  • Under How It Works again except for the first sentence this whole paragraph only talks about incoming connections and how they are shared between workers. And as this is the only thing that's talked about, it doesnt leave much room to the reader for a use-case without networking.

  • Options like schedulingPolicy or events like listening that only apply to networking are not labelled as such. Of course it is implied and it may even be trivial that they are, but as I said before whats trivial for one may be inconclusive for another. Especially in the bigger picture of the cluster docs as a whole

Not sure if this translates correctly to English, but in Dutch we say All pilsner is beer but not all beer is pilsner. I guess you could say that currently the cluster docs only talk about pilsner (with networking) while it applies to all beers (without networking)? 🍻

Contributor

pimlie commented Nov 15, 2017

@Trott Strange, I received an email with your comment about not thinking that networking is the primary use-case for cluster but don't see your comment listed here on github?

The main reason I wrote that networking is the primary use-case is because I have been startled by the current documentation for weeks and @bnoordhuis confirmed this in the referenced nodejs/help issue. Maybe otherwise the Cluster docs could use more of an overhaul then just adding this sentence?

Let me give you a few examples of why I think the current documentation is quite ambiguous if networking isn't the primary use-case:

  • The first/introduction paragraph says The cluster module allows easy creation of child processes that all share server ports. To me this is much more a statement then an introduction for the listed example that uses networking. Although nowhere is said that you can only use cluster with networking, it also doesn't specifically state the inverse which could imply that only the listed example use-case is supported. Hence the ambiguity.

  • Under How It Works again except for the first sentence this whole paragraph only talks about incoming connections and how they are shared between workers. And as this is the only thing that's talked about, it doesnt leave much room to the reader for a use-case without networking.

  • Options like schedulingPolicy or events like listening that only apply to networking are not labelled as such. Of course it is implied and it may even be trivial that they are, but as I said before whats trivial for one may be inconclusive for another. Especially in the bigger picture of the cluster docs as a whole

Not sure if this translates correctly to English, but in Dutch we say All pilsner is beer but not all beer is pilsner. I guess you could say that currently the cluster docs only talk about pilsner (with networking) while it applies to all beers (without networking)? 🍻

@gireeshpunathil

This comment has been minimized.

Show comment
Hide comment
@gireeshpunathil

gireeshpunathil Nov 15, 2017

Member

I guess the primary use case for cluster is to attain vertical sclability (in-system) to suppliment any short-comings the single-threaded node has in exploiting the multiple cores in the host, and as the primary use case of node is web workload, the cluster naturally inherited it. Nothing stopping one from using cluster for other purposes such as massive computation in a distributed manner. The doc changes looks good to me, thanks!

Member

gireeshpunathil commented Nov 15, 2017

I guess the primary use case for cluster is to attain vertical sclability (in-system) to suppliment any short-comings the single-threaded node has in exploiting the multiple cores in the host, and as the primary use case of node is web workload, the cluster naturally inherited it. Nothing stopping one from using cluster for other purposes such as massive computation in a distributed manner. The doc changes looks good to me, thanks!

@Trott

This comment has been minimized.

Show comment
Hide comment
@Trott

Trott Nov 15, 2017

Member

@pimlie OK, you convinced me. I never thought of it that way, but the docs seem to make that assumption.

(You didn't see my comment on GitHub because I deleted it immediately after leaving it. I realized I probably wasn't adding a whole lot to the conversation with my question so I deleted it. I guess GitHub sends notifications immediately because the comment was probably there for a matter of seconds. Oh well. Lesson learned.)

Member

Trott commented Nov 15, 2017

@pimlie OK, you convinced me. I never thought of it that way, but the docs seem to make that assumption.

(You didn't see my comment on GitHub because I deleted it immediately after leaving it. I realized I probably wasn't adding a whole lot to the conversation with my question so I deleted it. I guess GitHub sends notifications immediately because the comment was probably there for a matter of seconds. Oh well. Lesson learned.)

Show outdated Hide outdated doc/api/cluster.md Outdated
docs: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

Refs: https://github.com/nodejs/help/issues/970a
@pimlie

This comment has been minimized.

Show comment
Hide comment
@pimlie

pimlie Nov 15, 2017

Contributor

Updated as per @Trott comments

Contributor

pimlie commented Nov 15, 2017

Updated as per @Trott comments

@addaleax

This comment has been minimized.

Show comment
Hide comment
@addaleax

addaleax Nov 18, 2017

Member

Landed in adb7be2, thanks for the PR! 🎉

Member

addaleax commented Nov 18, 2017

Landed in adb7be2, thanks for the PR! 🎉

@addaleax addaleax closed this Nov 18, 2017

addaleax added a commit that referenced this pull request Nov 18, 2017

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: #17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins added a commit that referenced this pull request Dec 12, 2017

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: #17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

@MylesBorins MylesBorins referenced this pull request Dec 12, 2017

Merged

v9.3.0 proposal #17631

gibfahn added a commit that referenced this pull request Dec 19, 2017

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: #17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins added a commit that referenced this pull request Dec 19, 2017

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: #17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

@gibfahn gibfahn referenced this pull request Dec 20, 2017

Closed

v8.9.4 proposal #17772

gibfahn added a commit that referenced this pull request Dec 20, 2017

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: #17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

@gibfahn gibfahn referenced this pull request Dec 20, 2017

Merged

v8.9.4 proposal #17774

@MylesBorins MylesBorins referenced this pull request Dec 20, 2017

Merged

v6.12.3 proposal #17776

msoechting added a commit to hpicgs/node that referenced this pull request Feb 7, 2018

doc: add note about using cluster without networking
Although the primary use-case for the cluster module is networking, the
module provides a generic master/worker interface that could also be
used if you dont use networking at all. Currently the docs are a bit
ambiguous about this as only the primary use-case is ever mentioned,
this remark should clarify that the cluster module can also be used
without disadvantages if you dont use networking.

PR-URL: nodejs#17031
Refs: nodejs/help#970
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment