{"id":15890165,"url":"https://github.com/hph/clusterfork","last_synced_at":"2025-03-20T11:35:46.640Z","repository":{"id":57311270,"uuid":"56919810","full_name":"hph/clusterfork","owner":"hph","description":"An abstraction over the Node.js cluster API allowing you to run programs clustered with little or no configuration.","archived":false,"fork":false,"pushed_at":"2016-05-06T00:06:39.000Z","size":6,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-13T07:22:32.010Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-23T13:11:09.000Z","updated_at":"2023-03-10T10:08:27.000Z","dependencies_parsed_at":"2022-09-06T03:32:39.775Z","dependency_job_id":null,"html_url":"https://github.com/hph/clusterfork","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hph%2Fclusterfork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hph%2Fclusterfork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hph%2Fclusterfork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hph%2Fclusterfork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hph","download_url":"https://codeload.github.com/hph/clusterfork/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221752963,"owners_count":16875062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-06T07:04:14.173Z","updated_at":"2024-10-28T00:40:32.389Z","avatar_url":"https://github.com/hph.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clusterfork\n\n[![Package Version](https://img.shields.io/npm/v/node-clusterfork.svg)](https://www.npmjs.com/package/node-clusterfork)\n[![License](https://img.shields.io/npm/l/node-clusterfork.svg)](https://tldrlegal.com/license/mit-license)\n\nAn abstraction over the\n[Node.js cluster API](https://nodejs.org/api/cluster.html#cluster_cluster)\nallowing you to run programs clustered with little or no configuration\n([why?](#why)).\n\nIt's as simple as running `clusterfork server.js` instead of `node server.js`!\n\n* [Installation](#installation)\n* [Usage](#usage)\n  * [Via the command-line interface](#via-the-command-line-interface)\n  * [As an npm script](#as-an-npm-script)\n  * [Programmatically](#programmatically)\n* [Features](#features)\n  * [Debug information](#debug-information)\n  * [Number of workers](#number-of-workers)\n  * [Automatic restart](#automatic-restart)\n* [Interactive example](#interactive-example)\n* [Why](#why)\n\n### Installation\n\nInstall `node-clusterfork` to your project, saving it in `package.json`:\n\n    npm install -S node-clusterfork\n\nIf you just want to try `node-clusterfork` out, you may also install it\nglobally:\n\n    npm install -g node-clusterfork\n\n### Usage\n\n##### Via the command-line interface\n\nIf you have `node-clusterfork` installed globally, you can run a Node.js\nprogram (usually a web server) like this:\n\n    clusterfork server.js\n\nYou might want to pass the `-v / --verbose` flag as well, to get a better idea\nof what's going on behind the scenes.\n\n##### As an npm script\n\nNode.js programs are often run via the `npm start` command. For that to work,\nyou will have to edit your `package.json` in this fashion:\n\n```diff\n\"scripts\": {\n- \"start\": \"node server.js\"\n+ \"start\": \"clusterfork server.js\"\n}\n```\n\nNote that `node-clusterfork` should be installed normally, not globally, for\nthe above example.\n\n##### Programmatically\n\nIf you'd rather not do any of the above, and prefer the explicitness of code,\nyou might want to use `node-clusterfork` programmatically:\n\n```javascript\n'use strict';\nconst clusterfork = require('node-clusterfork');\nconst createServer = require('http').createServer;\n\nconst server = createServer((req, res) =\u003e {\n  res.end(`Hello from process ${process.pid}`);\n});\n\nclusterfork(() =\u003e server.listen(3000), { verbose: true });\n```\n\nThe above example starts a clustered server listening on port 3000. The only\nthing done differently from normal is that instead of calling `server.listen`\ndirectly, the call is passed along as an anonymous function to\n`node-clusterfork`.\n\n### Features\n\nFor a full list of options, run `clusterfork -h`.\n\n##### Debug information\n\nYou may get debug information on the state of the master process and the\nworkers by using the `-v / --verbose` flag.\n\n##### Number of workers\n\nThe default behaviour of `node-clusterfork` is to create a one-to-one mapping\nto your CPU cores, thus creating 8 workers if you have 8 cores. You may\noverride this behaviour with the `-c / --concurrency` option, e.g.:\n\n    clusterfork server.js --concurrency $WEB_CONCURRENCY\n\n##### Automatic restart\n\nIf you do not wish `node-clusterfork` to restart workers automatically if they\ndie, use the `-n / --no-refork` flag. Note that this option is called `refork`\n(not `noRefork`) when passing options as an object to the `clusterfork`\nfunction.\n\n### Interactive example\n\nCopy the following code to a file named `server.js`:\n\n```javascript\n'use strict';\nconst createServer = require('http').createServer;\n\ncreateServer((req, res) =\u003e {\n  res.end(`Hello from process ${process.pid}`);\n}).listen(3000);\n```\n\nYou can now run the server normally with `node server.js`. Opening\n`http://localhost:3000` you should see something like this:\n\n    Hello from process 12345\n\nIn this example, `12345` is the\n[PID](https://en.wikipedia.org/wiki/Process_identifier) of the server. You can\nkill it by running `kill -9 12345`. If you refresh the page, you'll see that\nyou'll get no response.\n\nNow, assuming you have installed `node-clusterfork` globally, you can run the\nserver like this:\n\n    clusterfork server.js -v\n\nYou will see the PIDs of the workers in the console (due to `-v`) and if you\nopen `http://localhost:3000` in the browser, you will get a hello message as\nbefore.\n\nYou can see how `node-clusterfork` restarts processes as they die by killing\nthe process specified in the browser. If you refresh the page, you'll get a new\nPID, from one of the other workers or the newly created one.\n\n### Why\n\nNode.js is single-threaded and cannot take advantage of multiple cores by\ndefault. It also has a low hard memory limit. To take full advantage of all \nresources, you must fork processes, also called clustering. This can be done\nvia [Node.js cluster API](https://nodejs.org/api/cluster.html#cluster_cluster)\nor by using a library such as `clusterfork`.\n\nIn many cases there is no need for custom logic to implement clustering. By\nusing `clusterfork` you can avoid modifying your app's entry point with\nclustering boilerplate and try out different configurations with ease. The\noptimal clustering configuration is highly dependent on the server's resources.\nHeroku has some\n[examples](https://devcenter.heroku.com/articles/node-concurrency#defaults) of\nsane numbers of workers for clustering on their various server types.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhph%2Fclusterfork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhph%2Fclusterfork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhph%2Fclusterfork/lists"}