slave 0.2.0 → 1.0.0

data/doc/files/lib/slave_rb.html

@@ -56,7 +56,7 @@
 		</tr>
 		<tr class="top-aligned-row">
 			<td><strong>Last Update:</strong></td>
-			<td>Thu Jun 08 15:54:54 MDT 2006</td>
+			<td>Fri Oct 13 13:24:25 MDT 2006</td>
 		</tr>
 		</table>
 	</div>
@@ -68,7 +68,8 @@
 	<div id="contextContent">
 		<div id="diagram">
 			<map name="map">
-  <area shape="RECT" coords="28,88,99,40"      href="../../classes/Slave.html" alt="Slave">
+  <area shape="RECT" coords="123,98,195,50"      href="../../classes/o.html" alt="o">
+  <area shape="RECT" coords="27,98,99,50"      href="../../classes/Slave.html" alt="Slave">
 </map>
 <img src="../../dot/f_1.jpg" usemap="#map" border=0 alt="TopLevel">
 		</div>
@@ -96,6 +97,7 @@
 
 			Class <a href="../../classes/Slave.html" class="link">Slave</a><br />
 &nbsp;&nbsp;::Class <a href="../../classes/Slave/Heartbeat.html" class="link">Slave::Heartbeat</a><br />
+Class <a href="../../classes/o.html" class="link">o</a><br />
 
 		</div>
 

data/doc/fr_class_index.html

@@ -22,6 +22,7 @@
 	<div id="index-entries">
 		<a href="classes/Slave.html">Slave</a><br />
 		<a href="classes/Slave/Heartbeat.html">Slave::Heartbeat</a><br />
+		<a href="classes/o.html">o</a><br />
 	</div>
 </div>
 </body>

data/doc/fr_method_index.html

@@ -20,25 +20,29 @@
 <div id="index">
 	<h1 class="section-bar">Methods</h1>
 	<div id="index-entries">
-		<a href="classes/Slave/Heartbeat.html#M000017">child_start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000014">child_start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000004">detach (Slave)</a><br />
-		<a href="classes/Slave.html#M000002">fork (Slave)</a><br />
-		<a href="classes/Slave.html#M000008">gen_psname (Slave)</a><br />
-		<a href="classes/Slave.html#M000001">getval (Slave)</a><br />
-		<a href="classes/Slave.html#M000009">getval (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000011">new (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000003">new (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000016">parent_start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000013">parent_start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000007">shutdown (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000012">start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000015">start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000018">stop (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000010">trace (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000019">trace (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000005">wait (Slave)</a><br />
-		<a href="classes/Slave.html#M000006">wait2 (Slave)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000021">child_start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000018">child_start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave.html#M000012">default (Slave)</a><br />
+		<a href="classes/Slave.html#M000002">default (Slave)</a><br />
+		<a href="classes/Slave.html#M000006">detach (Slave)</a><br />
+		<a href="classes/Slave.html#M000004">fork (Slave)</a><br />
+		<a href="classes/Slave.html#M000011">gen_psname (Slave)</a><br />
+		<a href="classes/Slave.html#M000013">getopts (Slave)</a><br />
+		<a href="classes/Slave.html#M000003">getopts (Slave)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000015">new (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave.html#M000005">new (Slave)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000020">parent_start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000017">parent_start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave.html#M000009">shutdown (Slave)</a><br />
+		<a href="classes/Slave.html#M000010">shutdown? (Slave)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000016">start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000019">start (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000022">stop (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave.html#M000014">trace (Slave)</a><br />
+		<a href="classes/Slave/Heartbeat.html#M000023">trace (Slave::Heartbeat)</a><br />
+		<a href="classes/Slave.html#M000001">version (Slave)</a><br />
+		<a href="classes/Slave.html#M000007">wait (Slave)</a><br />
+		<a href="classes/Slave.html#M000008">wait2 (Slave)</a><br />
 	</div>
 </div>
 </body>

data/gen_readme.rb

@@ -0,0 +1,32 @@
+require 'pathname'
+
+$VERBOSE=nil
+
+def indent s, n = 2
+  ws = ' ' * n
+  s.gsub %r/^/, ws 
+end
+
+template = IO::read 'README.tmpl'
+
+samples = ''
+prompt = '~ > '
+
+Dir['sample*/*'].sort.each do |sample|
+  samples << "\n" << "  <========< #{ sample } >========>" << "\n\n"
+
+  cmd = "cat #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+  samples << indent(`#{ cmd }`, 4) << "\n" 
+
+  cmd = "ruby #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+
+  cmd = "ruby -Ilib #{ sample }" 
+  samples << indent(`#{ cmd } 2>&1`, 4) << "\n" 
+end
+
+#samples.gsub! %r/^/, '  '
+
+readme  = template.gsub %r/^\s*@samples\s*$/, samples
+print readme 

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

@@ -20,14 +20,24 @@ require 'fcntl'
 #     end
 #   end
 #  
-#   slave = Slave.new Server.new
+#   slave = Slave.new 'object' => Server.new
 #   server = slave.object
 #  
 #   p server.add_two(40) #=> 42
+#  
+# two other methods of providing server objects exist:
+#  
+# a) server = Server.new "this is called the parent" }
+#    Slave.new(:object=>server){|s| puts "#{ s.inspect } passed to block in child process"}
+#  
+# b) Slave.new{ Server.new "this is called only in the child" }
+#  
+# of the two 'b' is preferred.
 #
   class Slave
 #--{{{
-    VERSION = '0.2.0'
+    VERSION = '1.0.0'
+    def self.version() VERSION end
   #
   # config
   #
@@ -59,14 +69,27 @@ require 'fcntl'
       # on STDERR
       attr :debug, true
 
-      # look up a value in an option hash failing back to class defaults
-      def getval key, opts = {}
+      # get a default value 
+      def default key
 #--{{{
-        keys = [key, key.to_s, key.to_s.intern]
-        keys.each{|k| return opts[k] if opts.has_key?(k)}
-        send key rescue nil
+        send key
+#--}}}
+      end
+
+      def getopts opts
+#--{{{
+        raise ArgumentError, opts.class unless
+          opts.respond_to?('has_key?') and opts.respond_to?('[]')
+
+        lambda do |key, *defval|
+          defval = defval.shift
+          keys = [key, key.to_s, key.to_s.intern]
+          key = keys.detect{|k| opts.has_key? k } and break opts[key]
+          defval
+        end
 #--}}}
       end
+
       # just fork with out silly warnings
       def fork &block
 #--{{{
@@ -82,87 +105,126 @@ require 'fcntl'
 #--}}}
     end
 
-    attr :object
+
     attr :obj
+    attr :socket_creation_attempts
+    attr :pulse_rate
+    attr :debug
     attr :psname
+    attr :at_exit
+
+    attr :shutdown
+    attr :status
+    attr :object
     attr :pid
     attr :ppid
     attr :uri
-    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'
+  # opts may contain the keys 'object', 'socket_creation_attempts',
+  # 'pulse_rate', 'psname', 'dumped', or 'debug'
   #
-    def initialize obj = nil, opts = {}, &block
+    def initialize opts = {}, &block
 #--{{{
-      raise ArgumentError, "no slave object!" if 
-        obj.nil? and block.nil?
+      getopt = getopts opts
 
-      @obj = obj
+      @obj = getopt['object']
+      @socket_creation_attempts = getopt['socket_creation_attempts'] || default('socket_creation_attempts')
+      @pulse_rate = getopt['pulse_rate'] || default('pulse_rate')
+      @debug = getopt['debug'] || default('debug')
+      @psname = getopt['psname']
+      @at_exit = getopt['at_exit']
+      @dumped = getopt['dumped']
 
-      @socket_creation_attempts = getval('socket_creation_attempts', opts)
-      @pulse_rate = getval('pulse_rate', opts)
-      @debug = getval('debug', opts)
-      @psname = getval('psname', opts) || gen_psname(@obj)
-
-      trace{ "socket_creation_attempts <#{ @socket_creation_attempts }>" }
-      trace{ "pulse_rate <#{ @pulse_rate }>" }
-      trace{ "psname <#{ @psname }>" }
+      raise ArgumentError, 'no slave object!' if 
+        @obj.nil? and block.nil?
 
       @shutdown = false
       @waiter = @status = nil
 
       @heartbeat = Heartbeat::new @pulse_rate, @debug
       @r, @w = IO::pipe
+      @r2, @w2 = IO::pipe
+
+      # weird syntax because dot/rdoc chokes on this!?!?
+      init_failure = lambda do |e|
+        o = Object.new
+        class << o
+          attr_accessor '__slave_object_failure__'
+        end
+        o.__slave_object_failure__ = Marshal.dump [e.class, e.message, e.backtrace]
+        @object = o
+      end
+
     #
     # child
     #
       unless((@pid = Slave::fork))
         e = nil
         begin
-          $0 = @psname 
-          @pid = Process::pid
-          @ppid = Process::ppid
+          Kernel.at_exit{ Kernel.exit! }
+
+          if @obj
+            @object = @obj
+          else
+            begin
+              @object = block.call 
+            rescue Exception => e
+              init_failure[e]
+            end
+          end
+
+          if block and @obj
+            begin
+              block[@obj]
+            rescue Exception => e
+              init_failure[e]
+            end
+          end
+
+          $0 = (@psname ||= gen_psname(@object))
+          unless @dumped or @object.respond_to?('__slave_object_failure__')
+            @object.extend DRbUndumped
+          end
+
+          @ppid, @pid = Process::ppid, Process::pid
 
           @r.close
+          @r2.close
           @socket = nil
           @uri = nil
 
-          tmpdir = Dir::tmpdir
-          basename = File::basename @psname
-          
-          server = @obj || block.call
+          tmpdir, basename = Dir::tmpdir, File::basename(@psname)
 
           @socket_creation_attempts.times do |attempt|
+            se = nil
             begin
               s = File::join(tmpdir, "#{ basename }_#{ attempt }")
               u = "drbunix://#{ s }"
-              DRb::start_service u, server 
+              DRb::start_service u, @object 
               @socket = s
               @uri = u
               trace{ "child - socket <#{ @socket }>" }
               trace{ "child - uri <#{ @uri }>" }
               break
-            rescue Errno::EADDRINUSE
+            rescue Errno::EADDRINUSE => se
               nil
             end
           end
 
           if @socket and @uri
             @heartbeat.start
-            @w.write @socket 
-            @w.close
+
             trap('SIGUSR2') do
               # @heartbeat.stop rescue nil
               DBb::thread.kill rescue nil
               FileUtils::rm_f @socket rescue nil
-              exit!
+              exit
             end
-            block[obj] if block and obj
+
+            @w.write @socket 
+            @w.close
             DRb::thread.join
           else
             @w.close
@@ -171,22 +233,36 @@ require 'fcntl'
           trace{ %Q[#{ e.message } (#{ e.class })\n#{ e.backtrace.join "\n" }] }
         ensure
           status = e.respond_to?('status') ? e.status : 1
-          exit!(status)
+          exit(status)
         end
     #
     # parent 
     #
       else
-        #Process::detach @pid
         detach
         @w.close
+        @w2.close
         @socket = @r.read
         @r.close
 
         trace{ "parent - socket <#{ @socket }>" }
 
+        if @at_exit
+          @at_exit_thread = Thread.new{
+            Thread.current.abort_on_exception = true
+
+            @r2.read rescue 42
+
+            if @at_exit.respond_to? 'call'
+              @at_exit.call self
+            else
+              send @at_exit.to_s, self
+            end
+          }
+        end
+
         if @socket and File::exist? @socket
-          at_exit{ FileUtils::rm_f @socket }
+          Kernel.at_exit{ FileUtils::rm_f @socket }
           @uri = "drbunix://#{ socket }"
           trace{ "parent - uri <#{ @uri }>" }
           @heartbeat.start
@@ -195,6 +271,12 @@ require 'fcntl'
         #
           DRb::start_service('druby://localhost:0', nil) unless DRb::thread
           @object = DRbObject::new nil, @uri
+          if @object.respond_to? '__slave_object_failure__'
+            c, m, bt = Marshal.load @object.__slave_object_failure__
+            (e = c.new(m)).set_backtrace bt
+            raise e 
+          end
+          @psname ||= gen_psname(@object)
         else
           raise "failed to find slave socket <#{ @socket }>"
         end
@@ -202,34 +284,70 @@ require 'fcntl'
 #--}}}
     end
   #
-  # starts a thread to attempt collecting the child status
+  # starts a thread to collect the child status and sets up at_exit handler to
+  # prevent zombies.  the at_exit handler is canceled if the thread is able to
+  # collect the status
   #
     def detach
 #--{{{
-      @waiter =
-        Thread.new{ @status = Process::waitpid2(@pid).last }
+      reap = lambda do |cid|
+        begin
+          @status = Process::waitpid2(cid).last
+        rescue Exception => e 
+          m, c, b = e.message, e.class, e.backtrace.join("\n")
+          warn "#{ m } (#{ c })\n#{ b }"  unless e.is_a? Errno::ECHILD
+        end
+      end
+
+      Kernel.at_exit do
+        shutdown rescue nil
+        reap[@pid] rescue nil
+      end
+
+      @waiter = 
+        Thread.new do
+          begin
+            @status = Process::waitpid2(@pid).last
+          ensure
+            reap = lambda{|cid| 'no-op' }
+          end
+        end
 #--}}}
     end
   #
-  # wait for slave to finish
+  # wait for slave to finish.  if the keyword 'non_block'=>true is given a
+  # thread is returned to do the waiting in an async fashion. eg 
   #
-    def wait
+  #   thread = slave.wait(:non_block=>true){|value| "background <#{ value }>"}
+  #
+    def wait opts = {}, &b
 #--{{{
-      @waiter.value
+      b ||= lambda{|exit_status|}
+      non_block = getopts(opts)['non_block']
+      non_block ? Thread.new{ b[ @waiter.value ] } : b[ @waiter.value ]
 #--}}}
     end
     alias :wait2 :wait
   #
-  # stops the heartbeat thread and kills the child process
+  # stops the heartbeat thread and kills the child process - give the key
+  # 'quiet' to ignore errors shutting down, including having already shutdown
   #
-    def shutdown
+    def shutdown opts = {}
 #--{{{
-      raise "already shutdown" if @shutdown
-      @heartbeat.stop rescue nil
-      Process::kill('SIGUSR2', @pid) rescue nil
-      Process::kill('SIGTERM', @pid) rescue nil
-      FileUtils::rm_f @socket
+      quiet = getopts(opts)['quiet']
+      raise "already shutdown" if @shutdown unless quiet
+      failure = lambda{ raise $! unless quiet }
+      @heartbeat.stop rescue failure.call 
+      Process::kill('SIGUSR2', @pid) rescue failure.call 
       @shutdown = true
+#--}}}
+    end
+  #
+  # true
+  #
+    def shutdown?
+#--{{{
+      @shutdown
 #--}}}
     end
   #
@@ -237,15 +355,23 @@ require 'fcntl'
   #
     def gen_psname obj
 #--{{{
-      "#{ obj.class }_slave_of_#{ Process::pid }".downcase.gsub(%r/\s+/,'_')
+      "#{ obj.class }_#{ obj.object_id }_#{ Process::ppid }_#{ Process::pid }".downcase.gsub(%r/\s+/,'_')
+#--}}}
+    end
+  #
+  # see docs for Slave.default
+  #
+    def default key
+#--{{{
+      self.class.default key
 #--}}}
     end
   #
-  # see docs for Slave.getval
+  # see docs for Slave.getopts
   #
-    def getval key, opts = {}
+    def getopts opts 
 #--{{{
-      self.class.getval key
+      self.class.getopts opts 
 #--}}}
     end
   #
@@ -256,7 +382,6 @@ require 'fcntl'
       STDERR.puts(yield) if @debug and STDERR.tty?
 #--}}}
     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
@@ -380,7 +505,7 @@ require 'fcntl'
               @pipe.read
             trace{ "child read." }
             trace{ "child exiting." }
-            exit!
+            exit
             rescue => e
               cur.raise e
             ensure