diff --git a/README b/README deleted file mode 100644 index 607c206..0000000 --- a/README +++ /dev/null @@ -1,223 +0,0 @@ -= Daemons Version 1.0.11 - -(See Releases for release-specific information) - -== What is Daemons? - -Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server) -to be run as a daemon and to be controlled by simple start/stop/restart commands. - -If you want, you can also use daemons to run blocks of ruby code in a daemon process and to control -these processes from the main application. - -Besides this basic functionality, daemons offers many advanced features like exception backtracing -and logging (in case your ruby script crashes) and monitoring and automatic restarting of your processes -if they crash. - -Daemons includes the daemonize.rb script written by Travis Whitton to do the daemonization -process. - -== Basic Usage - -You can use Daemons in four differet ways: - -=== 1. Create wrapper scripts for your server scripts or applications - -Layout: suppose you have your self-written server myserver.rb: - - # this is myserver.rb - # it does nothing really useful at the moment - - loop do - sleep(5) - end - -To use myserver.rb in a production environment, you need to be able to -run myserver.rb in the _background_ (this means detach it from the console, fork it -in the background, release all directories and file descriptors). - -Just create myserver_control.rb like this: - - # this is myserver_control.rb - - require 'rubygems' # if you use RubyGems - require 'daemons' - - Daemons.run('myserver.rb') - -And use it like this from the console: - - $ ruby myserver_control.rb start - (myserver.rb is now running in the background) - $ ruby myserver_control.rb restart - (...) - $ ruby myserver_control.rb stop - -For testing purposes you can even run myserver.rb without forking in the background: - - $ ruby myserver_control.rb run - -An additional nice feature of Daemons is that you can pass additional arguments to the script that -should be daemonized by seperating them by two _hyphens_: - - $ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument - - -=== 2. Create wrapper scripts that include your server procs - -Layout: suppose you have some code you want to run in the background and control that background process -from a script: - - # this is your code - # it does nothing really useful at the moment - - loop do - sleep(5) - end - -To run this code as a daemon create myproc_control.rb like this and include your code: - - # this is myproc_control.rb - - require 'rubygems' # if you use RubyGems - require 'daemons' - - Daemons.run_proc('myproc.rb') do - loop do - sleep(5) - end - end - -And use it like this from the console: - - $ ruby myproc_control.rb start - (myproc.rb is now running in the background) - $ ruby myproc_control.rb restart - (...) - $ ruby myproc_control.rb stop - -For testing purposes you can even run myproc.rb without forking in the background: - - $ ruby myproc_control.rb run - -=== 3. Control a bunch of daemons from another application - -Layout: you have an application my_app.rb that wants to run a bunch of -server tasks as daemon processes. - - # this is my_app.rb - - require 'rubygems' # if you use RubyGems - require 'daemons' - - task1 = Daemons.call(:multiple => true) do - # first server task - - loop { - conn = accept_conn() - serve(conn) - } - end - - task2 = Daemons.call do - # second server task - - loop { - something_different() - } - end - - # the parent process continues to run - - # we can even control our tasks, for example stop them - task1.stop - task2.stop - - exit - -=== 4. Daemonize the currently running process - -Layout: you have an application my_daemon.rb that wants to run as a daemon -(but without the ability to be controlled by daemons via start/stop commands) - - # this is my_daemons.rb - - require 'rubygems' # if you use RubyGems - require 'daemons' - - # Initialize the app while we're not a daemon - init() - - # Become a daemon - Daemons.daemonize - - # The server loop - loop { - conn = accept_conn() - serve(conn) - } - - -For further documentation, refer to the module documentation of Daemons. - - -== Download and Installation - -*Download*: just go to http://rubyforge.org/projects/daemons/ - -Installation *with* RubyGems: - $ su - # gem install daemons - -Installation *without* RubyGems: - $ tar xfz daemons-x.x.x.tar.gz - $ cd daemons-x.x.x - $ su - # ruby setup.rb - -== Documentation - -For further documentation, refer to the module documentation of Daemons (click on Daemons). - -The RDoc documentation is also online at http://daemons.rubyforge.org - - -== Author - -Written in 2005-2008 by Thomas Uehlinger . - -== License - -Copyright (c) 2005-2008 Thomas Uehlinger - -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - -This license does not apply to daemonize.rb, which is was written by -Travis Whitton und published under the following license: - -The Daemonize extension module is copywrited free software by Travis Whitton -. You can redistribute it under the terms specified in -the COPYING file of the Ruby distribution. - -== Feedback and other resources - -At http://rubyforge.org/projects/daemons. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e49028 --- /dev/null +++ b/README.md @@ -0,0 +1,225 @@ +# Daemons Version 1.0.11 + +(See Releases for release-specific information) + +## What is Daemons? + +Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server) +to be _run as a daemon_ and to be _controlled by simple start/stop/restart commands_. + +If you want, you can also use daemons to _run blocks of ruby code in a daemon process_ and to control +these processes from the main application. + +Besides this basic functionality, daemons offers many advanced features like _exception backtracing_ +and logging (in case your ruby script crashes) and _monitoring_ and automatic restarting of your processes +if they crash. + +Daemons includes the daemonize.rb script written by _Travis Whitton_ to do the daemonization +process. + +## Basic Usage + +You can use Daemons in four different ways: + +### 1. Create wrapper scripts for your server scripts or applications + +Layout: suppose you have your self-written server myserver.rb: + + # this is myserver.rb + # it does nothing really useful at the moment + + loop do + sleep(5) + end + +To use myserver.rb in a production environment, you need to be able to +run myserver.rb in the _background_ (this means detach it from the console, fork it +in the background, release all directories and file descriptors). + +Just create myserver_control.rb like this: + + # this is myserver_control.rb + + require 'rubygems' # if you use RubyGems + require 'daemons' + + Daemons.run('myserver.rb') + +And use it like this from the console: + + $ ruby myserver_control.rb start + (myserver.rb is now running in the background) + $ ruby myserver_control.rb restart + (...) + $ ruby myserver_control.rb stop + +For testing purposes you can even run myserver.rb _without forking_ in the background: + + $ ruby myserver_control.rb run + +An additional nice feature of Daemons is that you can pass _additional arguments_ to the script that +should be daemonized by separating them by two _hyphens_: + + $ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument + + +### 2. Create wrapper scripts that include your server procs + +Layout: suppose you have some code you want to run in the background and control that background process +from a script: + + # this is your code + # it does nothing really useful at the moment + + loop do + sleep(5) + end + +To run this code as a daemon create myproc_control.rb like this and include your code: + + # this is myproc_control.rb + + require 'rubygems' # if you use RubyGems + require 'daemons' + + Daemons.run_proc('myproc.rb') do + loop do + sleep(5) + end + end + +And use it like this from the console: + + $ ruby myproc_control.rb start + (myproc.rb is now running in the background) + $ ruby myproc_control.rb restart + (...) + $ ruby myproc_control.rb stop + +For testing purposes you can even run myproc.rb _without forking_ in the background: + + $ ruby myproc_control.rb run + +### 3. Control a bunch of daemons from another application + +Layout: you have an application my_app.rb that wants to run a bunch of +server tasks as daemon processes. + + # this is my_app.rb + + require 'rubygems' # if you use RubyGems + require 'daemons' + + task1 = Daemons.call(:multiple => true) do + # first server task + + loop { + conn = accept_conn() + serve(conn) + } + end + + task2 = Daemons.call do + # second server task + + loop { + something_different() + } + end + + # the parent process continues to run + + # we can even control our tasks, for example stop them + task1.stop + task2.stop + + exit + +### 4. Daemonize the currently running process + +Layout: you have an application my_daemon.rb that wants to run as a daemon +(but without the ability to be controlled by daemons via start/stop commands) + + # this is my_daemons.rb + + require 'rubygems' # if you use RubyGems + require 'daemons' + + # Initialize the app while we're not a daemon + init() + + # Become a daemon + Daemons.daemonize + + # The server loop + loop { + conn = accept_conn() + serve(conn) + } + + +For further documentation, refer to the module documentation of Daemons. + + +## Download and Installation + +**Download**: just go to http://rubyforge.org/projects/daemons/ + +Installation **with** RubyGems: + + $ su + # gem install daemons + +Installation **without** RubyGems: + + $ tar xfz daemons-x.x.x.tar.gz + $ cd daemons-x.x.x + $ su + # ruby setup.rb + +## Documentation + +For further documentation, refer to the module documentation of Daemons (click on Daemons). + +The RDoc documentation is also online at http://daemons.rubyforge.org + + +## Author + +Written in 2005-2008 by Thomas Uehlinger . + +## License + +Copyright (c) 2005-2008 Thomas Uehlinger + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +This license does not apply to daemonize.rb, which is was written by +Travis Whitton and published under the following license: + +The Daemonize extension module is copywrited free software by Travis Whitton +. You can redistribute it under the terms specified in +the COPYING file of the Ruby distribution. + +## Feedback and other resources + +At http://rubyforge.org/projects/daemons.