All functions and classes that Daemons provides reside in this module.
Daemons is normally invoked by one of the following four ways:
Daemons.run(script, options)
: This is used in wrapper-scripts
that are supposed to control other ruby scripts or external applications.
Control is completely passed to the daemons library. Such wrapper script
need to be invoked with command line options like 'start' or 'stop' to do
anything useful.
Daemons.run_proc(app_name, options) { (...) }
: This is used in
wrapper-scripts that are supposed to control a proc. Control is completely
passed to the daemons library. Such wrapper script need to be invoked with
command line options like 'start' or 'stop' to do anything useful.
Daemons.call(options) { block }
: Execute the block in a new
daemon. Daemons.call
will return immediately after spawning
the daemon with the new Application
object as a return value.
Daemons.daemonize(options)
: Daemonize the currently runnig process, i.e. the
calling process will become a daemon.
why do my daemons crash when they try to open a file?
why can I not see any output from the daemon on the console (when using for
example puts
)?
From a technical aspect of view, daemons does the following when creating a daemon:
Forks a child (and exits the parent process, if needed)
Becomes a session leader (which detaches the program from the controlling terminal).
Forks another child process and exits first child. This prevents the potential of acquiring a controlling terminal.
Changes the current working directory to "/".
Clears the file creation mask (sets umask
to 0000).
Closes file descriptors (reopens STDOUT
and
STDERR
to point to a logfile if possible).
So what does this mean for your daemons:
the current directory is '/'
you cannot receive any input from the console (for example no
gets
)
you cannot output anything from the daemons with
puts
/print
unless a logfile is used
Also, you are maybe interested in reading the documentation for the class PidFile. There you can find out about how Daemons works internally and how and where the so called PidFiles are stored.
Execute the block in a new daemon. Daemons.call
will return
immediately after spawning the daemon with the new Application object as a return value.
options
A hash that may contain one or more of the options listed below
block
The block to call in the daemon.
:multiple
Specifies whether multiple instances of the same script are allowed to run at the same time
:ontop
When given, stay on top, i.e. do not daemonize the application
:backtrace
Write a backtrace of the last exceptions to the file '[app_name].log' in the pid-file directory if the application exits due to an uncaught exception
options = { :backtrace => true, :monitor => true, :ontop => true } Daemons.call(options) begin # Server loop: loop { conn = accept_conn() serve(conn) } end
# File lib/daemons.rb, line 227 def call(options = {}, &block) unless block_given? raise "Daemons.call: no block given" end options[:proc] = block options[:mode] = :proc @group ||= ApplicationGroup.new('proc', options) new_app = @group.new_application(options) new_app.start return new_app end
Return the internal Controller instance.
# File lib/daemons.rb, line 281 def controller; @controller; end
Daemonize the currently runnig process, i.e. the calling process will become a daemon.
options
A hash that may contain one or more of the options listed below
:ontop
When given, stay on top, i.e. do not daemonize the application
:backtrace
Write a backtrace of the last exceptions to the file '[app_name].log' in the pid-file directory if the application exits due to an uncaught exception
options = { :backtrace => true, :ontop => true } Daemons.daemonize(options) # Server loop: loop { conn = accept_conn() serve(conn) }
# File lib/daemons.rb, line 269 def daemonize(options = {}) @group ||= ApplicationGroup.new('self', options) @group.new_application(:mode => :none).start end
Return the internal ApplicationGroup instance.
# File lib/daemons.rb, line 277 def group; @group; end
Passes control to Daemons. This is used in wrapper-scripts that are supposed to control other ruby scripts or external applications. Control is completely passed to the daemons library. Such wrapper script should be invoked with command line options like 'start' or 'stop' to do anything useful.
script
This is the path to the script that should be run as a daemon. Please note
that Daemons runs this script with load
<script>
. Also note that Daemons
cannot detect the directory in which the controlling script resides, so
this has to be either an absolute path or you have to run the controlling
script from the appropriate directory.
options
A hash that may contain one or more of the options listed below
:app_name
The name of the application. This will be used to contruct the name of the pid files and log files. Defaults to the basename of the script.
:ARGV
An array of strings containing parameters and switches for Daemons. This includes both parameters for Daemons itself and the controlled scripted. These are assumed to be separated by an array element '--', .e.g. ['start', 'f', '--', 'param1_for_script', 'param2_for_script']. If not given, ARGV (the parameters given to the Ruby process) will be used.
:dir_mode
Either :script
(the directory for writing the pid files to
given by :dir
is interpreted relative to the script location
given by script
) or :normal
(the directory given
by :dir
is interpreted as a (absolute or relative) path) or
:system
(/var/run
is used as the pid file
directory)
:dir
Used in combination with :dir_mode
(description above)
:multiple
Specifies whether multiple instances of the same script are allowed to run at the same time
:ontop
When given (i.e. set to true), stay on top, i.e. do not daemonize the application (but the pid-file and other things are written as usual)
:mode
:load
Load the script with Kernel.load
;
:exec
Execute the script file with Kernel.exec
:backtrace
Write a backtrace of the last exceptions to the file '[app_name].log' in the pid-file directory if the application exits due to an uncaught exception
:monitor
Monitor the programs and restart crashed instances
:log_output
When given (i.e. set to true), redirect both STDOUT and STDERR to a logfile named '[app_name].output' in the pid-file directory
:keep_pid_files
When given do not delete lingering pid-files (files for which the process is no longer running).
:hard_exit
When given use exit! to end a daemons instead of exit (this will for example not call at_exit handlers).
options = { :app_name => "my_app", :ARGV => ['start', '-f', '--', 'param_for_myscript'] :dir_mode => :script, :dir => 'pids', :multiple => true, :ontop => true, :mode => :exec, :backtrace => true, :monitor => true } Daemons.run(File.join(File.dirname(__FILE__), 'myscript.rb'), options)
# File lib/daemons.rb, line 134 def run(script, options = {}) options[:script] = script @controller = Controller.new(options, options[:ARGV] || ARGV) @controller.catch_exceptions { @controller.run } # I don't think anybody will ever use @group, as this location should not be reached under non-error conditions @group = @controller.group end
Passes control to Daemons. This function does the same as ::run except that not a script but a proc will be run as a daemon while this script provides command line options like 'start' or 'stop' and the whole pid-file management to control the proc.
app_name
The name of the application. This will be used to contruct the name of the pid files and log files. Defaults to the basename of the script.
options
A hash that may contain one or more of the options listed in the documentation for ::run
A block must be given to this function. The block will be used as the :proc entry in the options hash.
Daemons.run_proc('myproc.rb') do loop do accept_connection() read_request() send_response() close_connection() end end
# File lib/daemons.rb, line 174 def run_proc(app_name, options = {}, &block) options[:app_name] = app_name options[:mode] = :proc options[:proc] = block # we do not have a script location so the the :script :dir_mode cannot be used, change it to :normal if [nil, :script].include? options[:dir_mode] options[:dir_mode] = :normal options[:dir] = File.expand_path('.') end @controller = Controller.new(options, options[:ARGV] || ARGV) @controller.catch_exceptions { @controller.run } # I don't think anybody will ever use @group, as this location should not be reached under non-error conditions @group = @controller.group end