slave 0.0.1 → 0.2.0

data/README

@@ -1,42 +1,79 @@
-the Slave class forks a process and starts a drb server in the child using any
-object as the server.  the process is detached so it is not required (nor
-possible) to wait on the child pid.  a Heartbeat is set up between the parent
-and child processes so that the child will exit of the parent exits for any
-reason - preventing orphaned slaves from running indefinitely.  the purpose of
-Slaves is to be able to easily set up a collection of objects communicating
-via drb protocols instead of having to use IPC. 
+SYNOPSIS
 
-typical usage:
+  the Slave class forks a process and starts a drb server in the child using
+  any object as the server.  the process is detached so it is not required
+  (nor possible) to wait on the child pid.  a Heartbeat is set up between the
+  parent and child processes so that the child will exit of the parent exits
+  for any reason - preventing orphaned slaves from running indefinitely.  the
+  purpose of Slaves is to be able to easily set up a collection of objects
+  communicating via drb protocols instead of having to use IPC. 
 
-  obj = AnyClass::new
+  typical usage:
 
-  slave = Slave::new obj 
+    obj = AnyClass::new
 
-  p slave.object                  # handle on drb object
-  p slave.uri                     # uri of the drb object
-  p slave.socket                  # unix domain socket path for drb object
-  p slave.psname                  # title shown in ps/top
+    slave = Slave::new obj 
 
-other usage: 
+    p slave.object                  # handle on drb object
+    p slave.uri                     # uri of the drb object
+    p slave.socket                  # unix domain socket path for drb object
+    p slave.psname                  # title shown in ps/top
 
-set the pulse_rate used for the Heartbeat
+  other usage: 
 
-  slave = Slave::new MyClass::new, 'pulse_rate' => 10
+  set the pulse_rate used for the Heartbeat
 
-same
+    slave = Slave::new MyClass::new, 'pulse_rate' => 10
 
-  Slave::pulse_rate = 10
-  slave = Slave::new MyClass::new
+  same
 
-same
+    Slave::pulse_rate = 10
+    slave = Slave::new MyClass::new
 
-  ENV['SLAVE_PULSE_RATE'] = 10
-  slave = Slave::new MyClass::new
+  same
 
-slaves may be configured via the environment, the Slave class, or via the ctor
-for object itself.  attributes which may be configured include
+    ENV['SLAVE_PULSE_RATE'] = 10
+    slave = Slave::new MyClass::new
 
-* socket_creation_attempts
-* pulse_rate 
-* psname
-* debug 
+  to avoid having a copy of the object in both the parent and child use the
+  block form
+
+    slave = Slave::new{ Server::new }  # copy only in child!
+    server = slave.object
+
+  if both an object AND a block are passed the object is passed to the block
+  in the child process
+
+    slave = Slave::new(Server::new){|server| p 'in child!' }
+
+  slaves may be configured via the environment, the Slave class, or via the
+  ctor for object itself.  attributes which may be configured include
+
+    * socket_creation_attempts
+    * pulse_rate 
+    * psname
+    * debug 
+
+HISTORY
+
+  0.2.0:
+    incorporated joel vanderWerf's patch such that, if no object is passed the
+    block is used to create one ONLY in the child.  this avoids having a copy
+    in both parent and child is that needs to be avoided due to, for instance,
+    resource consumption.
+
+
+  0.0.1:
+    - patch from Logan Capaldo adds block form to slave new, block is run in the
+      child
+
+    - added a few more samples/*
+
+    - added Slave#wait
+
+    - added status information to slaves
+
+    - added close-on-exec flag to pipes in parent process
+
+  0.0.0:
+    - initial version

data/install.rb

@@ -156,6 +156,7 @@ usage = <<-usage
     -b, --bindir     <bindir>
     -r, --ruby       <ruby>
     -n, --no_linkify
+    -s, --sudo
     -h, --help
 usage
 
@@ -172,6 +173,8 @@ begin
       $ruby = ARGV.req_arg
     when '-n', '--no_linkify'
       no_linkify = true
+    when '-s', '--sudo'
+      sudo = 'sudo' 
     when '-h', '--help'
       help = true
     else
@@ -193,6 +196,8 @@ unless no_linkify
   linked = linkify('lib') + linkify('bin')
 end
 
+system "#{ $ruby } extconf.rb && make && #{ sudo } make install" if test(?s, 'extconf.rb')
+
 install_rb(LIBDIR, libdir, LIBDIR_MODE)
 install_rb(BINDIR, bindir, BINDIR_MODE, bin=true)
 

data/lib/{slave-0.0.1.rb → slave-0.2.0.rb}

@@ -4,41 +4,33 @@ require 'tmpdir'
 require 'tempfile'
 require 'fcntl'
 
-  class Pipe
-    attr 'r'
-    attr 'w'
-    def initialize
-      @r, @w = IO.pipe
-    end
-  end
-
-  class Lifeline
-    class Error < ::StandardError
-      def initialize 
-      end
-    end
-    def initialize
-      @pid = Process.pid 
-      @pipe = Pipe.new
-    end
-    def throw
-    end
-    def cling
-      @w.close
-      Thread.new(@r, Thread.current) do |r, t|
-        r.read rescue t.raise($!)
-      end
-    end
-  end
-
 #
 # the Slave class encapsulates the work of setting up a drb server in another
-# process.
+# process running on localhost.  the slave process is attached to it's parent
+# via a Heartbeat which is designed such that the slave cannot out-live it's
+# parent and become a zombie, even if the parent dies and early death, such as
+# by 'kill -9'.  the concept and purpose of the Slave class is to be able to
+# setup any server object in another process so easily that using a
+# multi-process, drb/ipc, based design is as easy, or easier, than a
+# multi-threaded one.  eg
+#
+#   class Server
+#     def add_two n
+#       n + 2
+#     end
+#   end
+#  
+#   slave = Slave.new Server.new
+#   server = slave.object
+#  
+#   p server.add_two(40) #=> 42
 #
   class Slave
 #--{{{
-    VERSION = '0.0.1'
-
+    VERSION = '0.2.0'
+  #
+  # config
+  #
     DEFAULT_SOCKET_CREATION_ATTEMPTS =
       Integer(ENV['SLAVE_SOCKET_CREATION_ATTEMPTS'] || 42)
 
@@ -51,7 +43,9 @@ require 'fcntl'
     @socket_creation_attempts = DEFAULT_SOCKET_CREATION_ATTEMPTS
     @pulse_rate = DEFAULT_PULSE_RATE
     @debug = DEFAULT_DEBUG
-
+  #
+  # class methods
+  #
     class << self
 #--{{{
       # defineds how many attempts will be made to create a temporary unix domain
@@ -97,13 +91,17 @@ require 'fcntl'
     attr :pulse_rate
     attr :socket
     attr :debug
+    attr :status
 
-    #
-    # 'obj' can be any object and 'opts' may contain the keys
-    # 'socket_creation_attempts', 'pulse_rate', 'psname', or 'debug'
-    #
+  #
+  # 'obj' can be any object and 'opts' may contain the keys
+  # 'socket_creation_attempts', 'pulse_rate', 'psname', or 'debug'
+  #
     def initialize obj = nil, opts = {}, &block
 #--{{{
+      raise ArgumentError, "no slave object!" if 
+        obj.nil? and block.nil?
+
       @obj = obj
 
       @socket_creation_attempts = getval('socket_creation_attempts', opts)
@@ -116,13 +114,15 @@ require 'fcntl'
       trace{ "psname <#{ @psname }>" }
 
       @shutdown = false
+      @waiter = @status = nil
 
-      # @heartbeat = Heartbeat::new @pulse_rate, @debug
+      @heartbeat = Heartbeat::new @pulse_rate, @debug
       @r, @w = IO::pipe
     #
     # child
     #
       unless((@pid = Slave::fork))
+        e = nil
         begin
           $0 = @psname 
           @pid = Process::pid
@@ -134,12 +134,14 @@ require 'fcntl'
 
           tmpdir = Dir::tmpdir
           basename = File::basename @psname
+          
+          server = @obj || block.call
 
           @socket_creation_attempts.times do |attempt|
             begin
               s = File::join(tmpdir, "#{ basename }_#{ attempt }")
               u = "drbunix://#{ s }"
-              DRb::start_service u, obj 
+              DRb::start_service u, server 
               @socket = s
               @uri = u
               trace{ "child - socket <#{ @socket }>" }
@@ -151,7 +153,7 @@ require 'fcntl'
           end
 
           if @socket and @uri
-            # @heartbeat.start
+            @heartbeat.start
             @w.write @socket 
             @w.close
             trap('SIGUSR2') do
@@ -160,21 +162,23 @@ require 'fcntl'
               FileUtils::rm_f @socket rescue nil
               exit!
             end
-            block[obj] if block
+            block[obj] if block and obj
             DRb::thread.join
           else
             @w.close
           end
-        rescue => e
+        rescue Exception => e
           trace{ %Q[#{ e.message } (#{ e.class })\n#{ e.backtrace.join "\n" }] }
         ensure
-          exit!
+          status = e.respond_to?('status') ? e.status : 1
+          exit!(status)
         end
     #
     # parent 
     #
       else
-        Process::detach @pid
+        #Process::detach @pid
+        detach
         @w.close
         @socket = @r.read
         @r.close
@@ -185,7 +189,7 @@ require 'fcntl'
           at_exit{ FileUtils::rm_f @socket }
           @uri = "drbunix://#{ socket }"
           trace{ "parent - uri <#{ @uri }>" }
-          # @heartbeat.start
+          @heartbeat.start
         #
         # starting drb on localhost avoids dns lookups!
         #
@@ -197,38 +201,56 @@ require 'fcntl'
       end
 #--}}}
     end
-    #
-    # stops the heartbeat thread and kills the child process
-    #
+  #
+  # starts a thread to attempt collecting the child status
+  #
+    def detach
+#--{{{
+      @waiter =
+        Thread.new{ @status = Process::waitpid2(@pid).last }
+#--}}}
+    end
+  #
+  # wait for slave to finish
+  #
+    def wait
+#--{{{
+      @waiter.value
+#--}}}
+    end
+    alias :wait2 :wait
+  #
+  # stops the heartbeat thread and kills the child process
+  #
     def shutdown
 #--{{{
       raise "already shutdown" if @shutdown
-      # @heartbeat.stop rescue nil
+      @heartbeat.stop rescue nil
       Process::kill('SIGUSR2', @pid) rescue nil
       Process::kill('SIGTERM', @pid) rescue nil
       FileUtils::rm_f @socket
       @shutdown = true
 #--}}}
     end
-    #
-    # generate a default name to appear in ps/top
-    #
+  #
+  # generate a default name to appear in ps/top
+  #
     def gen_psname obj
 #--{{{
-      "#{ obj.class }_slave_of_#{ Process::pid }".downcase
+      "#{ obj.class }_slave_of_#{ Process::pid }".downcase.gsub(%r/\s+/,'_')
 #--}}}
     end
-    #
-    # see docs for Slave.getval
-    #
+  #
+  # see docs for Slave.getval
+  #
     def getval key, opts = {}
 #--{{{
       self.class.getval key
 #--}}}
     end
-    #
-    # debugging output
-    #
+  #
+  # debugging output - ENV['SLAVE_DEBUG']=1 to enable
+  #
     def trace
 #--{{{
       STDERR.puts(yield) if @debug and STDERR.tty?
@@ -236,11 +258,11 @@ require 'fcntl'
     end
 
   #
-  # the Heartbeat class is essentially wrapper over an IPC channel that sends a
-  # ping on the channel indicating process health.  if either end of the channel
-  # is detached the ping will fail and an error will be raised.  in this was it
-  # is ensured that Slave object cannot continue to live without their parent
-  # being alive.
+  # the Heartbeat class is essentially wrapper over an IPC channel that sends
+  # a ping on the channel indicating process health.  if either end of the
+  # channel is detached the ping will fail and an error will be raised.  in
+  # this way it is ensured that Slave objects cannot continue to live without
+  # their parent being alive.
   #
     class Heartbeat
 #--{{{

data/lib/slave.rb

@@ -27,7 +27,7 @@ require 'fcntl'
 #
   class Slave
 #--{{{
-    VERSION = '0.0.1'
+    VERSION = '0.2.0'
   #
   # config
   #
@@ -99,6 +99,9 @@ require 'fcntl'
   #
     def initialize obj = nil, opts = {}, &block
 #--{{{
+      raise ArgumentError, "no slave object!" if 
+        obj.nil? and block.nil?
+
       @obj = obj
 
       @socket_creation_attempts = getval('socket_creation_attempts', opts)
@@ -131,12 +134,14 @@ require 'fcntl'
 
           tmpdir = Dir::tmpdir
           basename = File::basename @psname
+          
+          server = @obj || block.call
 
           @socket_creation_attempts.times do |attempt|
             begin
               s = File::join(tmpdir, "#{ basename }_#{ attempt }")
               u = "drbunix://#{ s }"
-              DRb::start_service u, obj 
+              DRb::start_service u, server 
               @socket = s
               @uri = u
               trace{ "child - socket <#{ @socket }>" }
@@ -157,7 +162,7 @@ require 'fcntl'
               FileUtils::rm_f @socket rescue nil
               exit!
             end
-            block[obj] if block
+            block[obj] if block and obj
             DRb::thread.join
           else
             @w.close
@@ -232,7 +237,7 @@ require 'fcntl'
   #
     def gen_psname obj
 #--{{{
-      "#{ obj.class }_slave_of_#{ Process::pid }".downcase.gsub(%r/\s*/,'_')
+      "#{ obj.class }_slave_of_#{ Process::pid }".downcase.gsub(%r/\s+/,'_')
 #--}}}
     end
   #

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: slave
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2006-06-08 00:00:00.000000 -06:00
+  version: 0.2.0
+date: 2006-09-23 00:00:00.000000 -06:00
 summary: slave
 require_paths: 
   - lib
@@ -29,20 +29,18 @@ cert_chain:
 authors: 
   - Ara T. Howard
 files: 
-  - HISTORY
   - install.rb
   - sample
   - lib
   - README
   - rdoc.cmd
-  - slave-0.0.1.gem
   - doc
   - gemspec.rb
   - sample/a.rb
   - sample/b.rb
   - sample/c.rb
-  - lib/slave-0.0.1.rb
   - lib/slave.rb
+  - lib/slave-0.2.0.rb
   - doc/index.html
   - doc/files
   - doc/fr_class_index.html

data/HISTORY

@@ -1,16 +0,0 @@
----
-
-0.0.1:
-  - patch from Logan Capaldo adds block form to slave new, block is run in the
-    child
-
-  - added a few more samples/*
-
-  - added Slave#wait
-
-  - added status information to slaves
-
-  - added close-on-exec flag to pipes in parent process
-
-0.0.0:
-  - initial version