215 lines
5.8 KiB
Plaintext
215 lines
5.8 KiB
Plaintext
= Daemons Version 1.1.8
|
|
|
|
(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 <i>run as a daemon</i> and to be <i>controlled by simple start/stop/restart commands</i>.
|
|
|
|
If you want, you can also use daemons to <i>run blocks of ruby code in a daemon process</i> and to control
|
|
these processes from the main application.
|
|
|
|
Besides this basic functionality, daemons offers many advanced features like <i>exception backtracing</i>
|
|
and logging (in case your ruby script crashes) and <i>monitoring</i> and automatic restarting of your processes
|
|
if they crash.
|
|
|
|
== 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 <tt>myserver.rb</tt>:
|
|
|
|
# this is myserver.rb
|
|
# it does nothing really useful at the moment
|
|
|
|
loop do
|
|
sleep(5)
|
|
end
|
|
|
|
To use <tt>myserver.rb</tt> in a production environment, you need to be able to
|
|
run <tt>myserver.rb</tt> in the _background_ (this means detach it from the console, fork it
|
|
in the background, release all directories and file descriptors).
|
|
|
|
Just create <tt>myserver_control.rb</tt> 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 <tt>myserver.rb</tt> <i>without forking</i> in the background:
|
|
|
|
$ ruby myserver_control.rb run
|
|
|
|
An additional nice feature of Daemons is that you can pass <i>additional arguments</i> 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 <tt>myproc_control.rb</tt> 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 <tt>myproc.rb</tt> <i>without forking</i> in the background:
|
|
|
|
$ ruby myproc_control.rb run
|
|
|
|
=== 3. Control a bunch of daemons from another application
|
|
|
|
Layout: you have an application <tt>my_app.rb</tt> 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 <tt>my_daemon.rb</tt> 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)
|
|
}
|
|
|
|
|
|
<b>For further documentation, refer to the module documentation of Daemons.</b>
|
|
|
|
|
|
== 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 2005-2010 by Thomas Uehlinger <mailto:th.uehlinger@gmx.ch>.
|
|
Anonymous SVN checkout is available with "svn checkout http://daemons.rubyforge.org/svn/".
|
|
|
|
== License
|
|
|
|
Copyright (c) 2005-2012 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.
|
|
|
|
== Feedback and other resources
|
|
|
|
At http://rubyforge.org/projects/daemons.
|