{"id":13747370,"url":"https://github.com/shiroyasha/kamisama","last_synced_at":"2025-08-03T15:30:51.331Z","repository":{"id":56879850,"uuid":"84644657","full_name":"shiroyasha/kamisama","owner":"shiroyasha","description":"Start, monitor, and observe background worker processes, from Ruby.","archived":false,"fork":false,"pushed_at":"2017-04-08T13:29:54.000Z","size":23,"stargazers_count":56,"open_issues_count":2,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-11T19:21:34.626Z","etag":null,"topics":["background-worker","linux","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shiroyasha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-11T11:19:49.000Z","updated_at":"2024-02-24T12:22:13.000Z","dependencies_parsed_at":"2022-08-20T23:40:13.178Z","dependency_job_id":null,"html_url":"https://github.com/shiroyasha/kamisama","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/shiroyasha%2Fkamisama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiroyasha%2Fkamisama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiroyasha%2Fkamisama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiroyasha%2Fkamisama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shiroyasha","download_url":"https://codeload.github.com/shiroyasha/kamisama/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228548552,"owners_count":17935226,"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":["background-worker","linux","ruby"],"created_at":"2024-08-03T06:01:26.519Z","updated_at":"2024-12-07T02:16:18.839Z","avatar_url":"https://github.com/shiroyasha.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Kamisama\n\n[![Build Status](https://semaphoreci.com/api/v1/shiroyasha/kamisama/branches/master/badge.svg)](https://semaphoreci.com/shiroyasha/kamisama)\n\nStart, monitor, and observe background worker processes, from Ruby.\n\nBased on [Unicorn](), [God](), and [Sidekiq]().\n\n# Usage\n\nKamisama is useful for starting multiple background workers. For example, let's\nsay that you have a background worker that crunches some data with periodic\nintervals.\n\n``` ruby\ndef worker\n  loop do\n    puts \"Crunching data...\"\n\n    sleep 60\n  end\nend\n```\n\nA usual way to run this task is to wrap it in a Rake task, and an upstart script\nto keep it running forever. This is pretty well until you have one process that\nyou want to execute. However, if you want to run multiple processes, you need to\nintroduce and manage multiple upstart configurations. One upstart script that\nacts like the master who manages your workers, and upstart scripts that describe\nyour workers.\n\nThis setup is cumbersome, hard to test, and managing different configurations\nfor different environments (production, staging, development) can be outright\nfrustrating.\n\nKamisama is here to help, by abstracting away the issue of running and monitor\nmultiple background workers.\n\nLet's run 17 instances of the above worker with Kamisama:\n\n``` ruby\ndef worker(worker_index)\n  loop do\n    puts \"WORKER #{worker_index}: Crunching data...\"\n\n    sleep 60\n  end\nend\n\nKamisama.run(:instances =\u003e 17) { |index| worker(index) }\n```\n\nThat's all! The above will start(fork) 17 processes on your machine, and restart\nthem in case of failure.\n\nKeep in mind that you will still need to wrap Kamisama itself in a rake task\nand an Upstart script.\n\n### Respawn limits\n\nRespawning workers is desirable in most cases, but we would still like to avoid\nrapid restarts of your workers in a short amount of time. Such rapid restarts\ncan harm your system, and usually indicate that a serious issue is killing\nyour workers.\n\nIf the job is respawned more than `respawn_limit` times in `respawn_interval`\nseconds, Kamisama will considered this to be a deeper problem and will die.\n\n``` ruby\ndef worker(worker_index)\n  loop do\n    puts \"WORKER #{worker_index}: Crunching data...\"\n\n    sleep 60\n  end\nend\n\nconfig = {\n  :instances =\u003e 17,\n  :respawn_limit =\u003e 10,\n  :respawn_interval =\u003e 60\n}\n\nKamisama.run(config) { |index| worker(index) }\n```\n\n## Signal control\n\nYou can control your Kamisama process by sending kill signals to the running\nprocess.\n\n- [TERM](#term-signal) - terminates master process and all workers\n- [KILL](#kill-signal)  - terminates master process and all workers\n- [TTIN](#ttin-signal) - spawns a new worker\n- [TTIN](#ttou-signal) - terminates a running worker\n\n#### TERM signal\n\nIf you send a term signal to your Kamisama process, it will immediately\nshutdown. Following this, every children will be notified by the kernel that the\nmaster process has died with the TERM signal.\n\nFor example, if you have the following processes:\n\n``` bash\n2000 - PID of master process\n2001 - PID of first worker\n2002 - PID of second worker\n2003 - PID of third worker\n```\n\nThen when you send a \"TERM\" signal:\n\n``` bash\nkill -TERM 2000\n```\n\nThe master process `2000` will die immediately, and the workers processes\n(2001, 2002, 2003) will receive the `TERM` signal.\n\n#### KILL signal\n\nIf you send a kill signal to your Kamisama process, it will immediately\nshutdown. Following this, every children will be notified by the kernel that the\nmaster process has dies with the TERM signal.\n\nFor example, if you have the following processes:\n\n``` bash\n2000 - PID of master process\n2001 - PID of first worker\n2002 - PID of second worker\n2003 - PID of third worker\n```\n\nThen when you send a \"KILL\" signal:\n\n``` bash\nkill -9 2000\n```\n\nThe master process `2000` will die immediately, and the workers processes\n(2001, 2002, 2003) will receive the `TERM` signal.\n\n#### TTIN signal\n\nIf you send a ttin signal to your Kamisama process, it will spawn a new process.\n\nFor example, if you have the following processes:\n\n``` bash\n2000 - PID of master process\n2001 - PID of first worker\n2002 - PID of second worker\n2003 - PID of third worker\n```\n\nThen when you send a \"TTIN\" signal:\n\n``` bash\nkill -TTIN 2000\n```\n\nThe master process `2000` will spawn a new worker process.\n\n#### TTOU signal\n\nIf you send a ttou signal to your Kamisama process, it will kill the oldest\nworker.\n\nFor example, if you have the following processes:\n\n``` bash\n2000 - PID of master process\n2001 - PID of first worker\n2002 - PID of second worker\n2003 - PID of third worker\n```\n\nThen when you send a \"TTOU\" signal:\n\n``` bash\nkill -TTOU 2000\n```\n\nThe master process `2000` will send a `TERM` signal to the process `2001`.\n\n*NOTE*: This will only work if you have more than one running processes.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiroyasha%2Fkamisama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshiroyasha%2Fkamisama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiroyasha%2Fkamisama/lists"}