daemons 0.0.1

data/README

@@ -0,0 +1,91 @@
+= Daemons Version 0.0.1
+
+(See Releases for release-specific information)
+
+== What is Daemons?
+
+Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server) 
+to be <i>run as a daemon</i> and to be <i>controlled by simple start/stop/restart commands</i>.
+
+Daemons includes the <tt>daemonize.rb</tt> script written by <i>Travis Whitton</i> to do the daemonization
+process.
+
+== Basic Usage
+
+Layout: suppose you have your self-written server <tt>myserver.rb</tt>:
+
+  # this is myserver.rb
+  # it does nothing really useful at the moment
+  
+  loop do
+    sleep(5)
+  end
+  
+To use <tt>myserver.rb</tt> in a production environment, you need to be able to
+run <tt>myserver.rb</tt> in the _background_ (this means detach it from the console, fork it
+in the background, release any directories and file descriptors).
+
+Just create <tt>myserver_control.rb</tt> like this:
+
+  # this is myserver_control.rb
+  
+  require 'rubygems'        # if you use RubyGems
+  require 'daemons'
+  
+  Daemons.run('myserver.rb')
+  
+And use it like this from the console:
+
+  $ ruby myserver_control.rb start
+      (myserver.rb is now running in the background)
+  $ ruby myserver_control.rb restart
+      (...)
+  $ ruby myserver_control.rb stop
+  
+For testing purposes you can even run <tt>myserver.rb</tt> <i>without forking</i> in the background:
+
+  $ ruby myserver_control.rb run
+
+An additional nice feature of Daemons is that you can pass <i>additional arguments</i> to the script that 
+should be daemonized by seperating them by two _hyphens_:
+  
+  $ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument
+  
+For further documentation, refer to the module documentation of Daemons.
+
+  
+== Download and Installation
+
+*Download*: just go to http://rubyforge.org/projects/daemons/
+
+Installation *with* RubyGems:
+  $ su
+  # gem install daemons
+  
+Installation *without* RubyGems:
+  $ tar xfz daemons-x.x.x.tar.gz
+  $ cd daemons-x.x.x
+  $ su
+  # ruby setup.rb
+  
+== Documentation
+
+For further documentation, refer to the module documentation of Daemons (click on Daemons).
+
+The RDoc documentation is also online at http://daemons.rubyforge.org
+
+
+== Author
+
+Written in 2005 by Thomas Uehlinger <mailto:th.uehlinger@gmx.ch>
+
+== License
+
+The Daemons script is copywrited free software by Thomas Uehlinger
+<mailto:th.uehlinger@gmx.ch>. You can redistribute it under the terms specified in
+the COPYING file of the Ruby distribution.
+
+
+== Feedback and other resources
+
+At http://rubyforge.org/projects/daemons.

data/Rakefile

@@ -0,0 +1,71 @@
+require 'rubygems'
+Gem::manage_gems
+
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/rdoctask'
+
+$LOAD_PATH << './lib'
+require 'daemons'
+
+
+PKG_NAME = "daemons"
+
+PKG_FILES = FileList[
+  "Rakefile", "Releases", "TODO", "README", 
+  "setup.rb",
+  "lib/**/*.rb",
+  "test/**/*"
+]
+PKG_FILES.exclude(%r(^test/tmp/.+))
+
+
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  #s.version = "0.0.1"
+  s.version = Daemons::VERSION
+  s.author = "Thomas Uehlinger"
+  s.email = "th.uehlinger@gmx.ch"
+  s.homepage = "http://daemons.rubyforge.org"
+  s.platform  = Gem::Platform::RUBY
+  s.summary = "A toolkit to convert your script to a controllable daemon"
+  #s.files = FileList["{test,lib}/**/*"].exclude("rdoc").to_a
+  s.files = PKG_FILES
+  s.require_path = "lib"
+  s.autorequire = "daemons"
+  s.test_file = "test/tc_main.rb"
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "Releases", "TODO"]
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end
+
+
+#Rake::PackageTask.new("package") do |p|
+#  p.name = PKG_NAME
+#  p.version = Daemons::VERSION
+#  p.need_tar = true
+#  p.need_zip = true
+#  p.package_files = PKG_FILES
+#end
+
+ 
+task :default => [:test]
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/tc_*.rb']
+end
+
+
+desc "Create the RDOC html files"
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html'
+  rdoc.title    = "Daemons"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('README', 'TODO', 'Releases')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('test/**/*.rb')
+}

data/Releases

@@ -0,0 +1,6 @@
+= Daemons Release History
+
+== Release 0.0.1: Feb 8, 2005
+
+* Initial release
+  

data/TODO

@@ -0,0 +1,2 @@
+* write the README (2005-02-07)
+* write some real tests (2005-02-08)

data/lib/daemons.rb

@@ -0,0 +1,308 @@
+require 'optparse'
+require 'optparse/time'
+#require 'ostruct'
+
+require 'daemons/pidfile'  
+require 'daemons/cmdline'
+require 'daemons/exceptions'
+
+
+# All functions and classes that Daemons provides reside in this module.
+#
+# The function you should me most interested in is Daemons#run, because it is
+# the only function you need to invoke directly from your scripts.
+#
+# 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>Pid-Files</i> are stored.
+#
+module Daemons
+
+  VERSION = "0.0.1"
+  
+  require 'daemons/daemonize'
+   
+  
+  class Application
+  
+    attr_accessor :app_argv
+    attr_accessor :controller_argv
+    
+    attr_reader :pid_file
+    
+    
+    def initialize(group, pid_file = nil)
+      @group = group
+      
+      @pid_file = (pid_file || PidFile.new(pidfile_dir(), @group.app_name, @group.multiple))
+    end
+    
+    def script
+      @script || @group.script
+    end
+    
+    def pidfile_dir
+      PidFile.dir(@dir_mode || @group.dir_mode, @dir || @group.dir, @script || @group.script)
+    end
+    
+    def start
+      #puts "starting..."
+      
+      unless @group.controller.options[:ontop]
+        Daemonize.daemonize()
+      end
+      
+      @pid_file.write
+      
+      at_exit {
+        @pid_file.remove rescue nil
+      }
+      
+      trap('TERM') {
+        @pid_file.remove rescue nil
+        exit
+      }
+      
+      run()
+    end
+    
+    def run
+      $DAEMONS_ARGV = @controller_argv
+      
+      ARGV.clear
+      ARGV.concat @app_argv if @app_argv
+      
+      load script()
+    end
+    
+    def stop
+      Process.kill('TERM', @pid_file.read)
+      
+#       begin
+#         @pidfile.remove
+#       rescue ::Exception
+#       end
+    end
+  end
+  
+  
+  class ApplicationGroup
+  
+    attr_reader :app_name
+    attr_reader :script
+    
+    attr_reader :controller
+    
+    # True if one can start multiple instances of the application
+    #attr_reader :multiple
+    
+    #attr_reader :options
+    
+    attr_reader :applications
+    
+    attr_accessor :controller_argv
+    attr_accessor :app_argv
+    
+    attr_accessor :dir_mode
+    attr_accessor :dir
+    
+    attr_reader :multiple
+    
+    def initialize(app_name, script, controller) #multiple = false)
+      @app_name = app_name
+      @script = script
+      @controller = controller
+      
+      options = controller.options
+      
+      @multiple = options[:multiple] || false
+      
+      @dir_mode = options[:dir_mode] || :script
+      @dir = options[:dir] || ''
+      
+      #@multiple = multiple
+      
+      @applications = find_applications(pidfile_dir())
+    end
+    
+    def pidfile_dir
+      PidFile.dir(@dir_mode, @dir, script)
+    end  
+    
+    def find_applications(dir)
+      pid_files = PidFile.find_files(dir, app_name)
+      
+      #pp pid_files
+      
+      return pid_files.map {|f| Application.new(self, PidFile.existing(f))}
+    end
+    
+    def new_application(script = nil)
+      if @applications.size > 0 and not @multiple
+        raise RuntimeException.new('there is already one or more instance(s) of the program running')
+      end
+      
+      app = Application.new(self)
+      
+      app.controller_argv = @controller_argv
+      app.app_argv = @app_argv
+      
+      @applications << app
+      
+      return app
+    end
+    
+    def start_all
+      @applications.each {|a| fork { a.start } }
+    end
+    
+    def stop_all
+      @applications.each {|a| a.stop}
+    end
+  end
+
+  
+  
+  class Controller
+    
+    attr_reader :app_name
+    attr_reader :options
+    
+    
+    COMMANDS = [
+      'start',
+      'stop',
+      'restart',
+      'run'
+    ]
+    
+    def initialize(script, argv = [])
+      @argv = argv
+      @script = File.expand_path(script)
+      
+      @app_name = File.split(@script)[1]
+      
+      @command, @controller_part, @app_part = Controller.split_argv(argv)
+      
+      #@options[:dir_mode] ||= :script
+      
+      @optparse = Optparse.new(self)
+    end
+    
+    
+    def setup_options
+      #@options[:ontop] ||= true
+    end
+    
+    def run(options = {})
+      @options = options
+      
+      @options.update @optparse.parse(@controller_part).delete_if {|k,v| !v}
+      
+      setup_options()
+      
+      #pp @options
+
+      @group = ApplicationGroup.new(@app_name, @script, self) #options)
+      @group.controller_argv = @controller_part
+      @group.app_argv = @app_part
+      
+      case @command
+        when 'start'
+          @group.new_application.start
+        when 'run'
+          @group.new_application.run
+        when 'stop'
+          @group.stop_all
+        when 'restart'
+          @group.stop_all
+          sleep 1
+          @group.start_all
+        when nil
+          raise CmdException.new('no command given')
+          #puts "ERROR: No command given"; puts
+          
+          #print_usage()
+          #raise('usage function not implemented')
+        else
+          raise Error.new("not implemented command '#{@command}'")
+      end
+    end
+    
+    
+    # Split an _argv_ array.
+    # +argv+ is assumed to be in the following format:
+    #   ['command', 'controller option 1', 'controller option 2', ..., '--', 'app option 1', ...]
+    #
+    # <tt>command</tt> must be one of the commands listed in <tt>COMMANDS</tt>
+    #
+    # *Returns*: the command as a string, the controller options as an array, the appliation options
+    # as an array
+    #
+    def Controller.split_argv(argv)
+      argv = argv.dup
+      
+      command = nil
+      controller_part = []
+      app_part = []
+       
+      if COMMANDS.include? argv[0]
+        command = argv.shift
+      end
+      
+      if i = argv.index('--')
+        controller_part = argv[0..i-1]
+        app_part = argv[i+1..-1]
+      else
+        controller_part = argv[0..-1]
+      end
+       
+      return command, controller_part, app_part
+    end
+  end
+  
+  
+  # Passes control to Daemons.
+  #
+  # +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 options listed below
+  #
+  # === Options:
+  # <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 relative to the current directory) 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
+  #
+  # -----
+  # 
+  # === Example:
+  #   options = {
+  #     :dir_mode   => :script,
+  #     :dir        => 'pids',
+  #     :multiple   => true
+  #   }
+  #
+  #   Daemons.run(File.join(File.split(__FILE__)[0], 'myscript.rb'), options)
+  #
+  def run(script, options = {})
+    @controller = Controller.new(script, ARGV)
+    
+    #pp @controller
+    
+    @controller.catch_exceptions {
+      @controller.run(options)
+    }
+  end
+  module_function :run
+  
+end