module Daemons
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 scripts 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 newApplication
object as a return value. -
Daemons.daemonize(options)
:Daemonize
the currently runnig process, i.e. the calling process will become a daemon.
What does daemons internally do with my daemons?¶ ↑
- or
-
why do my daemons crash when they try to open a file?
- or
-
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
How do PidFiles work? Where are they stored?¶ ↑
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.
Constants
- VERSION
Public Class Methods
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.
app_name
-
The name of the application.
options
-
A hash that may contain one or more of the options listed below
block
-
The block to call in the daemon.
Options:¶ ↑
:multiple
-
Specifies whether multiple instances of the same script are allowed to run at the same time
:monitor
-
Monitor
the programs and restart crashed instances :monitor_interval
-
Interval in sesconds at which to check whether the instances are still running
: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
Example:¶ ↑
options = { :app_name => "myproc", :backtrace => true, :monitor => true, :ontop => true } Daemons.call(options) begin # Server loop: loop { conn = accept_conn() serve(conn) } end
# File lib/daemons.rb, line 242 def call(options = {}, &block) new_app = Daemons.new(options, &block) new_app.start new_app end
Return the internal Controller
instance.
# File lib/daemons.rb, line 321 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
Options:¶ ↑
: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
: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.
:dir_mode
-
Either
:script
(the directory for writing files to given by:dir
is interpreted relative to the script location given byscript
, the default) or:normal
(the directory given by:dir
is interpreted as a (absolute or relative) path) or:system
(/var/run
is used as the file directory) :dir
-
Used in combination with
:dir_mode
(description above) :log_dir
-
A specific directory to put the log files into (when not given, resort to the default location as derived from the :dir_mode and :dir options
:log_output
-
When given (i.e. set to true), redirect both $stdout and $stdout to a logfile named ‘[app_name].output’ in the pid-file directory
:log_output_syslog
-
When set to true, redirect output into SYSLOG instead of the file. This overrides log_output setting.
Example:¶ ↑
options = { :backtrace => true, :ontop => true, :log_output => true } Daemons.daemonize(options) # Server loop: loop { conn = accept_conn() puts "some text which goes to the output logfile" serve(conn) }
# File lib/daemons.rb, line 305 def daemonize(options = {}) options[:script] ||= File.basename(__FILE__) @group ||= ApplicationGroup.new(options[:app_name] || options[:script], options) @group.new_application(:mode => :none).start end
Return the internal ApplicationGroup
instance.
# File lib/daemons.rb, line 315 def group @group end
Create a new Daemon application, like Daemons.call
, but will not start it automatically
# File lib/daemons.rb, line 250 def new(options = {}, &block) fail 'Daemons.call: no block given' unless block_given? options[:app_name] ||= 'proc' options[:proc] = Proc.new(&block) options[:mode] = :proc options[:dir_mode] = :normal @group ||= ApplicationGroup.new(options[:app_name], options) @group.new_application(options) 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 withload <script>
. Also note thatDaemons
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. Your script name should not end with _monitor because that name is reserved for a monitor process which is there to restart your daemon if it crashes. options
-
A hash that may contain one or more of the options listed below
Options:¶ ↑
: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 forDaemons
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 byscript
, the default) 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
:pid_delimiter
-
Specifies the separator used when enumerating multiple process names/pid-files. Default is ‘_num’.
: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)
:shush
-
When given (i.e. set to true), turn on silent mode (no output to the terminal)
:mode
-
:load
Load the script withKernel.load
; note that :stop_proc only works for the :load (and :proc) mode.:exec
Execute the script file withKernel.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 :monitor_interval
-
Interval in sesconds at which to check whether the instances are still running
:log_dir
-
A specific directory to put the log files into (when not given, resort to the default location as derived from the :dir_mode and :dir options
:logfilename
-
Specifiy a custom log file name
:log_output
-
When given (i.e. set to true), redirect both $stdout and $stderr to a logfile named ‘[app_name].output’ (or as given in :output_logfilename) in the pid-file directory
:output_logfilename
-
Specifiy a custom output redirection file name
:log_output_syslog
-
When set to true, redirect output into SYSLOG instead of the file. This overrides log_output setting.
: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).
:stop_proc
-
A proc that will be called when the daemonized process receives a request to stop (works only for :load and :proc mode)
Example:¶ ↑
options = { :app_name => "my_app", :ARGV => ['start', '-f', '--', 'param_for_myscript'] :dir_mode => :script, :dir => 'pids', :multiple => true, :pid_delimiter => '.n', :ontop => true, :shush => false, :mode => :exec, :backtrace => true, :monitor => true, :logfilename => 'custom_logfile.log', :output_logfilename => 'custom_outputfile.txt' } Daemons.run(File.join(File.dirname(__FILE__), 'myscript.rb'), options)
# File lib/daemons.rb, line 145 def run(script, options = {}) options[:script] = script @controller = Controller.new(options, options[:ARGV] || ARGV) @controller.catch_exceptions do @controller.run end # 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 Daemons.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
Daemons.run
A block must be given to this function. The block will be used as the :proc entry in the options hash.
Example:¶ ↑
Daemons.run_proc('myproc.rb') do loop do accept_connection() read_request() send_response() close_connection() end end
# File lib/daemons.rb, line 185 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 do @controller.run end # I don't think anybody will ever use @group, as this location should not be reached under non-error conditions @group = @controller.group end
Private Instance Methods
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.
app_name
-
The name of the application.
options
-
A hash that may contain one or more of the options listed below
block
-
The block to call in the daemon.
Options:¶ ↑
:multiple
-
Specifies whether multiple instances of the same script are allowed to run at the same time
:monitor
-
Monitor
the programs and restart crashed instances :monitor_interval
-
Interval in sesconds at which to check whether the instances are still running
: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
Example:¶ ↑
options = { :app_name => "myproc", :backtrace => true, :monitor => true, :ontop => true } Daemons.call(options) begin # Server loop: loop { conn = accept_conn() serve(conn) } end
# File lib/daemons.rb, line 242 def call(options = {}, &block) new_app = Daemons.new(options, &block) new_app.start new_app end
Return the internal Controller
instance.
# File lib/daemons.rb, line 321 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
Options:¶ ↑
: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
: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.
:dir_mode
-
Either
:script
(the directory for writing files to given by:dir
is interpreted relative to the script location given byscript
, the default) or:normal
(the directory given by:dir
is interpreted as a (absolute or relative) path) or:system
(/var/run
is used as the file directory) :dir
-
Used in combination with
:dir_mode
(description above) :log_dir
-
A specific directory to put the log files into (when not given, resort to the default location as derived from the :dir_mode and :dir options
:log_output
-
When given (i.e. set to true), redirect both $stdout and $stdout to a logfile named ‘[app_name].output’ in the pid-file directory
:log_output_syslog
-
When set to true, redirect output into SYSLOG instead of the file. This overrides log_output setting.
Example:¶ ↑
options = { :backtrace => true, :ontop => true, :log_output => true } Daemons.daemonize(options) # Server loop: loop { conn = accept_conn() puts "some text which goes to the output logfile" serve(conn) }
# File lib/daemons.rb, line 305 def daemonize(options = {}) options[:script] ||= File.basename(__FILE__) @group ||= ApplicationGroup.new(options[:app_name] || options[:script], options) @group.new_application(:mode => :none).start end
Return the internal ApplicationGroup
instance.
# File lib/daemons.rb, line 315 def group @group end
Create a new Daemon application, like Daemons.call
, but will not start it automatically
# File lib/daemons.rb, line 250 def new(options = {}, &block) fail 'Daemons.call: no block given' unless block_given? options[:app_name] ||= 'proc' options[:proc] = Proc.new(&block) options[:mode] = :proc options[:dir_mode] = :normal @group ||= ApplicationGroup.new(options[:app_name], options) @group.new_application(options) 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 withload <script>
. Also note thatDaemons
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. Your script name should not end with _monitor because that name is reserved for a monitor process which is there to restart your daemon if it crashes. options
-
A hash that may contain one or more of the options listed below
Options:¶ ↑
: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 forDaemons
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 byscript
, the default) 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
:pid_delimiter
-
Specifies the separator used when enumerating multiple process names/pid-files. Default is ‘_num’.
: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)
:shush
-
When given (i.e. set to true), turn on silent mode (no output to the terminal)
:mode
-
:load
Load the script withKernel.load
; note that :stop_proc only works for the :load (and :proc) mode.:exec
Execute the script file withKernel.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 :monitor_interval
-
Interval in sesconds at which to check whether the instances are still running
:log_dir
-
A specific directory to put the log files into (when not given, resort to the default location as derived from the :dir_mode and :dir options
:logfilename
-
Specifiy a custom log file name
:log_output
-
When given (i.e. set to true), redirect both $stdout and $stderr to a logfile named ‘[app_name].output’ (or as given in :output_logfilename) in the pid-file directory
:output_logfilename
-
Specifiy a custom output redirection file name
:log_output_syslog
-
When set to true, redirect output into SYSLOG instead of the file. This overrides log_output setting.
: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).
:stop_proc
-
A proc that will be called when the daemonized process receives a request to stop (works only for :load and :proc mode)
Example:¶ ↑
options = { :app_name => "my_app", :ARGV => ['start', '-f', '--', 'param_for_myscript'] :dir_mode => :script, :dir => 'pids', :multiple => true, :pid_delimiter => '.n', :ontop => true, :shush => false, :mode => :exec, :backtrace => true, :monitor => true, :logfilename => 'custom_logfile.log', :output_logfilename => 'custom_outputfile.txt' } Daemons.run(File.join(File.dirname(__FILE__), 'myscript.rb'), options)
# File lib/daemons.rb, line 145 def run(script, options = {}) options[:script] = script @controller = Controller.new(options, options[:ARGV] || ARGV) @controller.catch_exceptions do @controller.run end # 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 Daemons.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
Daemons.run
A block must be given to this function. The block will be used as the :proc entry in the options hash.
Example:¶ ↑
Daemons.run_proc('myproc.rb') do loop do accept_connection() read_request() send_response() close_connection() end end
# File lib/daemons.rb, line 185 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 do @controller.run end # I don't think anybody will ever use @group, as this location should not be reached under non-error conditions @group = @controller.group end