servolux 0.10.0 → 0.11.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c744b0af533fabea800e187f1008917cf2c7aacf
+  data.tar.gz: e46bfba16ebbcfac37aa4e4d0fa44bb6e090e403
+SHA512:
+  metadata.gz: 1f8e41c57443b49a4a4ba6766daa95933e7e6a9827e759aee2284828589e29c13536041ba70e196ac945fa5cc1ee96c61124cfd0726881990634c4b4f9b32372
+  data.tar.gz: 555e8ad6764063743afca6635515f445e8e8e04b509a4143fbda4026cc9074b98d9310f36da0f37c59083f127cba8a10df44738dda4b1590d52ea9a76d83af9c

data/.gitignore

@@ -16,3 +16,5 @@ coverage
 doc
 pkg
 .yardoc
+.rvmrc
+vendor

data/.travis.yml

@@ -6,6 +6,6 @@ install:        "rake gem:install_dependencies"
 script: "rake"
 
 rvm:
-  - 1.8.7
-  - 1.9.2
-
+  - 1.9.3
+  - 2.1.5
+  - 2.2.2

data/README.md

@@ -0,0 +1,74 @@
+## Serv-O-Lux
+by Tim Pease [![](https://secure.travis-ci.org/TwP/servolux.png)](http://travis-ci.org/TwP/servolux)
+
+* [Homepage](http://rubygems.org/gems/servolux)
+* [Github Project](http://github.com/TwP/servolux)
+
+### 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 supporting both 1.8 and 1.9
+interpreters.
+
+### Features
+
+[Servolux::Threaded](http://www.rubydoc.info/github/TwP/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.
+
+[Servolux::Server](http://www.rubydoc.info/github/TwP/servolux/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](http://www.rubydoc.info/github/TwP/servolux/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](http://www.rubydoc.info/github/TwP/servolux/Servolux/Daemon)
+-- a robust class for starting and stopping daemon processes.
+
+[Servolux::Child](http://www.rubydoc.info/github/TwP/servolux/Servolux/Child)
+-- adds some much needed functionality 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](http://www.rubydoc.info/github/TwP/servolux/Servolux/Prefork)
+-- provides a pre-forking worker pool for executing tasks in parallel using
+multiple processes.
+
+All the documentation is available online at http://rdoc.info/projects/TwP/servolux
+
+### Install
+
+    gem install servolux
+
+### License
+
+The MIT License
+
+Copyright (c) 2015 Tim Pease
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -5,20 +5,24 @@ rescue LoadError
   abort '### please install the "bones" gem ###'
 end
 
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'servolux/version'
+
 task :default => 'spec:run'
 task 'gem:release' => 'spec:run'
 
 Bones {
   name         'servolux'
+  summary      'A collection of tools for working with processes'
   authors      'Tim Pease'
   email        'tim.pease@gmail.com'
-  url          'http://gemcutter.org/gems/servolux'
-  readme_file  'README.rdoc'
-  spec.opts << '--color' << '--format documentation'
+  url          'http://rubygems.org/gems/servolux'
+  version      Servolux::VERSION
 
-  use_gmail
+  spec.opts << '--color' << '--format documentation'
 
-  depend_on  'bones-rspec',  :development => true
-  depend_on  'bones-git',    :development => true
-  depend_on  'logging',      :development => true
+  depend_on  'bones-rspec', '~> 2.0',  :development => true
+  depend_on  'bones-git',   '~> 1.3',  :development => true
+  depend_on  'logging',     '~> 2.0',  :development => true
 }

data/examples/beanstalk.rb

@@ -25,7 +25,9 @@ module JobProcessor
   # 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'])
+    host = config[:host]
+    port = config[:port]
+    @beanstalk = Beanstalk::Pool.new(["#{host}:#{port}"])
   end
 
   # Close the connection to our beanstalk queue. This method is called once
@@ -65,7 +67,13 @@ module JobProcessor
 end
 
 # Create our preforking worker pool. Each worker will run the code found in
-# the JobProcessor module. We set a timeout of 10 minutes. The child process
+# the JobProcessor module.
+#
+# The `:config` Hash is passed to each worker when it is created. The values
+# here are available to the JobProcessor module. We use this config hash to pass
+# the `:host` and `:port` where the beanstalkd server can be found.
+#
+# We set a timeout of 10 minutes for the worker pool. The child process
 # must send a "heartbeat" message to the parent within this timeout period;
 # otherwise, the parent will halt the child process.
 #
@@ -75,7 +83,10 @@ end
 #
 # This also means that if any job processed by a worker takes longer than 10
 # minutes to run, that child worker will be killed.
-pool = Servolux::Prefork.new(:timeout => 600, :module => JobProcessor)
+pool = Servolux::Prefork.new \
+  :timeout => 600,
+  :module => JobProcessor,
+  :config => {:host => '127.0.0.1', :port => 11300}
 
 # Start up 7 child processes to handle jobs
 pool.start 7

data/examples/server_beanstalk.rb

@@ -32,7 +32,9 @@ 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 = Servolux::Prefork.new \
+      :module => JobProcessor,
+      :config => {:host => '127.0.0.1', :port => 11300}
     @pool.start 7
   end
 
@@ -57,7 +59,9 @@ end
 # See the beanstalk.rb example for an explanation of the JobProcessor
 module JobProcessor
   def before_executing
-    @beanstalk = Beanstalk::Pool.new(['localhost:11300'])
+    host = config[:host]
+    port = config[:port]
+    @beanstalk = Beanstalk::Pool.new(["#{host}:#{port}"])
   end
 
   def after_executing

data/lib/servolux.rb

@@ -1,4 +1,3 @@
-
 module Servolux
 
   # :stopdoc:
@@ -9,14 +8,6 @@ module Servolux
   # Generic Servolux Error class.
   Error = Class.new(StandardError)
 
-  # Returns the version string for the library.
-  #
-  # @return [String]
-  #
-  def self.version
-    @version ||= File.read(path('version.txt')).strip
-  end
-
   # Returns the library path for the module. If any arguments are given,
   # they will be joined to the end of the library path using
   # <tt>File.join</tt>.
@@ -47,7 +38,7 @@ module Servolux
 
 end
 
-%w[threaded server piper daemon child prefork].each do |lib|
+%w[version threaded server piper daemon child prefork].each do |lib|
   require Servolux.libpath('servolux', lib)
 end
 

data/lib/servolux/child.rb

@@ -121,7 +121,7 @@ class Servolux::Child
     end
 
     kill if alive?
-    @io.close rescue nil
+    @io.close unless @io.nil? || @io.closed?
     @io = nil
     self
   end

data/lib/servolux/daemon.rb

@@ -126,7 +126,7 @@ class Servolux::Daemon
   #   still being used by the parent process. This prevents zombie processes.
   #
   # @option opts [Numeric, String, Array<String>, Proc, Method, Servolux::Server] :shutdown_command (nil)
-  #   Assign the startup command. Different calling semantics are used for
+  #   Assign the shutdown command. Different calling semantics are used for
   #   each type of command.
   #
   # @option opts [String] :log_file (nil)
@@ -363,9 +363,9 @@ private
 
     skip = [STDIN, STDOUT, STDERR]
     skip << @piper.socket if @piper
-    ObjectSpace.each_object(IO) { |obj|
-      next if skip.include? obj
-      obj.close rescue nil
+    ObjectSpace.each_object(IO) { |io|
+      next if skip.include? io
+      io.close unless io.closed?
     }
 
     before_exec.call if before_exec.respond_to? :call

data/lib/servolux/piper.rb

@@ -1,4 +1,3 @@
-
 require 'socket'
 
 # == Synopsis
@@ -55,7 +54,7 @@ class Servolux::Piper
   # Creates a new Piper with the child process configured as a daemon. The
   # +pid+ method of the piper returns the PID of the daemon process.
   #
-  # Be default a daemon process will release its current working directory
+  # By default a daemon process will release its current working directory
   # and the stdout/stderr/stdin file descriptors. This allows the parent
   # process to exit cleanly. This behavior can be overridden by setting the
   # _nochdir_ and _noclose_ flags to true. The first will keep the current
@@ -154,7 +153,7 @@ class Servolux::Piper
   # @return [Piper] self
   #
   def close
-    @socket.close rescue nil
+    @socket.close unless @socket.closed?
     self
   end
 
@@ -173,7 +172,7 @@ class Servolux::Piper
   #
   def readable?
     return false if @socket.closed?
-    r,w,e = Kernel.select([@socket], nil, nil, @timeout) rescue nil
+    r,_,_ = Kernel.select([@socket], nil, nil, @timeout) rescue nil
     return !(r.nil? or r.empty?)
   end
 
@@ -184,7 +183,7 @@ class Servolux::Piper
   #
   def writeable?
     return false if @socket.closed?
-    r,w,e = Kernel.select(nil, [@socket], nil, @timeout) rescue nil
+    _,w,_ = Kernel.select(nil, [@socket], nil, @timeout) rescue nil
     return !(w.nil? or w.empty?)
   end
 

data/lib/servolux/prefork.rb

@@ -141,6 +141,7 @@ class Servolux::Prefork
   attr_accessor :timeout     # Communication timeout in seconds.
   attr_accessor :min_workers # Minimum number of workers
   attr_accessor :max_workers # Maximum number of workers
+  attr_accessor :config      # Worker configuration options (a Hash)
 
   # call-seq:
   #    Prefork.new { block }
@@ -171,6 +172,7 @@ class Servolux::Prefork
     @module = opts.fetch(:module, nil)
     @max_workers = opts.fetch(:max_workers, nil)
     @min_workers = opts.fetch(:min_workers, nil)
+    @config = opts.fetch(:config, {})
     @module = Module.new { define_method :execute, &block } if block
     @workers = []
 
@@ -245,7 +247,7 @@ class Servolux::Prefork
   def add_workers( number = 1 )
     number.times do
       break if at_max_workers?
-      worker = Worker.new( self )
+      worker = Worker.new(self, @config)
       worker.extend @module
       worker.start
       @workers << worker
@@ -360,12 +362,16 @@ private
 
     attr_reader :error
 
+    attr_reader :config
+
     # Create a new worker that belongs to the _prefork_ pool.
     #
     # @param [Prefork] prefork The prefork pool that created this worker.
+    # @param [Hash] config The worker configuration options.
     #
-    def initialize( prefork )
+    def initialize( prefork, config )
       @timeout = prefork.timeout
+      @config = config
       @thread = nil
       @piper = nil
       @error = nil

data/lib/servolux/server.rb

@@ -190,9 +190,9 @@ class Servolux::Server
     }
 
     begin
+      trap_signals
       create_pid_file
       start
-      trap_signals
       join
       wait_for_shutdown if wait
     ensure
@@ -266,10 +266,19 @@ class Servolux::Server
 
   def trap_signals
     SIGNALS.each do |sig|
-      m = sig.downcase.to_sym
-      Signal.trap(sig) { self.send(m) rescue nil } if self.respond_to? m
+      method = sig.downcase.to_sym
+      if self.respond_to? method
+        Signal.trap(sig) do
+          Thread.new do
+            begin
+              self.send(method)
+            rescue StandardError => err
+              logger.error "Exception in signal handler: #{method}"
+              logger.error err
+            end
+          end
+        end
+      end
     end
   end
-
 end
-

data/lib/servolux/threaded.rb

@@ -152,6 +152,27 @@ module Servolux::Threaded
     _activity_thread.interval
   end
 
+  # Signals the activity thread to treat the sleep interval with strict
+  # semantics. The time it takes for the 'run' method to execute will be
+  # subtracted from the sleep interval.
+  #
+  # If the sleep interval is 60 seconds and the 'run' method takes 2.2 seconds
+  # to execute, then the activity thread will sleep for 57.2 seconds. The
+  # subsequent invocation of the 'run' will occur as close as possible to 60
+  # seconds after the previous invocation.
+  #
+  def use_strict_interval=( value )
+    _activity_thread.use_strict_interval = (value ? true : false)
+  end
+
+  # When true, the activity thread will treat the sleep interval with strict
+  # semantics. See the setter method for an in depth explanation.
+  #
+  def use_strict_interval
+    _activity_thread.use_strict_interval
+  end
+  alias :use_strict_interval? :use_strict_interval
+
   # Sets the maximum number of invocations of the threaded object's
   # 'run' method
   #
@@ -199,11 +220,11 @@ module Servolux::Threaded
 
   # :stopdoc:
   def _activity_thread
-    @_activity_thread ||= ::Servolux::Threaded::ThreadContainer.new(60, 0, nil, false);
+    @_activity_thread ||= ::Servolux::Threaded::ThreadContainer.new(60, false, 0, nil, false);
   end  # @private
 
   # @private
-  ThreadContainer = Struct.new( :interval, :iterations, :maximum_iterations, :continue_on_error, :thread, :running ) {
+  ThreadContainer = Struct.new( :interval, :use_strict_interval, :iterations, :maximum_iterations, :continue_on_error, :thread, :running ) {
     def start( threaded )
       self.running = true
       self.iterations = 0
@@ -219,6 +240,7 @@ module Servolux::Threaded
     def run( threaded )
       loop do
         begin
+          mark_time
           break unless running?
           threaded.run
 
@@ -230,7 +252,7 @@ module Servolux::Threaded
             end
           end
 
-          sleep interval if running?
+          sleep if running?
         rescue SystemExit; raise
         rescue Exception => err
           if continue_on_error
@@ -259,6 +281,33 @@ module Servolux::Threaded
     end  # @private
 
     alias :running? :running
+
+    # Mark the start time of the run loop.
+    #
+    def mark_time
+      @mark = Time.now if use_strict_interval
+    end  # @private
+
+    # Sleep for "interval" seconds adjusting for the run time of the "run"
+    # method if the "use_strict_interval" flag is set. If the run time of the
+    # "run" method exceeds our sleep "interval", then log a warning and just
+    # use the interval as normal for this sleep period.
+    #
+    def sleep
+      time_to_sleep = interval
+
+      if use_strict_interval and interval > 0
+        diff = Time.now - @mark
+        time_to_sleep = interval - diff
+
+        if time_to_sleep < 0
+          time_to_sleep = interval
+          logger.warn "Run time [#{diff} s] exceeded strict interval [#{interval} s]"
+        end
+      end
+
+      ::Kernel.sleep time_to_sleep
+    end  # @private
   }
   # :startdoc: