basic_daemon 0.9.0

data/README

@@ -0,0 +1,94 @@
+A basic library for creating daemonized processes
+  (c) 2009 Samuel Mullen (samullen)
+
+  http://github.com/samullen/basic_daemon
+
+This library works with Ruby 1.8, Ruby 1.9, and JRuby and is licensed under the MIT License.
+
+Gettings Started
+
+There are currently two ways of using the basic_daemon library: 1) Objected Oriented; 2) Functional.
+
+Object Oriented 
+
+The basic idea here is to subclass BasicDaemon and overwrite the "run" method.
+
+  require 'basic_daemon'
+
+  class MyDaemon < BasicDaemon
+    def run
+      foo = open("/tmp/out", "w")
+
+      i = 1
+
+      while true do
+        foo.puts "loop: #{i}"
+        foo.flush
+        sleep 2
+
+        i += 1
+      end
+    end
+  end
+
+  daemon = MyDaemon.new
+
+  if ARGV[0] == 'start'
+    daemon.start
+  elsif ARGV[0] == 'stop'
+    daemon.stop
+    exit!
+  elsif ARGV[0] == 'restart'
+    daemon.restart
+  else
+    STDERR.puts "Usage: foo_daemon.rb <start|stop|restart>"
+    exit!
+  end
+
+Functional
+
+Rather than subclassing BasicDaemon, a block is just passed to the start method.
+
+  require 'basic_daemon'
+
+  daemon = BasicDaemon.new
+
+  if ARGV[0] == 'start'
+    daemon.start do
+      foo = open("/tmp/out", "w")
+
+      i = 1
+
+      while true do
+        foo.puts "loop: #{i}"
+        foo.flush
+        sleep 2
+
+        i += 1
+      end
+    end
+  elsif ARGV[0] == 'stop'
+    daemon.stop
+    exit!
+  elsif ARGV[0] == 'restart'
+    daemon.restart
+  else
+    STDERR.puts "Usage: foo_daemon.rb <start|stop|restart>"
+    exit!
+  end
+
+Arguments
+
+BasicDaemon creates file to store the process ID (PID). By default, this file is given the same name as the calling script sans the file extension and is stored in the /tmp directory. Also by default, the directory the calling script is working in is changed to the root directory ('/').
+
+Each argument, :pidfile, :piddir, :workingdir, can be changed upon instantiation of the class. 
+
+Example:
+
+Most Linux users will want to instantiate thusly:
+
+  BasicDaemon.new(:piddir => '/var/lock')
+
+Installation
+
+pending

data/examples/functional.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/ruby
+
+# STDERR.puts "this won't work until I get the block stuff working."
+# exit
+
+require File.join(File.dirname(__FILE__), '..', 'lib','basic_daemon')
+
+basedir = "/tmp" # change this to where you want to deal with things
+pidfile = File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME))
+
+d = BasicDaemon.new({:pidfile => pidfile, :piddir => basedir, :workingdir => basedir})
+
+if ARGV[0] == 'start'
+  puts "should print 'got here' on the next line"
+  d.start do
+    i = 1
+    foo = open(basedir + "/out", "w")
+
+    while true do
+      foo.puts "loop: #{i}"
+      foo.flush
+      sleep 5
+
+      i += 1
+    end
+  end
+elsif ARGV[0] == 'stop'
+  d.stop
+  exit!
+elsif ARGV[0] == 'restart'
+  d.restart
+else
+  STDERR.puts "wrong! use start or stop."
+  exit!
+end
+
+puts 'got here'
+exit

data/examples/objectoriented.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/ruby
+
+require File.join(File.dirname(__FILE__), '..', 'lib','basic_daemon')
+require 'pp'
+
+basedir = "/tmp" # change this to where you want to deal with things
+pidfile = File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME))
+
+class MyDaemon < BasicDaemon
+  def run
+    foo = open("/tmp/out", "w")
+
+    i = 1
+
+    while true do
+      foo.puts "loop: #{i}"
+      foo.flush
+      sleep 5
+
+      i += 1
+    end
+  end
+end
+
+d = MyDaemon.new(:pidfile => pidfile, :piddir => basedir, :workingdir => basedir)
+
+if ARGV[0] == 'start'
+  puts "Should print 'got here' on the next line"
+  d.start
+elsif ARGV[0] == 'stop'
+  d.stop
+  exit!
+elsif ARGV[0] == 'restart'
+  d.restart
+else
+  STDERR.puts "wrong! use start or stop."
+  exit!
+end
+
+puts 'got here'
+exit

data/lib/basic_daemon.rb

@@ -0,0 +1,187 @@
+class BasicDaemon
+  attr_accessor :workingdir, :pidfile, :piddir, :process
+
+  VERSION = '0.9.0'
+
+  DEFAULT_OPTIONS = {
+    :pidfile => File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME)),
+    :piddir => '/tmp',
+    :workingdir => '/'
+  }
+
+  # Instantiate a new BasicDaemon
+  #
+  # Takes an optional hash with the following symbol keys:
+  # - :piddir = Directory to store the PID file in. Default is /tmp
+  # - :pidfile = name of the file to store the PID in. default is the script 
+  #   name sans extension.
+  # - :workingdir = Directory to work from. Default is "/" and should probably 
+  #   be left as such.
+  def initialize(*args)
+    opts = {}
+
+    case
+    when args.length == 0 then
+    when args.length == 1 && args[0].class == Hash then
+      arg = args.shift
+
+      if arg.class == Hash
+        opts = arg
+      end
+    else
+      raise ArgumentError, "new() expects hash or hashref as argument"
+    end
+
+    opts = DEFAULT_OPTIONS.merge opts
+
+    @piddir     = opts[:piddir]
+    @pidfile    = opts[:pidfile]
+    @workingdir = opts[:workingdir]
+    @pid        = nil
+    @process    = nil
+  end
+
+  # Returns the fullpath to the file containing the process ID (PID)
+  def pidpath
+    File.join(@piddir, @pidfile)
+  end
+
+  # Returns the PID of the currently running daemon
+  def pid
+    return @pid unless @pid.nil?
+
+    begin
+      @pid = open(self.pidpath, 'r').read.to_i
+    rescue Errno::EACCES => e
+      STDERR.puts "Error: unable to open file #{self.pidpath} for reading:\n\t"+
+        "(#{e.class}) #{e.message}"
+      exit!
+    rescue => e
+    end
+
+    @pid
+  end
+
+  # Starts the daemon by forking the supplied process either by block or by 
+  # overridden run method.
+  def start(&block)
+    if pid
+      STDERR.puts "pidfile #{self.pidpath} with pid #{@pid} already exists. " +
+        "Make sure this daemon is not already running."
+      exit!
+    end
+
+    if block_given?
+      @process = block
+    end
+
+    #----- Fork off from the calling process -----#
+    begin
+      fork do
+        Process.setsid #----- make forked process session leader
+        fork && exit!
+
+        at_exit do
+          delpidfile
+        end
+
+        Dir::chdir(@workingdir) #----- chdir to working directory
+        File::umask(0) #----- clear out file mode creation mask
+
+        begin
+          open(self.pidpath, "w") do |f|
+            @pid = Process.pid
+            f.puts @pid
+          end
+        rescue => e
+          STDERR.puts "Error: Unable to open #{self.pidpath} for writing:\n\t" +
+            "(#{e.class}) #{e.message}"
+          exit!
+        end
+
+        STDIN.reopen("/dev/null", 'r')
+        STDOUT.reopen("/dev/null", "w")
+        STDERR.reopen("/dev/null", "w")
+
+        unless @process.nil?
+          @process.call
+        else
+          self.run
+        end
+      end
+    rescue => e
+      STDERR.puts "Error: Failed to fork properly: \n\t: " +
+        "(#{e.class}) #{e.message}"
+      exit!
+    end
+  end
+  
+  # stops the daemon. It does this by retrieving the process ID (PID) of the 
+  # currently running process from the pidfile and killing it till it's dead.
+  def stop
+    unless self.pid
+      STDERR.puts "pidfile #{self.pidpath} does not exist. Daemon not running?\n"
+      return # not an error in a restart
+    end
+
+    begin
+      while true do
+        Process.kill("TERM", self.pid)
+        sleep(0.1)
+      end
+    rescue Errno::ESRCH # gets here when there is no longer a process to kill
+    rescue => e
+      STDERR.puts "unable to terminate process: (#{e.class}) #{e.message}"
+      exit!
+    end
+  end
+
+  # restarts the daemon by first killing it and then restarting. 
+  #
+  # Warning: does not work if block is initially passed to start.
+  def restart
+    self.stop
+    @pid = nil
+
+    unless @process.nil?
+      self.start
+    else
+      self.start &@process
+    end
+  end
+
+  # Boolean. Does the current process exist? True or false.
+  # Reads the PID from the pidfile and attempts to "kill 0" the process.
+  # Success results in true; failure, false.
+  def process_exists?
+    begin
+      Process.kill(0, self.pid)
+      true
+    rescue Errno::ESRCH, TypeError # "PID is NOT running or is zombied
+      false
+    rescue Errno::EPERM
+      STDERR.puts "No permission to query #{pid}!";
+    rescue => e
+      STDERR.puts "(#{e.class}) #{e.message}:\n\t" << 
+        "Unable to determine status for #{pid}."
+    end
+  end
+
+  # run should be overridden if using BasicDaemon Object Orientedly. 
+  # See examples.
+  def run
+  end
+
+  private
+
+  #----------------------------------------------------------------------------#
+  def delpidfile
+    begin
+      File.unlink(self.pidpath)
+    rescue => e
+      STDERR.puts "ERROR: Unable to unlink #{self.pidpath}:\n\t" +
+        "(#{e.class}) #{e.message}"
+      exit
+    end
+  end
+end

data/test/basic_daemon_settings_test.rb

@@ -0,0 +1,72 @@
+require 'test/unit'
+
+require File.join(File.dirname(__FILE__), '..', 'lib','basic_daemon')
+
+class TestBasicDaemon < Test::Unit::TestCase
+  def setup
+    @daemon = BasicDaemon.new
+  end
+
+  def test_should_default_pidfile_to_program_name
+    file_sans_ext = File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME))
+    message = "#{@daemon.pidfile} and #{file_sans_ext} are not equal"
+
+    assert_equal @daemon.pidfile, file_sans_ext, message
+  end
+
+  def test_should_default_piddir_to_tmp
+    message = "PID Directory #{@daemon.piddir} should default to '/tmp'"
+
+    assert_equal @daemon.piddir, "/tmp", message
+  end
+
+  def test_should_default_working_directory_to_root
+    message = "Working Directory #{@daemon.workingdir} should default to '/'"
+
+    assert_equal @daemon.workingdir, "/", message
+  end
+
+  def test_update_of_pidfile
+    message = "PID File should be set to 'foo.txt'"
+    new_pidfile = 'foo.txt'
+
+    @daemon.pidfile = new_pidfile
+    assert_equal @daemon.pidfile, new_pidfile, message
+    assert_equal @daemon.pidpath, "/tmp/#{new_pidfile}", message
+  end
+
+  def test_pid_method_should_return_nil
+    assert_nil @daemon.pid
+  end
+end
+
+class TestWithSuppliedValues < Test::Unit::TestCase
+  def setup
+    @daemon = BasicDaemon.new({:pidfile => 'foo', :piddir => '/var/lock', :workingdir => '/var/lock'})
+  end
+
+  def test_should_default_pidfile_to_foo
+    message = "#{@daemon.pidfile} and 'foo' are not equal"
+
+    assert_equal @daemon.pidfile, "foo", message
+  end
+
+  def test_should_default_piddir_to_varlock
+    message = "PID Directory #{@daemon.piddir} should default to '/var/lock'"
+
+    assert_equal @daemon.piddir, "/var/lock", message
+  end
+
+  def test_should_default_piddir_to_varlockfoo
+    message = "PID Path #{@daemon.pidpath} should default to '/var/lock/foo'"
+
+    assert_equal @daemon.pidpath, "/var/lock/foo", message
+  end
+
+  def test_should_default_working_directory_to_varlock
+    message = "Working Directory #{@daemon.workingdir} should default to '/var/lock'"
+
+    assert_equal @daemon.workingdir, "/var/lock", message
+  end
+end
+

data/test/functional_basic_daemon_test.rb

@@ -0,0 +1,76 @@
+require 'test/unit'
+
+require File.join(File.dirname(__FILE__), '..', 'lib','basic_daemon')
+
+class TestFunctionalBasicDaemon < Test::Unit::TestCase
+  def setup
+    @daemon = BasicDaemon.new
+
+    @process = Proc.new do
+      foo = open("/tmp/out", "w")
+
+      i = 1
+
+      while true do
+        foo.puts "loop: #{i}"
+        foo.flush
+        sleep 2
+
+        i += 1
+      end
+    end
+  end
+
+  def teardown
+    @daemon.process_exists? && @daemon.stop
+  end
+
+  def test_creation_deletion_of_pidfile
+    @daemon.start &@process
+
+    sleep 0.1 #----- give child proc time to create file
+    assert File.exists?(@daemon.pidpath), "PID file at #{@daemon.pidpath} should exist"
+    assert_match(/^\d+$/, File.open(@daemon.pidpath, 'r').read, "PID should be numeric")
+
+    @daemon.stop
+    assert File.exists?(@daemon.pidpath) == false, "PID file at #{@daemon.pidpath} should not exist"
+    assert @daemon.process_exists? == false, "Process should not exist"
+  end
+
+  def test_pidfile_removal_upon_termination
+    @daemon.start &@process
+    sleep 0.1 #----- give child proc time to create file
+    pid = File.open(@daemon.pidpath, 'r').read.to_i
+
+    begin
+      while true do
+        Process.kill("TERM", pid)
+        sleep(0.1)
+      end
+    rescue Errno::ESRCH
+    end
+    assert @daemon.process_exists? == false
+
+    assert File.exists?(@daemon.pidpath) == false
+  end
+
+  def test_backgrounding_of_subclassed_daemon
+    @daemon.start &@process
+    sleep 0.1 #----- give child proc time to create file
+    assert @daemon.process_exists?
+    @daemon.stop
+    assert @daemon.process_exists? == false
+  end
+
+  def test_restart
+    @daemon.start &@process
+    sleep 0.1
+    assert @daemon.process_exists?
+    previous_pid = @daemon.pid
+
+    @daemon.restart
+    sleep 0.1
+    assert @daemon.process_exists?
+    assert previous_pid != @daemon.pid
+  end
+end

data/test/oo_basic_daemon_test.rb

@@ -0,0 +1,89 @@
+require 'test/unit'
+
+require File.join(File.dirname(__FILE__), '..', 'lib','basic_daemon')
+
+#------------------------------------------------------------------------------#
+# OO Testing
+#------------------------------------------------------------------------------#
+
+#----- Really needs to be in a helper file -----#
+class MyDaemon < BasicDaemon
+  def run
+    foo = open("/tmp/out", "w")
+
+    i = 1
+
+    while true do
+      foo.puts "loop: #{i}"
+      foo.flush
+      sleep 2
+
+      i += 1
+    end
+  end
+end
+
+class TestSubclassedBasicDaemon < Test::Unit::TestCase
+  def setup
+    @mydaemon = MyDaemon.new
+  end
+
+  def teardown
+    @mydaemon.process_exists? && @mydaemon.stop
+  end
+
+#------------------------------------------------------------------------------#
+  def test_creation_deletion_of_pidfile
+    assert_nil @mydaemon.pid, "pidfile shouldn't exist so pid should be nil."
+
+    @mydaemon.start
+    sleep 0.1 #----- give child proc time to create file
+
+    assert File.exists?(@mydaemon.pidpath), "PID file at #{@mydaemon.pidpath} should exist"
+    assert_match(/^\d+$/, File.open(@mydaemon.pidpath, 'r').read, "PID should be numeric")
+
+    @mydaemon.stop
+    assert File.exists?(@mydaemon.pidpath) == false, "PID file at #{@mydaemon.pidpath} should no longer exist"
+    assert @mydaemon.process_exists? == false, "Process should no longer exist."
+  end
+
+#------------------------------------------------------------------------------#
+  def test_pidfile_removal_upon_termination
+    @mydaemon.start
+    sleep 0.1 #----- give child proc time to create file
+
+    begin
+      while true do
+        Process.kill("TERM", @mydaemon.pid)
+        sleep(0.1)
+      end
+    rescue Errno::ESRCH
+    end
+
+    assert @mydaemon.process_exists? == false, "External termination of the process should register with the daemon."
+    assert File.exists?(@mydaemon.pidpath) == false, "pidfile should be deleted when the process is terminated externally"
+  end
+
+#------------------------------------------------------------------------------#
+  def test_backgrounding_of_subclassed_daemon
+    @mydaemon.start
+    sleep 0.1 #----- give child proc time to create file
+    assert @mydaemon.process_exists?
+    @mydaemon.stop
+    assert @mydaemon.process_exists? == false
+  end
+
+#------------------------------------------------------------------------------#
+  def test_restart
+    @mydaemon.start
+    sleep 0.1
+    assert @mydaemon.process_exists?
+    previous_pid = @mydaemon.pid
+
+    @mydaemon.restart
+    sleep 0.1
+    assert @mydaemon.process_exists?
+    assert previous_pid != @mydaemon.pid
+  end
+end
+

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: basic_daemon
+version: !ruby/object:Gem::Version 
+  version: 0.9.0
+platform: ruby
+authors: 
+- Samuel Mullen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-18 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: "false"
+email: samullen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- examples/functional.rb
+- examples/objectoriented.rb
+- lib/basic_daemon.rb
+- test/oo_basic_daemon_test.rb
+- test/basic_daemon_settings_test.rb
+- test/functional_basic_daemon_test.rb
+has_rdoc: true
+homepage: http://github.com/samullen/basic_daemon
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A simple ruby library for daemonizing processes
+test_files: 
+- test/oo_basic_daemon_test.rb
+- test/basic_daemon_settings_test.rb
+- test/functional_basic_daemon_test.rb