servolux 0.4.0 → 0.5.0

data/History.txt

@@ -1,4 +1,10 @@
-== 0.4.0 / 2009-07-01
+== 0.5.0 / 2009-06-30
+
+* 2 Minor Enchancements
+  * Added tests for the Child class
+  * Updating documentation in preperation for a release
+
+== 0.4.0 / 2009-06-29
 
 * 1 Minor Enhancement
   * Added a "Child" class for working with child processes

data/README.rdoc

@@ -4,18 +4,39 @@
 
 === DESCRIPTION:
 
-Threads : Servers : Forks : Daemons : Serv-O-Lux has them all!
+Serv-O-Lux is a collection of Ruby classes that are useful for daemon and
+process management, and for writing your own Ruby services. The code is well
+documented and tested. It works with Ruby and JRuby supporing both 1.8 and 1.9
+interpreters.
 
 === FEATURES:
 
-http://codeforpeople.rubyforge.org/servolux
+Servolux::Threaded -- when included into your own class, it gives you an
+activity thread that will run some code at a regular interval. Provides methods
+to start and stop the thread, report on the running state, and join the thread
+to wait for it to complete.
 
-=== SYNOPSIS:
+Servolux::Server -- a template server class that handles the mundane work of
+creating / deleting a PID file, reporting running state, logging errors,
+starting the service, and gracefully shutting down the service.
 
+Servolux::Piper -- an extension of the standard Ruby fork method that opens a
+pipe for communication between parent and child processes. Ruby objects are
+passed between parent and child allowing, for example, exceptions in the child
+process to be passed to the parent and raised there.
+
+Servolux::Daemon -- a robust class for starting and stopping daemon processes.
+
+Servolux::Child -- adds some much needed funtionality to child processes
+created via Ruby's IO#popen method. Specifically, a timeout thread is used to
+signal the child process to die if it does not exit in a given amount of time.
+
+
+All the documentation is available online at http://codeforpeople.rubyforge.org/servolux
 
 === INSTALL:
 
-gem install servolux
+  gem install servolux
 
 === LICENSE:
 

data/lib/servolux.rb

@@ -4,7 +4,7 @@ require 'logging'
 module Servolux
 
   # :stopdoc:
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:

data/lib/servolux/child.rb

@@ -1,5 +1,41 @@
 
+# == Synopsis
+# Manage a child process spawned via IO#popen and provide a timeout
+# mechanism to kill the process after some amount time.
 #
+# == Details
+# Ruby provides the IO#popen method to spawn a child process and return an
+# IO instance connected to the child's stdin and stdout (with stderr
+# redirected to stdout). The Servolux::Child class adds to this a timeout
+# thread that will signal the child process after some number of seconds.
+# If the child exits cleanly before the timeout expires then no signals are
+# sent to the child.
+#
+# A list of signals can be provided which will be sent in succession to the
+# child until one of them causes the child to exit. The current Ruby thread
+# suspends for a few seconds to allow each signal to be processed by the
+# child. By default these signals are SIGTERM, SIGQUIT, SIGKILL and the time
+# to wait between signals is four seconds.
+#
+# The +stop+ method is used to stop the child process (if running) and to
+# reset the state of the Child instance so that it can be started again.
+# Stopping the Child instance closes the IO between parent and child
+# process.
+#
+# The +wait+ method is used to wait for the child process to exit. The
+# Process::Status object is retrieved by the Child and stored as an instance
+# variable. The +exitstatus+ method (and the other process related methods)
+# will return non-nil values after the wait method is called.
+#
+# == Examples
+#
+#    child = Servolux::Child.new(:command => 'sleep 120', :timeout => 10)
+#    child.start
+#    child.wait
+#
+#    child.timed_out?    #=> true
+#    child.signaled?     #=> true
+#    child.exitstatus    #=> nil
 #
 class Servolux::Child
 
@@ -10,29 +46,63 @@ class Servolux::Child
   attr_reader :io
   attr_reader :pid
 
+  # Create a new Child that will execute and manage the +command+ string as
+  # a child process.
+  #
+  # ==== Options
+  # * command <String>
+  #     The command that will be executed via IO#popen.
   #
+  # * timeout <Numeric>
+  #     The number of seconds to wait before terminating the child process.
+  #     No action is taken if the child process exits normally before the
+  #     timeout expires.
   #
-  def initialize( command, opts = {} )
-    @command = command
+  # * signals <Array>
+  #     A list of signals that will be sent to the child process when the
+  #     timeout expires. The signals increase in severity with SIGKILL being
+  #     the signal of last resort.
+  #
+  # * suspend <Numeric>
+  #     The number of seconds to wait for the child process to respond to
+  #     a signal before trying the next one in the list.
+  #
+  def initialize( opts = {} )
+    @command = opts.getopt :command
     @timeout = opts.getopt :timeout
     @signals = opts.getopt :signals, %w[TERM QUIT KILL]
     @suspend = opts.getopt :suspend, 4
-    @io = @pid = @thread = @timed_out = nil
+    @io = @pid = @status = @thread = @timed_out = nil
+    yield self if block_given?
   end
 
+  # Runs the +command+ string as a subprocess; the subprocess’s
+  # standard input and output will be connected to the returned IO object.
+  # The default mode for the new file object is "r", but mode may be set to
+  # any of the modes listed in the description for class IO.
   #
+  # If a block is given, Ruby will run the +command+ as a child connected to
+  # Ruby with a pipe. Ruby’s end of the pipe will be passed as a parameter
+  # to the block. In this case the value of the block is returned.
   #
   def start( mode = 'r', &block )
     start_timeout_thread if @timeout
 
-    @io  = IO::popen @command, mode
+    @io = IO::popen @command, mode
     @pid = @io.pid
+    @status = nil
 
     return block.call(@io) unless block.nil?
-    self
+    @io
   end
 
+  # Stop the child process if it is alive. A sequence of +signals+ are sent
+  # to the process until it dies with SIGKILL being the signal of last
+  # resort.
   #
+  # After this method returns, the IO pipe to the child will be closed and
+  # the stored child PID is set to +nil+. The +start+ method can be safely
+  # called again.
   #
   def stop
     unless @thread.nil?
@@ -43,7 +113,7 @@ class Servolux::Child
 
     kill if alive?
     @io.close rescue nil
-    @io = @pid = nil
+    @io = nil
     self
   end
 
@@ -54,10 +124,12 @@ class Servolux::Child
   def wait( flags = 0 )
     return if @io.nil?
     Process.wait(@pid, flags)
-    $?.exitstatus
+    @status = $?
+    exitstatus
   end
 
-  # Returns +true+ if the child process is alive.
+  # Returns +true+ if the child process is alive. Returns +nil+ if the child
+  # process has not been started.
   #
   def alive?
     return if @io.nil?
@@ -73,10 +145,26 @@ class Servolux::Child
     @timed_out
   end
 
+  %w[coredump? exited? signaled? stopped? success? exitstatus stopsig termsig].
+  each { |method|
+    self.class_eval <<-CODE
+      def #{method}
+        return if @status.nil?
+        @status.#{method}
+      end
+    CODE
+  }
+
 
   private
 
+  # Attempt to kill the child process by sending the configured +signals+
+  # and waiting for +suspend+ seconds between each signal; this gives the
+  # child time to respond to the signal.
   #
+  # Returns +true+ if the child died. Returns +false+ if the child is still
+  # not dead after the last signal was sent. Returns +nil+ if the child was
+  # not running in the first place.
   #
   def kill
     return if @io.nil?
@@ -96,8 +184,6 @@ class Servolux::Child
     return !alive?
   end
 
-  #
-  #
   def start_timeout_thread
     @timed_out = false
     @thread = Thread.new(self) { |child|

data/lib/servolux/daemon.rb

@@ -1,3 +1,4 @@
+
 # == Synopsis
 # The Daemon takes care of the work of creating and managing daemon
 # processes from Ruby.

data/spec/child_spec.rb

@@ -0,0 +1,51 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Servolux::Child do
+
+  before :all do
+    @child = Servolux::Child.new
+  end
+
+  after :each do
+    @child.stop
+  end
+
+  it 'has some sensible defaults' do
+    @child.command.should be_nil
+    @child.timeout.should be_nil
+    @child.signals.should == %w[TERM QUIT KILL]
+    @child.suspend.should == 4
+    @child.pid.should be_nil
+    @child.io.should be_nil
+  end
+
+  it 'starts a child process' do
+    @child.command = 'echo `pwd`'
+    @child.start
+
+    @child.pid.should_not be_nil
+    @child.wait
+    @child.io.read.strip.should == Dir.pwd
+    @child.success?.should be_true
+  end
+
+  it 'kills a child process after some timeout' do
+    @child.command = 'sleep 5; echo `pwd`'
+    @child.timeout = 0.25
+    @child.start
+
+    @child.pid.should_not be_nil
+    @child.wait
+
+    @child.io.read.strip.should be_empty
+
+    @child.signaled?.should be_true
+    @child.exited?.should be_false
+    @child.exitstatus.should be_nil
+    @child.success?.should be_nil
+  end
+
+end
+
+# EOF

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: servolux
 version: !ruby/object:Gem::Version 
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors: 
 - Tim Pease
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-29 00:00:00 -06:00
+date: 2009-06-30 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,7 +42,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 2.5.0
     version: 
-description: "Threads : Servers : Forks : Daemons : Serv-O-Lux has them all!"
+description: Serv-O-Lux is a collection of Ruby classes that are useful for daemon and process management, and for writing your own Ruby services. The code is well documented and tested. It works with Ruby and JRuby supporing both 1.8 and 1.9 interpreters.
 email: tim.pease@gmail.com
 executables: []
 
@@ -61,6 +61,7 @@ files:
 - lib/servolux/piper.rb
 - lib/servolux/server.rb
 - lib/servolux/threaded.rb
+- spec/child_spec.rb
 - spec/piper_spec.rb
 - spec/server_spec.rb
 - spec/servolux_spec.rb
@@ -105,6 +106,6 @@ rubyforge_project: codeforpeople
 rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
-summary: "Threads : Servers : Forks : Daemons : Serv-O-Lux has them all!"
+summary: Serv-O-Lux is a collection of Ruby classes that are useful for daemon and process management, and for writing your own Ruby services
 test_files: []