seamusabshere-daemons 1.0.11.1

data/TODO

@@ -0,0 +1,6 @@
+* write the README (2005-02-07) *DONE*
+* write some real tests (2005-02-08)
+* document the new options (2005-03-14) *DONE*
+* start/stop with --force options (2005-04-05)
+* option to give some console output on start/stop commands (2005-04-05)
+

data/daemons.gemspec

@@ -0,0 +1,44 @@
+Gem::Specification.new do |s|
+  s.name     = "daemons"
+  s.version  = "1.0.11.1"
+  s.date     = "2009-01-07"
+  s.summary  = "A toolkit to convert your script to a controllable daemon (with Chris Kline's fix)"
+  s.email    = "seamus@abshere.net"
+  s.homepage = "http://github.com/seamusabshere/daemons"
+  s.description =<<EOF
+    This is Daemons 1.0.10 with the addition of Chris Kline's fix from http://blog.rapleaf.com/dev/?p=19
+  
+    Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server) to be run as a daemon and to be controlled by simple start/stop/restart commands.
+
+    If you want, you can also use daemons to run blocks of ruby code in a daemon process and to control these processes from the main application.
+
+    Besides this basic functionality, daemons offers many advanced features like exception backtracing and logging (in case your ruby script crashes) and monitoring and automatic restarting of your processes if they crash.
+
+    Daemons includes the daemonize.rb script written by Travis Whitton to do the daemonization process.
+EOF
+  s.has_rdoc = false
+  s.authors  = [
+    "Thomas Uehlinger",
+    "Travis Whitton",
+    "Chris Kline"
+    ]
+  s.files    = [
+    "daemons.gemspec",
+    "lib/daemons/application.rb",
+    "lib/daemons/application_group.rb",
+    "lib/daemons/cmdline.rb",
+    "lib/daemons/controller.rb",
+    "lib/daemons/daemonize.rb",
+    "lib/daemons/exceptions.rb",
+    "lib/daemons/monitor.rb",
+    "lib/daemons/pid.rb",
+    "lib/daemons/pidfile.rb",
+    "lib/daemons/pidmem.rb",
+    "lib/daemons.rb",
+    "LICENSE",
+    "Rakefile",
+    "README",
+    "Releases",
+    "TODO"
+    ]
+end

data/lib/daemons.rb

@@ -0,0 +1,284 @@
+require 'optparse'
+require 'optparse/time'
+
+
+require 'daemons/pidfile'  
+require 'daemons/cmdline'
+require 'daemons/exceptions'
+require 'daemons/monitor'
+
+
+require 'daemons/application'
+require 'daemons/application_group'
+require 'daemons/controller'
+
+require 'timeout'
+
+# All functions and classes that Daemons provides reside in this module.
+#
+# Daemons is normally invoked by one of the following four ways:
+#
+# 1.  <tt>Daemons.run(script, options)</tt>:
+#     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.  <tt>Daemons.run_proc(app_name, options) { (...) }</tt>:
+#     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.
+#
+# 3.  <tt>Daemons.call(options) { block }</tt>:
+#     Execute the block in a new daemon. <tt>Daemons.call</tt> will return immediately
+#     after spawning the daemon with the new Application object as a return value.
+#
+# 4.  <tt>Daemons.daemonize(options)</tt>:
+#     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 <i>PidFiles</i> are stored.
+#
+module Daemons
+
+  VERSION = "1.0.10"
+  
+  require 'daemons/daemonize'
+  
+  
+  # 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 <tt>load <script></tt>.
+  #             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
+  #
+  # === Options:
+  # <tt>:app_name</tt>::  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.
+  # <tt>:ARGV</tt>::      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.
+  # <tt>:dir_mode</tt>::  Either <tt>:script</tt> (the directory for writing the pid files to 
+  #                       given by <tt>:dir</tt> is interpreted relative
+  #                       to the script location given by +script+) or <tt>:normal</tt> (the directory given by 
+  #                       <tt>:dir</tt> is interpreted as a (absolute or relative) path) or <tt>:system</tt> 
+  #                       (<tt>/var/run</tt> is used as the pid file directory)
+  #
+  # <tt>:dir</tt>::       Used in combination with <tt>:dir_mode</tt> (description above)
+  # <tt>:multiple</tt>::  Specifies whether multiple instances of the same script are allowed to run at the
+  #                       same time
+  # <tt>:ontop</tt>::     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)
+  # <tt>:mode</tt>::      <tt>:load</tt> Load the script with <tt>Kernel.load</tt>;
+  #                       <tt>:exec</tt> Execute the script file with <tt>Kernel.exec</tt>
+  # <tt>:backtrace</tt>:: 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
+  # <tt>:monitor</tt>::   Monitor the programs and restart crashed instances
+  # <tt>:log_output</tt>:: When given (i.e. set to true), redirect both STDOUT and STDERR to a logfile named '[app_name].output' in the pid-file directory
+  # <tt>:keep_pid_files</tt>:: When given do not delete lingering pid-files (files for which the process is no longer running).
+  # <tt>:hard_exit</tt>:: When given use exit! to end a daemons instead of exit (this will for example
+  #                       not call at_exit handlers).
+  # -----
+  # 
+  # === 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)
+  #
+  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
+  module_function :run
+  
+  
+  # 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
+  #
+  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
+  module_function :run_proc
+  
+  
+  # Execute the block in a new daemon. <tt>Daemons.call</tt> 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.
+  #
+  # === Options:
+  # <tt>:multiple</tt>::  Specifies whether multiple instances of the same script are allowed to run at the
+  #                       same time
+  # <tt>:ontop</tt>::     When given, stay on top, i.e. do not daemonize the application 
+  # <tt>:backtrace</tt>:: 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 = {
+  #     :backtrace  => true,
+  #     :monitor    => true,
+  #     :ontop      => true
+  #   }
+  #
+  #   Daemons.call(options) begin
+  #     # Server loop:
+  #     loop {
+  #       conn = accept_conn()
+  #       serve(conn)
+  #     }
+  #   end
+  #
+  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
+  module_function :call
+  
+  
+  # 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:
+  # <tt>:ontop</tt>::     When given, stay on top, i.e. do not daemonize the application 
+  # <tt>:backtrace</tt>:: 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 = {
+  #     :backtrace  => true,
+  #     :ontop      => true
+  #   }
+  #
+  #   Daemons.daemonize(options)
+  #
+  #   # Server loop:
+  #   loop {
+  #     conn = accept_conn()
+  #     serve(conn)
+  #   }
+  #
+  def daemonize(options = {})
+    @group ||= ApplicationGroup.new('self', options)
+    
+    @group.new_application(:mode => :none).start
+  end
+  module_function :daemonize
+  
+  # Return the internal ApplicationGroup instance.
+  def group; @group; end
+  module_function :group
+  
+  # Return the internal Controller instance.
+  def controller; @controller; end
+  module_function :controller
+end 

data/lib/daemons/application.rb

@@ -0,0 +1,374 @@
+require 'daemons/pidfile'
+require 'daemons/pidmem'
+
+
+module Daemons
+
+  class Application
+  
+    attr_accessor :app_argv
+    attr_accessor :controller_argv
+    
+    # the Pid instance belonging to this application
+    attr_reader :pid
+    
+    # the ApplicationGroup the application belongs to
+    attr_reader :group
+    
+    # my private options
+    attr_reader :options
+    
+    
+    SIGNAL = (RUBY_PLATFORM =~ /win32/ ? 'KILL' : 'TERM')
+    
+    
+    def initialize(group, add_options = {}, pid = nil)
+      @group = group
+      @options = group.options.dup
+      @options.update(add_options)
+      
+      @dir_mode = @dir = @script = nil
+      
+      unless @pid = pid
+        if @options[:no_pidfiles]
+          @pid = PidMem.new
+        elsif dir = pidfile_dir
+          @pid = PidFile.new(dir, @group.app_name, @group.multiple)
+        else
+          @pid = PidMem.new
+        end
+      end
+    end
+    
+    def script
+      @script || @group.script
+    end
+    
+    def pidfile_dir
+      Pid.dir(@dir_mode || @group.dir_mode, @dir || @group.dir, @script || @group.script)
+    end
+    
+    def output_logfile
+      logdir = options[:dir_mode] == :system ? '/var/log' : pidfile_dir
+      (options[:log_output] && logdir) ? File.join(logdir, @group.app_name + '.output') : nil
+    end
+    
+    def logfile
+      logdir = options[:dir_mode] == :system ? '/var/log' : pidfile_dir
+      logdir ? File.join(logdir, @group.app_name + '.log') : nil
+    end
+    
+    # this function is only used to daemonize the currently running process (Daemons.daemonize)
+    def start_none
+      unless options[:ontop]
+        Daemonize.daemonize(nil, @group.app_name) #(logfile)
+      else
+        Daemonize.simulate
+      end
+      
+      @pid.pid = Process.pid
+      
+      
+      # We need this to remove the pid-file if the applications exits by itself.
+      # Note that <tt>at_text</tt> will only be run if the applications exits by calling 
+      # <tt>exit</tt>, and not if it calls <tt>exit!</tt> (so please don't call <tt>exit!</tt>
+      # in your application!
+      #
+      at_exit {
+        begin; @pid.cleanup; rescue ::Exception; end
+        
+        # If the option <tt>:backtrace</tt> is used and the application did exit by itself
+        # create a exception log.
+        if options[:backtrace] and not options[:ontop] and not $daemons_sigterm
+          begin; exception_log(); rescue ::Exception; end
+        end
+          
+      }
+      
+      # This part is needed to remove the pid-file if the application is killed by 
+      # daemons or manually by the user.
+      # Note that the applications is not supposed to overwrite the signal handler for
+      # 'TERM'.
+      #
+      trap(SIGNAL) {
+        begin; @pid.cleanup; rescue ::Exception; end
+        $daemons_sigterm = true
+        
+        if options[:hard_exit]
+          exit!
+        else
+          exit
+        end
+      }
+    end
+    
+    def start_exec
+      if options[:backtrace]
+        puts "option :backtrace is not supported with :mode => :exec, ignoring"
+      end
+      
+      unless options[:ontop]
+        Daemonize.daemonize(output_logfile, @group.app_name)
+      else
+        Daemonize.simulate(output_logfile)
+      end
+      
+      # note that we cannot remove the pid file if we run in :ontop mode (i.e. 'ruby ctrl_exec.rb run')
+      @pid.pid = Process.pid
+        
+      ENV['DAEMONS_ARGV'] = @controller_argv.join(' ')      
+      # haven't tested yet if this is really passed to the exec'd process...
+      
+      
+      
+      Kernel.exec(script(), *(@app_argv || []))
+      #Kernel.exec(script(), *ARGV)
+    end
+    
+    def start_load
+      unless options[:ontop]
+        Daemonize.daemonize(output_logfile, @group.app_name)
+      else
+        Daemonize.simulate(output_logfile)
+      end
+      
+      @pid.pid = Process.pid
+      
+      
+      # We need this to remove the pid-file if the applications exits by itself.
+      # Note that <tt>at_text</tt> will only be run if the applications exits by calling 
+      # <tt>exit</tt>, and not if it calls <tt>exit!</tt> (so please don't call <tt>exit!</tt>
+      # in your application!
+      #
+      at_exit {
+        begin; @pid.cleanup; rescue ::Exception; end
+        
+        # If the option <tt>:backtrace</tt> is used and the application did exit by itself
+        # create a exception log.
+        if options[:backtrace] and not options[:ontop] and not $daemons_sigterm
+          begin; exception_log(); rescue ::Exception; end
+        end
+          
+      }
+      
+      # This part is needed to remove the pid-file if the application is killed by 
+      # daemons or manually by the user.
+      # Note that the applications is not supposed to overwrite the signal handler for
+      # 'TERM'.
+      #
+      trap(SIGNAL) {
+        begin; @pid.cleanup; rescue ::Exception; end
+        $daemons_sigterm = true
+        
+        if options[:hard_exit]
+          exit!
+        else
+          exit
+        end
+      }
+      
+      # Now we really start the script...
+      $DAEMONS_ARGV = @controller_argv
+      ENV['DAEMONS_ARGV'] = @controller_argv.join(' ')
+      
+      ARGV.clear
+      ARGV.concat @app_argv if @app_argv
+      
+      # TODO: begin - rescue - end around this and exception logging
+      load script()
+    end
+    
+    def start_proc
+      return unless p = options[:proc]
+    
+      myproc = proc do 
+        # We need this to remove the pid-file if the applications exits by itself.
+        # Note that <tt>at_text</tt> will only be run if the applications exits by calling 
+        # <tt>exit</tt>, and not if it calls <tt>exit!</tt> (so please don't call <tt>exit!</tt>
+        # in your application!
+        #
+        at_exit {
+          begin; @pid.cleanup; rescue ::Exception; end
+
+          # If the option <tt>:backtrace</tt> is used and the application did exit by itself
+          # create a exception log.
+          if options[:backtrace] and not options[:ontop] and not $daemons_sigterm
+            begin; exception_log(); rescue ::Exception; end
+          end
+
+        }
+
+        # This part is needed to remove the pid-file if the application is killed by 
+        # daemons or manually by the user.
+        # Note that the applications is not supposed to overwrite the signal handler for
+        # 'TERM'.
+        #
+        trap(SIGNAL) {
+          begin; @pid.cleanup; rescue ::Exception; end
+          $daemons_sigterm = true
+
+          if options[:hard_exit]
+            exit!
+          else
+            exit
+          end
+        }
+        
+        p.call()
+      end
+      
+      unless options[:ontop]
+        @pid.pid = Daemonize.call_as_daemon(myproc, output_logfile, @group.app_name)
+      else
+        Daemonize.simulate(output_logfile)
+        
+        @pid.pid = Process.pid
+        
+        myproc.call
+        
+# why did we use this??
+#         Thread.new(&options[:proc])
+
+# why did we use the code below??
+        # unless pid = Process.fork
+        #   @pid.pid = pid
+        #   Daemonize.simulate(logfile)
+        #   options[:proc].call
+        #   exit
+        # else
+        #   Process.detach(@pid.pid)
+        # end
+      end
+    end
+    
+    
+    def start
+      @group.create_monitor(@group.applications[0] || self) unless options[:ontop]  # we don't monitor applications in the foreground
+      
+      case options[:mode]
+        when :none
+          # this is only used to daemonize the currently running process
+          start_none
+        when :exec
+          start_exec
+        when :load
+          start_load
+        when :proc
+          start_proc
+        else
+          start_load
+      end
+    end
+    
+#     def run
+#       if @group.controller.options[:exec]
+#         run_via_exec()
+#       else
+#         run_via_load()
+#       end
+#     end
+#      
+#     def run_via_exec
+#       
+#     end
+#     
+#     def run_via_load
+#       
+#     end
+
+
+    # This is a nice little function for debugging purposes:
+    # In case a multi-threaded ruby script exits due to an uncaught exception
+    # it may be difficult to find out where the exception came from because
+    # one cannot catch exceptions that are thrown in threads other than the main
+    # thread.
+    #
+    # This function searches for all exceptions in memory and outputs them to STDERR
+    # (if it is connected) and to a log file in the pid-file directory.
+    #
+    def exception_log
+      return unless logfile
+      
+      require 'logger'
+      
+      l_file = Logger.new(logfile)
+      
+      # the code below finds the last exception
+      e = nil
+      
+      ObjectSpace.each_object {|o|
+        if ::Exception === o
+          e = o
+        end
+      }
+     
+      l_file.info "*** below you find the most recent exception thrown, this will be likely (but not certainly) the exception that made the application exit abnormally ***"
+      l_file.error e
+      
+      l_file.info "*** below you find all exception objects found in memory, some of them may have been thrown in your application, others may just be in memory because they are standard exceptions ***"
+      
+      # this code logs every exception found in memory
+      ObjectSpace.each_object {|o|
+        if ::Exception === o
+          l_file.error o
+        end
+      }
+      
+      l_file.close
+    end
+    
+    
+    def stop
+      if options[:force] and not running?
+        self.zap
+        return
+      end
+      
+      # Catch errors when trying to kill a process that doesn't
+      # exist. This happens when the process quits and hasn't been
+      # restarted by the monitor yet. By catching the error, we allow the
+      # pid file clean-up to occur.
+      begin
+        Process.kill(SIGNAL, @pid.pid)
+      rescue Errno::ESRCH => e
+        puts "#{e} #{@pid.pid}"
+        puts "deleting pid-file."
+      end
+      
+      # We try to remove the pid-files by ourselves, in case the application
+      # didn't clean it up.
+      begin; @pid.cleanup; rescue ::Exception; end
+      
+    end
+    
+    def zap
+      @pid.cleanup
+    end
+    
+    def zap!
+      begin; @pid.cleanup; rescue ::Exception; end
+    end
+    
+    def show_status
+      running = self.running?
+      
+      puts "#{self.group.app_name}: #{running ? '' : 'not '}running#{(running and @pid.exist?) ? ' [pid ' + @pid.pid.to_s + ']' : ''}#{(@pid.exist? and not running) ? ' (but pid-file exists: ' + @pid.pid.to_s + ')' : ''}"
+    end
+    
+    # This function implements a (probably too simle) method to detect
+    # whether the program with the pid found in the pid-file is still running.
+    # It just searches for the pid in the output of <tt>ps ax</tt>, which
+    # is probably not a good idea in some cases.
+    # Alternatives would be to use a direct access method the unix process control
+    # system.
+    #
+    def running?
+      if @pid.exist?
+        return Pid.running?(@pid.pid)
+      end
+      
+      return false
+    end
+  end
+  
+end