slave 0.2.0 → 1.0.0

data/lib/slave.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

data/{sample → samples}/a.rb

@@ -1,19 +1,16 @@
 require 'slave'
-
 #
 # simple usage is simply to stand up a server object as a slave.  you do not
 # need to wait for the server, join it, etc.  it will die when the parent
 # process dies - even under 'kill -9' conditions
 #
-
-class Server
-  def add_two n
-    n + 2
+  class Server
+    def add_two n
+      n + 2
+    end
   end
-end
-
-slave = Slave.new Server.new
-server = slave.object
 
-p server.add_two(40) #=> 42
+  slave = Slave.new :object => Server.new
+  server = slave.object
 
+  p server.add_two(40) #=> 42

data/samples/b.rb

@@ -0,0 +1,22 @@
+require 'slave'
+#
+# if certain operations need to take place in the child only a block can be
+# used
+#
+  class Server
+    def connect_to_db 
+      "we only want to do this in the child process!"
+      @connection = :postgresql
+    end
+    attr :connection
+  end
+
+  slave = Slave.new('object' => Server.new){|s| s.connect_to_db}
+
+  server = slave.object
+
+  p server.connection  #=> :postgresql 
+#
+# errors in the child are detected and raised in the parent
+#
+  slave = Slave.new('object' => Server.new){|s| s.typo} #=> raises an error!

data/samples/c.rb

@@ -0,0 +1,21 @@
+require 'slave'
+#
+# if no slave object is given the block itself is used to contruct it 
+#
+  class Server
+    def initialize
+      "this is run only in the child"
+      @pid = Process.pid
+    end
+    attr 'pid'
+  end
+
+  slave = Slave.new{ Server.new }
+  server = slave.object
+
+  p Process.pid
+  p server.pid # not going to be the same as parents!
+#
+# errors are still detected though
+#
+  slave = Slave.new{ fubar } # raises error in parent