servolux 0.1.0

data/lib/servolux/piper.rb

@@ -0,0 +1,274 @@
+
+# == Synopsis
+# A Piper is used to fork a child proces and then establish a communication
+# pipe between the parent and child. This communication pipe is used to pass
+# Ruby objects between the two.
+#
+# == Details
+# When a new piper instance is created, the Ruby process is forked into two
+# porcesses - the parent and the child. Each continues execution from the
+# point of the fork. The piper establishes a pipe for communication between
+# the parent and the child. This communication pipe can be opened as read /
+# write / read-write (from the perspective of the parent).
+#
+# Communication over the pipe is handled by marshalling Ruby objects through
+# the pipe. This means that nearly any Ruby object can be passed between the
+# two processes. For example, exceptions from the child process can be
+# marshalled back to the parent and raised there.
+#
+# Object passing is handled by use of the +puts+ and +gets+ methods defined
+# on the Piper. These methods use a +timeout+ and the Kernel#select method
+# to ensure a timely return.
+#
+# == Examples
+#
+#    piper = Servolux::Piper.new('r', :timeout => 5)
+#
+#    piper.parent {
+#      $stdout.puts "parent pid #{Process.pid}"
+#      $stdout.puts "child pid #{piper.pid} [from fork]"
+#
+#      child_pid = piper.gets
+#      $stdout.puts "child pid #{child_pid} [from child]"
+#
+#      msg = piper.gets
+#      $stdout.puts "message from child #{msg.inspect}"
+#    }
+#
+#    piper.child {
+#      sleep 2
+#      piper.puts Process.pid
+#      sleep 3
+#      piper.puts "The time is #{Time.now}"
+#    }
+#
+#    piper.close
+#
+class Servolux::Piper
+
+  # :stopdoc:
+  SEPERATOR = [0xDEAD, 0xBEEF].pack('n*').freeze
+  # :startdoc:
+
+  # call-seq:
+  #    Piper.daemon( nochdir = false, noclose = false )
+  #
+  # 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
+  # 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
+  # working directory; the second will keep stdout/stderr/stdin open.
+  #
+  def self.daemon( nochdir = false, noclose = false )
+    piper = self.new(:timeout => 1)
+    piper.parent {
+      pid = piper.gets
+      piper.instance_variable_set(:@child_pid, pid)
+    }
+    piper.child {
+      Process.setsid                     # Become session leader.
+      exit!(0) if fork                   # Zap session leader.
+
+      Dir.chdir '/' unless nochdir       # Release old working directory.
+      File.umask 0000                    # Ensure sensible umask.
+
+      unless noclose
+        STDIN.reopen  '/dev/null'        # Free file descriptors and
+        STDOUT.reopen '/dev/null', 'a'   # point them somewhere sensible.
+        STDERR.reopen '/dev/null', 'a'
+      end
+
+      piper.puts Process.pid
+    }
+    piper
+  end
+
+  # The timeout in seconds to wait for puts / gets commands.
+  attr_accessor :timeout
+
+  # The read end of the pipe.
+  attr_reader :read_io
+
+  # The write end of the pipe.
+  attr_reader :write_io
+
+  # call-seq:
+  #    Piper.new( mode = 'r', opts = {} )
+  #
+  # Creates a new Piper instance with the communication pipe configured
+  # using the provided _mode_. The default mode is read-only (from the
+  # parent, and write-only from the child). The supported modes are as
+  # follows:
+  #
+  #    Mode | Parent View | Child View
+  #    -----+-------------+-----------
+  #    r      read-only     write-only
+  #    w      write-only    read-only
+  #    rw     read-write    read-write
+  #
+  # The communication timeout can be provided as an option. This is the
+  # number of seconds to wait for a +puts+ or +gets+ to succeed.
+  #
+  def initialize( *args )
+    opts = args.last.is_a?(Hash) ? args.pop : {}
+    mode = args.first || 'r'
+
+    unless %w[r w rw].include? mode
+      raise ArgumentError, "Unsupported mode #{mode.inspect}"
+    end
+
+    @timeout = opts.getopt(:timeout, 0)
+    @read_io, @write_io = IO.pipe
+    @child_pid = Kernel.fork
+
+    if child?
+      case mode
+      when 'r'; close_read
+      when 'w'; close_write
+      end
+    else
+      case mode
+      when 'r'; close_write
+      when 'w'; close_read
+      end
+    end
+  end
+
+  # Close both the read and write ends of the communications pipe. This only
+  # affects the process from which it was called -- the parent or the child.
+  #
+  def close
+    @read_io.close rescue nil
+    @write_io.close rescue nil
+  end
+
+  # Close the read end of the communications pipe. This only affects the
+  # process from which it was called -- the parent or the child.
+  #
+  def close_read
+    @read_io.close rescue nil
+  end
+
+  # Close the write end of the communications pipe. This only affects the
+  # process from which it was called -- the parent or the child.
+  #
+  def close_write
+    @write_io.close rescue nil
+  end
+
+  # Returns +true+ if the communications pipe is readable from the process
+  # and there is data waiting to be read.
+  #
+  def readable?
+    return false if @read_io.closed?
+    r,w,e = Kernel.select([@read_io], nil, nil, @timeout)
+    return !(r.nil? or r.empty?)
+  end
+
+  # Returns +true+ if the communications pipe is writeable from the process
+  # and the write buffer can accept more data.
+  #
+  def writeable?
+    return false if @write_io.closed?
+    r,w,e = Kernel.select(nil, [@write_io], nil, @timeout)
+    return !(w.nil? or w.empty?)
+  end
+
+  # call-seq:
+  #    child { block }
+  #    child {|piper| block }
+  #
+  # Execute the _block_ only in the child process. This method returns
+  # immediately when called from the parent process.
+  #
+  def child( &block )
+    return unless child?
+    raise ArgumentError, "A block must be supplied" if block.nil?
+
+    if block.arity > 0
+      block.call(self)
+    else
+      block.call
+    end
+  end
+
+  # Returns +true+ if this is the child prcoess and +false+ otherwise.
+  #
+  def child?
+    @child_pid.nil?
+  end
+
+  # call-seq:
+  #    parent { block }
+  #    parent {|piper| block }
+  #
+  # Execute the _block_ only in the parent process. This method returns
+  # immediately when called from the child process.
+  #
+  def parent( &block )
+    return unless parent?
+    raise ArgumentError, "A block must be supplied" if block.nil?
+
+    if block.arity > 0
+      block.call(self)
+    else
+      block.call
+    end
+  end
+
+  # Returns +true+ if this is the parent prcoess and +false+ otherwise.
+  #
+  def parent?
+    !@child_pid.nil?
+  end
+
+  # Returns the PID of the child process when called from the parent.
+  # Returns +nil+ when called from the child.
+  #
+  def pid
+    @child_pid
+  end
+
+  # Read an object from the communication pipe. Returns +nil+ if the pipe is
+  # closed for reading or if no data is available before the timeout
+  # expires. If data is available then it is un-marshalled and returned as a
+  # Ruby object.
+  #
+  # This method will block until the +timeout+ is reached or data can be
+  # read from the pipe.
+  #
+  def gets
+    return unless readable?
+
+    data = @read_io.gets SEPERATOR
+    return if data.nil?
+
+    data.chomp! SEPERATOR
+    Marshal.load(data) rescue data
+  end
+
+  # Write an object to the communication pipe. Returns +nil+ if the pipe is
+  # closed for writing or if the write buffer is full. The _obj_ is
+  # marshalled and written to the pipe (therefore, procs and other
+  # un-marshallable Ruby objects cannot be passed through the pipe).
+  #
+  # If the write is successful, then the number of bytes written to the pipe
+  # is returned. If this number is zero it means that the _obj_ was
+  # unsuccessfully communicated (sorry).
+  #
+  def puts( obj )
+    return unless writeable?
+
+    bytes = @write_io.write Marshal.dump(obj)
+    @write_io.write SEPERATOR if bytes > 0
+    @write_io.flush
+
+    bytes
+  end
+
+end  # class Servolux::Piper
+
+# EOF

data/lib/servolux/server.rb

@@ -0,0 +1,226 @@
+
+# == Synopsis
+# The Server class makes it simple to create a server-type application in
+# Ruby. A server in this context is any process that should run for a long
+# period of time either in the foreground or as a daemon.
+#
+# == Details
+# The Server class provides for standard server features: process ID file
+# management, signal handling, run loop, logging, etc. All that you need to
+# provide is a +run+ method that will be called by the server's run loop.
+# Optionally, you can provide a block to the +new+ method and it will be
+# called within the run loop instead of a run method.
+#
+# SIGINT and SIGTERM are handled by default. These signals will gracefully
+# shutdown the server by calling the +shutdown+ method (provided by default,
+# too). A few other signals can be handled by defining a few methods on your
+# server instance. For example, SIGINT is hanlded by the +int+ method (an
+# alias for +shutdown+). Likewise, SIGTERM is handled by the +term+ method
+# (another alias for +shutdown+). The following signal methods are
+# recognized by the Server class:
+#
+#    Method  |  Signal  |  Default Action
+#    --------+----------+----------------
+#    hup        SIGHUP     none
+#    int        SIGINT     shutdown
+#    term       SIGTERM    shutdown
+#    usr1       SIGUSR1    none
+#    usr2       SIGUSR2    none
+#
+# In order to handle SIGUSR1 you would define a <tt>usr1</tt> method for your
+# server.
+#
+# There are a few other methods that are useful and should be mentioned. Two
+# methods are called before and after the run loop starts: +before_starting+
+# and +after_starting+. The first is called just before the run loop thread
+# is created and started. The second is called just after the run loop
+# thread has been created (no guarantee is made that the run loop thread has
+# actually been scheduled).
+#
+# Likewise, two other methods are called before and after the run loop is
+# shutdown: +before_stopping+ and +after_stopping+. The first is called just
+# before the run loop thread is signaled for shutdown. The second is called
+# just after the run loop thread has died; the +after_stopping+ method is
+# guarnteed to NOT be called till after the run loop thread is well and
+# truly dead.
+# 
+# == Usage
+# For simple, quick and dirty servers just pass a block to the Server
+# initializer. This block will be used as the run method.
+#
+#    server = Servolux::Server.new('Basic', :interval => 1) {
+#      puts "I'm alive and well @ #{Time.now}"
+#    }
+#    server.startup
+#
+# For more complex services you will need to define your own server methods:
+# the +run+ method, signal handlers, and before/after methods. Any pattern
+# that Ruby provides for defining methods on objects can be used to define
+# these methods. In a nutshell:
+#
+# Inheritance
+#
+#    class MyServer < Servolux::Server
+#      def run
+#        puts "I'm alive and well @ #{Time.now}"
+#      end
+#    end
+#    server = MyServer.new('MyServer', :interval => 1)
+#    server.startup
+#
+# Extension
+#
+#    module MyServer
+#      def run
+#        puts "I'm alive and well @ #{Time.now}"
+#      end
+#    end
+#    server = Servolux::Server.new('Module', :interval => 1)
+#    server.extend MyServer
+#    server.startup
+#
+# Singleton Class
+#
+#    server = Servolux::Server.new('Singleton', :interval => 1)
+#    class << server
+#      def run
+#        puts "I'm alive and well @ #{Time.now}"
+#      end
+#    end
+#    server.startup
+#
+# == Examples
+#
+# === Signals
+# This example shows how to change the log level of the server when SIGUSR1
+# is sent to the process. The log level toggles between "debug" and the
+# original log level each time SIGUSR1 is sent to the server process. Since
+# this is a module, it can be used with any Servolux::Server instance.
+#
+#    module DebugSignal
+#      def usr1
+#        if @old_log_level
+#          logger.level = @old_log_level
+#          @old_log_level = nil
+#        else
+#          @old_log_level = logger.level
+#          logger.level = :debug
+#        end
+#      end
+#    end
+#
+#    server = Servolux::Server.new('Debugger', :interval => 2) {
+#      logger.info "Running @ #{Time.now}"
+#      logger.debug "hey look - a debug message"
+#    }
+#    server.extend DebugSignal
+#    server.startup
+#
+class Servolux::Server
+  include ::Servolux::Threaded
+
+  # :stopdoc:
+  SIGNALS = %w[HUP INT TERM USR1 USR2] & Signal.list.keys
+  SIGNALS.each {|sig| sig.freeze}.freeze
+  # :startdoc:
+
+  Error = Class.new(::Servolux::Error)
+
+  attr_reader   :name
+  attr_writer   :logger
+  attr_writer   :pid_file
+
+  # call-seq:
+  #    Server.new( name, options = {} ) { block }
+  #
+  # Creates a new server identified by _name_ and configured from the
+  # _options_ hash. The _block_ is run inside a separate thread that will
+  # loop at the configured interval.
+  #
+  # ==== Options
+  # * logger <Logger> :: The logger instance this server will use
+  # * pid_file <String> :: Location of the PID file
+  # * interval <Numeric> :: Sleep interval between invocations of the _block_
+  #
+  def initialize( name, opts = {}, &block )
+    @name = name
+
+    self.logger   = opts.getopt :logger
+    self.pid_file = opts.getopt :pid_file
+    self.interval = opts.getopt :interval, 0
+
+    if block
+      eg = class << self; self; end
+      eg.__send__(:define_method, :run, &block)
+    end
+
+    ary = %w[name logger pid_file].map { |var|
+      self.send(var).nil? ? var : nil
+    }.compact
+    raise Error, "These variables are required: #{ary.join(', ')}." unless ary.empty?
+  end
+
+  # Start the server running using it's own internal thread. This method
+  # will not return until the server is shutdown.
+  #
+  # Startup involves creating a PID file, registering signal handlers to
+  # shutdown the server, starting and joining the server thread. The PID
+  # file is deleted when this method returns.
+  #
+  def startup
+    return self if running?
+    begin
+      create_pid_file
+      trap_signals
+      start
+      join
+    ensure
+      delete_pid_file
+    end
+    return self
+  end
+
+  alias :shutdown :stop     # for symmetry with the startup method
+  alias :int :stop          # handles the INT signal
+  alias :term :stop         # handles the TERM signal
+  private :start, :stop
+
+  # Returns the logger instance used by the server. If none was given, then
+  # a logger is created from the Logging framework (see the Logging rubygem
+  # for more information).
+  #
+  def logger
+    @logger ||= Logging.logger[self]
+  end
+
+  # Returns the PID file name used by the server. If none was given, then
+  # the server name is used to create a PID file name.
+  #
+  def pid_file
+    @pid_file ||= name.downcase.tr(' ','_') + '.pid'
+  end
+
+  private
+
+  def create_pid_file
+    logger.debug "Server #{name.inspect} creating pid file #{pid_file.inspect}"
+    File.open(pid_file, 'w') {|fd| fd.write(Process.pid.to_s)}
+  end
+
+  def delete_pid_file
+    if test(?f, pid_file)
+      logger.debug "Server #{name.inspect} removing pid file #{pid_file.inspect}"
+      File.delete(pid_file)
+    end
+  end
+
+  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
+    end
+  end
+
+end  # class Servolux::Server
+
+# EOF

data/lib/servolux/threaded.rb

@@ -0,0 +1,133 @@
+
+# == Synopsis
+# The Threaded module is used to peform some activity at a specified
+# interval.
+#
+# == Details
+# Sometimes it is useful for an object to have its own thread of execution
+# to perform a task at a recurring interval. The Threaded module
+# encapsulates this functionality so you don't have to write it yourself. It
+# can be used with any object that responds to the +run+ method.
+#
+# The threaded object is run by calling the +start+ method. This will create
+# a new thread that will invoke the +run+ method at the desired interval.
+# Just before the thread is created the +before_starting+ method will be
+# called (if it is defined by the threaded object). Likewise, after the
+# thread is created the +after_starting+ method will be called (if it is
+# defeined by the threaded object).
+#
+# The threaded object is stopped by calling the +stop+ method. This sets an
+# internal flag and then wakes up the thread. The thread gracefully exits
+# after checking the flag. Like the start method, before and after methods
+# are defined for stopping as well. Just before the thread is stopped the
+# +before_stopping+ method will be called (if it is defined by the threaded
+# object). Likewise, after the thread has died the +after_stopping+ method
+# will be called (if it is defeined by the threaded object).
+#
+# Calling the +join+ method on a threaded object will cause the calling
+# thread to wait until the threaded object has stopped. An optional timeout
+# parameter can be given.
+#
+# == Examples
+# Take a look at the Servolux::Server class for an example of a threaded
+# object.
+#
+module Servolux::Threaded
+
+  # This method will be called by the activity thread at the desired
+  # interval. Implementing classes are exptect to provide this
+  # functionality.
+  #
+  def run
+    raise NotImplementedError,
+         'This method must be defined by the threaded object.'
+  end
+
+  # Start the activity thread. If already started this method will return
+  # without taking any action.
+  #
+  # If the including class defines a 'before_starting' method, it will be
+  # called before the thread is created and run. Likewise, if the
+  # including class defines an 'after_starting' method, it will be called
+  # after the thread is created.
+  #
+  def start
+    return self if running?
+    logger.debug "Starting"
+
+    before_starting if self.respond_to?(:before_starting)
+    @activity_thread_running = true
+    @activity_thread = Thread.new {
+      begin
+        loop {
+          sleep interval
+          break unless running?
+          run
+        }
+      rescue Exception => e
+        logger.fatal e
+      end
+    }
+    after_starting if self.respond_to?(:after_starting)
+    self
+  end
+
+  # Stop the activity thread. If already stopped  this method will return
+  # without taking any action.
+  #
+  # If the including class defines a 'before_stopping' method, it will be
+  # called before the thread is stopped. Likewise, if the including class
+  # defines an 'after_stopping' method, it will be called after the thread
+  # has stopped.
+  #
+  def stop
+    return self unless running?
+    logger.debug "Stopping"
+
+    before_stopping if self.respond_to?(:before_stopping)
+    @activity_thread_running = false
+    @activity_thread.wakeup
+    @activity_thread.join
+    @activity_thread = nil
+    after_stopping if self.respond_to?(:after_stopping)
+    self
+  end
+
+  # If the activity thread is running, the calling thread will suspend
+  # execution and run the activity thread. This method does not return until
+  # the activity thread is stopped or until _limit_ seconds have passed.
+  #
+  # If the activity thread is not running, this method returns immediately
+  # with +nil+.
+  #
+  def join( limit = nil )
+    @activity_thread.join limit
+    self
+  rescue NoMethodError
+    return self
+  end
+
+  # Returns +true+ if the activity thread is running. Returns +false+
+  # otherwise.
+  #
+  def running?
+    @activity_thread_running
+  end
+
+  # Sets the number of seconds to sleep between invocations of the
+  # threaded object's 'run' method.
+  #
+  def interval=( value )
+    @activity_thread_interval = value
+  end
+
+  # Returns the number of seconds to sleep between invocations of the
+  # threaded object's 'run' method.
+  #
+  def interval
+    @activity_thread_interval
+  end
+
+end  # module Servolux::Threaded
+
+# EOF

data/lib/servolux.rb

@@ -0,0 +1,49 @@
+
+require 'logging'
+
+module Servolux
+
+  # :stopdoc:
+  VERSION = '0.1.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+  
+  # Generic Servolux Error class.
+  Error = Class.new(StandardError)
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Returns +true+ if the execution platform supports fork.
+  #
+  def self.fork?
+    RUBY_PLATFORM != 'java' and test(?e, '/dev/null')
+  end
+
+end  # module Servolux
+
+%w[threaded server piper daemon].each do |lib|
+  require Servolux.libpath('servolux', lib)
+end
+
+# EOF

data/spec/servolux_spec.rb

@@ -0,0 +1,20 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Servolux do
+
+  before :all do
+    @root_dir = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+  end
+
+  it "finds things releative to 'lib'" do
+    Servolux.libpath(%w[servolux threaded]).should == File.join(@root_dir, %w[lib servolux threaded])
+  end 
+    
+  it "finds things releative to 'root'" do
+    Servolux.path('Rakefile').should == File.join(@root_dir, 'Rakefile')
+  end 
+
+end
+
+# EOF