Module: Daemons

Defined in:
lib/daemons.rb,
lib/daemons/pid.rb,
lib/daemons/pidmem.rb,
lib/daemons/cmdline.rb,
lib/daemons/monitor.rb,
lib/daemons/pidfile.rb,
lib/daemons/version.rb,
lib/daemons/controller.rb,
lib/daemons/exceptions.rb,
lib/daemons/application.rb,
lib/daemons/application_group.rb

Overview

All functions and classes that Daemons provides reside in this module.

Daemons is normally invoked by one of the following four ways:

  1. 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.

  2. 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.

  3. 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.

  4. 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:

  1. Forks a child (and exits the parent process, if needed)

  2. Becomes a session leader (which detaches the program from the controlling terminal).

  3. Forks another child process and exits first child. This prevents the potential of acquiring a controlling terminal.

  4. Changes the current working directory to “/”.

  5. Clears the file creation mask (sets umask to 0000).

  6. 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.

Defined Under Namespace

Classes: Application, ApplicationGroup, CmdException, Controller, Error, Exception, Monitor, Optparse, Pid, PidFile, PidMem, RuntimeException, SystemError, TimeoutError

Constant Summary collapse

VERSION = 
"1.1.11"

Class Method Summary collapse

Class Method Details

.call(options = {}, &block) ⇒ Object

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

: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



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/daemons.rb', line 236

def call(options = {}, &block)
  unless block_given?
    raise "Daemons.call: no block given"
  end
  
  options[:proc] = block
  options[:mode] = :proc
  
  options[:app_name] ||= 'proc'
  
  @group ||= ApplicationGroup.new(options[:app_name], options)
  
  new_app = @group.new_application(options)
  new_app.start

  return new_app
end

.controller ⇒ Object

Return the internal Controller instance.



310
 
# File 'lib/daemons.rb', line 310

def controller; @controller; end

.daemonize(options = {}) ⇒ Object

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 by script, 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 STDERR to a logfile named ‘[app_name].output’ in the pid-file directory

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)
}



296
297
298
299
300
301
302
 
# File 'lib/daemons.rb', line 296

def daemonize(options = {})
  options[:script] ||= File.basename(__FILE__)
  
  @group ||= ApplicationGroup.new(options[:app_name] || options[:script], options)
  
  @group.new_application(:mode => :none).start
end

.group ⇒ Object

Return the internal ApplicationGroup instance.



306
 
# File 'lib/daemons.rb', line 306

def group; @group; end

.run(script, options = {}) ⇒ Object

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. 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 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, 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

: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; note that :stop_proc only works for the :load (and :proc) mode. :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_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 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).

: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,
  :ontop      => true,
  :mode       => :exec,
  :backtrace  => true,
  :monitor    => true
}

Daemons.run(File.join(File.dirname(__FILE__), 'myscript.rb'), options)



139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/daemons.rb', line 139

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

.run_proc(app_name, options = {}, &block) ⇒ Object

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



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/daemons.rb', line 180

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