mlanett-daemons 1.0.13

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 "daemons/version"
+
+
+# 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.11"
+  
+  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,376 @@
+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 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.
+      pid = @pid.pid
+      begin
+        Process.kill(SIGNAL, pid)
+        while Pid.running?(pid)
+          sleep 0.1
+        end
+      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