servolux 0.8.1 → 0.9.0

data/History.txt

@@ -1,3 +1,13 @@
+== 0.9.0 / 2009-11-30
+
+* Minor Enhancements
+  * Moving towards yard style documentation
+  * Adding tests for the Prefork class
+* Bug Fixes
+  * Fixes for Ruby 1.9
+  * Ensuring the examples run and shutdown properly
+  * Other numerous bug fixes
+
 == 0.8.1 / 2009-11-12
 
 * 3 Bug Fixes

data/README.rdoc

@@ -31,8 +31,10 @@ 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.
 
+Servolux::Prefork -- provides a pre-forking worker pool for executing tasks in
+parallel using multiple processes.
 
-All the documentation is available online at http://codeforpeople.rubyforge.org/servolux
+All the documentation is available online at http://rdoc.info/projects/TwP/servolux
 
 === INSTALL
 

data/examples/beanstalk.rb

@@ -22,25 +22,45 @@ require 'servolux'
 require 'beanstalk-client'
 
 module JobProcessor
-  # Open a connection to our beanstalk queue
+  # Open a connection to our beanstalk queue. This method is called once just
+  # before entering the child run loop.
   def before_executing
     @beanstalk = Beanstalk::Pool.new(['localhost:11300'])
   end
 
-  # Close the connection to our beanstalk queue
+  # Close the connection to our beanstalk queue. This method is called once
+  # just after the child run loop stops and just before the child exits.
   def after_executing
     @beanstalk.close
   end
 
+  # Close the beanstalk socket when we receive SIGHUP. This allows the execute
+  # thread to return processing back to the child run loop; the child run loop
+  # will gracefully shutdown the process.
+  def hup
+    @beanstalk.close if @job.nil?
+    @thread.wakeup
+  end
+
+  # We want to do the same thing when we receive SIGTERM.
+  alias :term :hup
+
   # Reserve a job from the beanstalk queue, and processes jobs as we receive
   # them. We have a timeout set for 2 minutes so that we can send a heartbeat
   # back to the parent process even if the beanstalk queue is empty.
+  #
+  # This method is called repeatedly by the child run loop until the child is
+  # killed via SIGHUP or SIGTERM or halted by the parent.
   def execute
-    job = @beanstalk.reserve(120)
-    if job
-      # process job here ...
-      job.delete
+    @job = nil
+    @job = @beanstalk.reserve(120) rescue nil
+    if @job
+      $stdout.puts "[C] #{Process.pid} processing job #{@job.inspect}"
+      # ... do more processing here
     end
+  rescue Beanstalk::TimedOut
+  ensure
+    @job.delete rescue nil if @job
   end
 end
 
@@ -60,6 +80,11 @@ pool = Servolux::Prefork.new(:timeout => 600, :module => JobProcessor)
 # Start up 7 child processes to handle jobs
 pool.start 7
 
-# Stop when SIGINT is received.
-trap('INT') { pool.stop }
+# When SIGINT is received, kill all child process and then reap the child PIDs
+# from the proc table.
+trap('INT') {
+  pool.signal 'KILL'
+  pool.reap
+}
 Process.waitall
+

data/examples/echo.rb

@@ -48,5 +48,5 @@ pool = Servolux::Prefork.new {
 pool.start 3
 
 # Stop the child processes when SIGINT is received.
-trap('INT') { pool.stop }
+trap('INT') { pool.signal 'KILL' }
 Process.waitall

data/examples/server_beanstalk.rb

@@ -0,0 +1,84 @@
+
+require 'rubygems'
+require 'servolux'
+require 'beanstalk-client'
+require 'logger'
+
+# The END block is executed at the *end* of the script. It is here only
+# because this is the meat of the running code, and it makes the example more
+# "exemplary".
+END {
+
+# Create a new Servolux::Server and augment it with our BeanstalkWorkerPool
+# methods. The run loop will be executed every 30 seconds by this server.
+server = Servolux::Server.new('BeanstalkWorkerPool', :logger => Logger.new($stdout), :interval => 30)
+server.extend BeanstalkWorkerPool
+
+# Startup the server. The "before_starting" method will be called and the run
+# loop will begin executing. This method will not return until a SIGINT or
+# SIGTERM is sent to the server process.
+server.startup
+
+}
+
+# The worker pool is managed as a Servolux::Server instance. This allows the
+# pool to be gracefully stopped and to be monitored by the server thread. This
+# monitoring involves reaping child processes that have died and reporting on
+# errors raised by children. It is also possible to respawn dead child
+# workers, but this should be thuroughly thought through (ha, unintentional
+# alliteration) before doing so [if the CPU is thrashing, then respawning dead
+# child workers will only contribute to the thrash].
+module BeanstalkWorkerPool
+  # Before we start the server run loop, allocate our pool of child workers
+  # and prefork seven JobProcessors to pull work from the beanstalk queue.
+  def before_starting
+    @pool = Servolux::Prefork.new(:module => JobProcessor)
+    @pool.start 7
+  end
+
+  # This run loop will be called at a fixed interval by the server thread. If
+  # the pool has any child processes that have died or restarted, then the
+  # expired PIDs are reaed from the proc table. If any workers in the pool
+  # have reported an error, then display those errors on STDOUT; these are
+  # errors raised from the child process that caused the child to terminate.
+  def run
+    @pool.reap
+    @pool.each_worker { |worker|
+      $stdout.puts "[P] #{Process.pid} child error: #{worker.error.inspect}" if worker.error
+    }
+  end
+
+  # After the server run loop exits, stop all children in the pool of workers.
+  def after_stopping
+    @pool.stop
+  end
+end
+
+# See the beanstalk.rb example for an explanation of the JobProcessor
+module JobProcessor
+  def before_executing
+    @beanstalk = Beanstalk::Pool.new(['localhost:11300'])
+  end
+
+  def after_executing
+    @beanstalk.close
+  end
+
+  def hup
+    @beanstalk.close if @job.nil?
+    @thread.wakeup
+  end
+  alias :term :hup
+
+  def execute
+    @job = nil
+    @job = @beanstalk.reserve(120) rescue nil
+    if @job
+      $stdout.puts "[C] #{Process.pid} processing job #{@job.inspect}"
+    end
+  rescue Beanstalk::TimedOut
+  ensure
+    @job.delete rescue nil if @job
+  end
+end
+

data/lib/servolux/child.rb

@@ -49,23 +49,22 @@ class Servolux::Child
   # 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.
+  # @option opts [String] :command
+  #   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.
+  # @option opts [Numeric] :timeout (nil)
+  #   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.
   #
-  # * 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.
+  # @option opts [Array<String, Integer>] :signals (['TERM', 'QUIT', 'KILL'])
+  #   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.
+  # @option opts [Numeric] :suspend (4)
+  #   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[:command]
@@ -85,6 +84,14 @@ class Servolux::Child
   # 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.
   #
+  # @param [String] mode The mode flag used to open the child process via
+  #   IO#popen.
+  # @yield [IO] Execute the block of call passing in the communication pipe
+  #   with the child process.
+  # @yieldreturn Returns the result of the block.
+  # @return [IO] The communication pipe with the child process or the return
+  #   value from the block if one was given.
+  #
   def start( mode = 'r', &block )
     start_timeout_thread if @timeout
 
@@ -104,6 +111,8 @@ class Servolux::Child
   # the stored child PID is set to +nil+. The +start+ method can be safely
   # called again.
   #
+  # @return self
+  #
   def stop
     unless @thread.nil?
       t, @thread = @thread, nil
@@ -121,6 +130,12 @@ class Servolux::Child
   # global variable $? is set to a Process::Status object containing
   # information on the child process.
   #
+  # @param [Integer] flags Bit flags that will be passed to the system level
+  #   wait call. See the Ruby core documentation for Process#wait for more
+  #   information on these flags.
+  # @return [Integer, nil] The exit status of the child process or +nil+ if
+  #   the child process is not running.
+  #
   def wait( flags = 0 )
     return if @io.nil?
     Process.wait(@pid, flags)
@@ -131,6 +146,8 @@ class Servolux::Child
   # Returns +true+ if the child process is alive. Returns +nil+ if the child
   # process has not been started.
   #
+  # @return [Boolean]
+  #
   def alive?
     return if @io.nil?
     Process.kill(0, @pid)
@@ -141,6 +158,8 @@ class Servolux::Child
 
   # Returns +true+ if the child process was killed by the timeout thread.
   #
+  # @return [Boolean]
+  #
   def timed_out?
     @timed_out
   end
@@ -197,6 +216,6 @@ class Servolux::Child
     }
   end
 
-end  # class Servolux::Child
+end
 
 # EOF

data/lib/servolux/daemon.rb

@@ -1,4 +1,3 @@
-
 # == Synopsis
 # The Daemon takes care of the work of creating and managing daemon
 # processes from Ruby.
@@ -88,60 +87,56 @@ class Servolux::Daemon
   # Create a new Daemon that will manage the +startup_command+ as a deamon
   # process.
   #
-  # ==== Required
-  # * name <String>
-  #     The name of the daemon process. This name will appear in log
-  #     messages.
-  #  
-  # * logger <Logger>
-  #     The Logger instance used to output messages.
+  # @option opts [String] :name
+  #   The name of the daemon process. This name will appear in log messages.
+  #   [required]
+  #
+  # @option opts [Logger] :logger
+  #   The Logger instance used to output messages. [required]
   #
-  # * pid_file <String>
-  #     Location of the PID file. This is used to determine if the daemon
-  #     process is running, and to send signals to the daemon process.
+  # @option opts [String] :pid_file
+  #   Location of the PID file. This is used to determine if the daemon
+  #   process is running, and to send signals to the daemon process.
+  #   [required]
   #
-  # * startup_command
-  #     Assign the startup command. This can be either a String, an Array of
-  #     strings, a Proc, a bound Method, or a Servolux::Server instance.
-  #     Different calling semantics are used for each type of command. See
-  #     the setter method for more details.
+  # @option opts [String, Array<String>, Proc, Method, Servolux::Server] :startup_command
+  #   Assign the startup command. Different calling semantics are used for
+  #   each type of command. See the {Daemon#startup_command= startup_command}
+  #   method for more details. [required]
   #
-  # ==== Options
+  # @option opts [Numeric] :timeout (30)
+  #   The time (in seconds) to wait for the daemon process to either startup
+  #   or shutdown. An error is raised when this timeout is exceeded.
   #
-  # * timeout <Numeric>
-  #     The time (in seconds) to wait for the daemon process to either
-  #     startup or shutdown. An error is raised when this timeout is
-  #     exceeded. The default is 30 seconds.
+  # @option opts [Boolen] :nochdir (false)
+  #   When set to true this flag directs the daemon process to keep the
+  #   current working directory. By default, the process of daemonizing will
+  #   cause the current working directory to be changed to the root folder
+  #   (thus preventing the daemon process from holding onto the directory
+  #   inode).
   #
-  # * nochdir <Boolean>
-  #     When set to true this flag directs the daemon process to keep the
-  #     current working directory. By default, the process of daemonizing
-  #     will cause the current working directory to be changed to the root
-  #     folder (thus preventing the daemon process from holding onto the
-  #     directory inode). The default is false.
+  # @option opts [Boolen] :noclose (false)
+  #   When set to true this flag keeps the standard input/output streams from
+  #   being reopend to /dev/null when the deamon process is created. Reopening
+  #   the standard input/output streams frees the file descriptors which are
+  #   still being used by the parent process. This prevents zombie processes.
   #
-  # * noclose <Boolean>
-  #     When set to true this flag keeps the standard input/output streams
-  #     from being reopend to /dev/null when the deamon process is created.
-  #     Reopening the standard input/output streams frees the file
-  #     descriptors which are still being used by the parent process. This
-  #     prevents zombie processes. The default is false.
+  # @option opts [String, Array<String>, Proc, Method, Servolux::Server] :shutdown_command (nil)
+  #   Assign the startup command. Different calling semantics are used for
+  #   each type of command.
   #
-  # * shutdown_command
-  #     Assign the startup command. This can be either a String, an Array of
-  #     strings, a Proc, a bound Method, or a Servolux::Server instance.
-  #     Different calling semantics are used for each type of command.
+  # @option opts [String] :log_file (nil)
+  #   This log file will be monitored to determine if the daemon process has
+  #   sucessfully started.
   #
-  # * log_file <String>
-  #     This log file will be monitored to determine if the daemon process
-  #     has sucessfully started.
+  # @option opts [String, Regexp] :look_for (nil)
+  #   This can be either a String or a Regexp. It defines a phrase to search
+  #   for in the log_file. When the daemon process is started, the parent
+  #   process will not return until this phrase is found in the log file. This
+  #   is a useful check for determining if the daemon process is fully
+  #   started.
   #
-  # * look_for
-  #     This can be either a String or a Regexp. It defines a phrase to
-  #     search for in the log_file. When the daemon process is started, the
-  #     parent process will not return until this phrase is found in the log
-  #     file. This is a useful check for determining if the daemon process
-  #     is fully started. The default is nil.
+  # @yield [self] Block used to configure the daemon instance
   #
   def initialize( opts = {} )
     self.server = opts[:server] || opts[:startup_command]
@@ -173,16 +168,19 @@ class Servolux::Daemon
   #
   # If the startup command is a String or an Array of strings, then
   # Kernel#exec is used to run the command. Therefore, the string (or array)
-  # should be system level command that is either fully qualified or can be
+  # should be a system command that is either fully qualified or can be
   # found on the current environment path.
   #
   # If the startup command is a Proc or a bound Method then it is invoked
   # using the +call+ method on the object. No arguments are passed to the
   # +call+ invocoation.
   #
-  # Lastly, if the startup command is a Servolux::Server then it's +startup+
+  # Lastly, if the startup command is a Servolux::Server then its +startup+
   # method is called.
   #
+  # @param [String, Array<String>, Proc, Method, Servolux::Server] val The startup
+  # command to invoke when daemonizing.
+  #
   def startup_command=( val )
     @startup_command = val
     return unless val.is_a?(::Servolux::Server)
@@ -198,6 +196,8 @@ class Servolux::Daemon
   # Assign the log file name. This log file will be monitored to determine
   # if the daemon process is running.
   #
+  # @param [String] filename The name of the log file to monitor
+  #
   def log_file=( filename )
     return if filename.nil?
     @logfile_reader ||= LogfileReader.new
@@ -212,6 +212,8 @@ class Servolux::Daemon
   # If no phrase is given to look for, then the log file will simply be
   # watched for a change in size and a modified timestamp.
   #
+  # @param [String, Regexp] val The phrase in the log file to search for
+  #
   def look_for=( val )
     return if val.nil?
     @logfile_reader ||= LogfileReader.new
@@ -220,6 +222,8 @@ class Servolux::Daemon
 
   # Start the daemon process.
   #
+  # @return [Daemon] self
+  #
   def startup
     raise Error, "Fork is not supported in this Ruby environment." unless ::Servolux.fork?
     return if alive?
@@ -234,12 +238,15 @@ class Servolux::Daemon
     }
 
     @piper.child { run_startup_command }
+    self
   end
 
   # Stop the daemon process. If a shutdown command has been defined, it will
   # be called to stop the daemon process. Otherwise, SIGINT will be sent to
   # the daemon process to terminate it.
   #
+  # @return [Daemon] self
+  #
   def shutdown
     return unless alive?
 
@@ -260,6 +267,8 @@ class Servolux::Daemon
   # +false+ if this is not the case. The status of the process is determined
   # by sending a signal to the process identified by the +pid_file+.
   #
+  # @return [Boolean]
+  #
   def alive?
     pid = retrieve_pid
     Process.kill(0, pid)
@@ -276,11 +285,16 @@ class Servolux::Daemon
   # default signal to send is 'INT' (2). The signal can be given either as a
   # string or a signal number.
   #
+  # @param [String, Integer] signal The kill signal to send to the daemon
+  #   process
+  # @return [Daemon] self
+  #
   def kill( signal = 'INT' )
     signal = Signal.list.invert[signal] if signal.is_a?(Integer)
     pid = retrieve_pid
     logger.info "Killing PID #{pid} with #{signal}"
     Process.kill(signal, pid)
+    self
   rescue Errno::EINVAL
     logger.error "Failed to kill PID #{pid} with #{signal}: " \
                  "'#{signal}' is an invalid or unsupported signal number."
@@ -368,7 +382,7 @@ class Servolux::Daemon
 
   def wait_for_shutdown
     logger.debug "Waiting for #{name.inspect} to shutdown."
-    return if wait_for { !alive? }
+    return self if wait_for { !alive? }
     raise Timeout, "#{name.inspect} failed to shutdown in a timely fashion. " \
                    "The timeout is set at #{timeout} seconds."
   end
@@ -390,6 +404,7 @@ class Servolux::Daemon
   end
 
   # :stopdoc:
+  # @private
   class LogfileReader
     attr_accessor :filename
     attr_reader   :look_for
@@ -430,9 +445,8 @@ class Servolux::Daemon
     ensure
       @stat = s
     end
-  end  # class LogfileReader
+  end
   # :startdoc:
 
-end  # class Servolux::Daemon
+end
 
-# EOF