Skip to content

Commit

Permalink
Quick attempt at making the deamons docs more readable.
Browse files Browse the repository at this point in the history
  • Loading branch information
@joakimk
joakimk committed Jan 23, 2010
1 parent 86260ed commit d896f99
Showing 1 changed file with 100 additions and 91 deletions.
191 changes: 100 additions & 91 deletions README → README.markdown
View file
@@ -1,4 +1,5 @@
= Quick'n'dirty Daemons Version 1.0.10 gem with fix by Chris Kline and additions by Michael Hale
Quick'n'dirty Daemons Version 1.0.10 gem with fix by Chris Kline and additions by Michael Hale
====

This is a clean import of Daemons 1.0.10, with the following changes:

Expand All @@ -7,11 +8,13 @@ This is a clean import of Daemons 1.0.10, with the following changes:
# Includes ability to change the process uid/gid.
# logdir can be specified seperate from piddir.

= Daemons Version 1.0.10
Daemons Version 1.0.10
====

(See Releases for release-specific information)

== What is Daemons?
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>.
Expand All @@ -26,176 +29,181 @@ if they crash.
Daemons includes the <tt>daemonize.rb</tt> script written by <i>Travis Whitton</i> to do the daemonization
process.

== Basic Usage
Basic Usage
====

You can use Daemons in four differet ways:

=== 1. Create wrapper scripts for your server scripts or applications
### 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
# 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
# this is myserver_control.rb

require 'rubygems' # if you use RubyGems
require 'daemons'
require 'rubygems' # if you use RubyGems
require 'daemons'

Daemons.run('myserver.rb')
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
$ 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
$ 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
$ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument


=== 2. Create wrapper scripts that include your server procs
### 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
# 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
# this is myproc_control.rb

require 'rubygems' # if you use RubyGems
require 'daemons'
require 'rubygems' # if you use RubyGems
require 'daemons'

Daemons.run_proc('myproc.rb') do
loop do
sleep(5)
Daemons.run_proc('myproc.rb') do
loop do
sleep(5)
end
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
$ 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
$ ruby myproc_control.rb run

=== 3. Control a bunch of daemons from another application
### 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
# this is my_app.rb

require 'rubygems' # if you use RubyGems
require 'daemons'
require 'rubygems' # if you use RubyGems
require 'daemons'

task1 = Daemons.call(:multiple => true) do
# first server task
task1 = Daemons.call(:multiple => true) do
# first server task

loop {
conn = accept_conn()
serve(conn)
}
end
loop {
conn = accept_conn()
serve(conn)
}
end

task2 = Daemons.call do
# second server task
task2 = Daemons.call do
# second server task

loop {
something_different()
}
end
loop {
something_different()
}
end

# the parent process continues to run
# the parent process continues to run

# we can even control our tasks, for example stop them
task1.stop
task2.stop
# we can even control our tasks, for example stop them
task1.stop
task2.stop

exit
exit

=== 4. Daemonize the currently running process
### 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
# this is my_daemons.rb

require 'rubygems' # if you use RubyGems
require 'daemons'
require 'rubygems' # if you use RubyGems
require 'daemons'

# Initialize the app while we're not a daemon
init()
# Initialize the app while we're not a daemon
init()

# Become a daemon
Daemons.daemonize
# Become a daemon
Daemons.daemonize

# The server loop
loop {
conn = accept_conn()
serve(conn)
}
# 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 and Installation
====

*Download*: just go to http://rubyforge.org/projects/daemons/
*Download*: just go to [http://rubyforge.org/projects/daemons/](http://rubyforge.org/projects/daemons/)

Installation *with* RubyGems:
$ su
# gem install daemons
$ su
# gem install daemons

Installation *without* RubyGems:
$ tar xfz daemons-x.x.x.tar.gz
$ cd daemons-x.x.x
$ su
# ruby setup.rb
$ tar xfz daemons-x.x.x.tar.gz
$ cd daemons-x.x.x
$ su
# ruby setup.rb

== Documentation
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
The RDoc documentation is also online at [http://daemons.rubyforge.org](http://daemons.rubyforge.org)


== Author
Author
====

Written in 2005-2008 by Thomas Uehlinger <mailto:th.uehlinger@gmx.ch>.

== License
License
====

Copyright (c) 2005-2008 Thomas Uehlinger

Expand Down Expand Up @@ -227,6 +235,7 @@ The Daemonize extension module is copywrited free software by Travis Whitton
<whitton@atlantic.net>. You can redistribute it under the terms specified in
the COPYING file of the Ruby distribution.

== Feedback and other resources
Feedback and other resources
====

At http://rubyforge.org/projects/daemons.
At [http://rubyforge.org/projects/daemons.](http://rubyforge.org/projects/daemons).

0 comments on commit d896f99

Please sign in to comment.