slave 0.0.0 → 0.0.1

data/doc/created.rid

@@ -1 +1 @@
-Fri Nov 12 12:27:08 MST 2004
+Thu Jun 08 15:55:38 MDT 2006

data/doc/dot/f_1.dot

@@ -3,12 +3,27 @@ digraph TopLevel {
     bgcolor = lightcyan1
     fontname = Arial
     fontsize = 8
-    label = "VERSION"
+    label = "lib/slave.rb"
     node [
         fontname = Arial,
         fontsize = 8,
         color = black
     ]
 
+    subgraph cluster_1 {
+        fontname = Arial
+        color = red
+        label = "lib/slave.rb"
+        Slave [
+            fontcolor = black,
+            URL = "classes/Slave.html",
+            shape = ellipse,
+            color = palegoldenrod,
+            style = filled,
+            label = "Slave"
+        ]
+
+    }
+
 }
 

data/doc/files/README.html

@@ -56,7 +56,7 @@
 		</tr>
 		<tr class="top-aligned-row">
 			<td><strong>Last Update:</strong></td>
-			<td>Fri Nov 12 12:27:06 MST 2004</td>
+			<td>Thu Jun 08 14:54:53 MDT 2006</td>
 		</tr>
 		</table>
 	</div>

data/doc/files/lib/slave_rb.html

@@ -56,7 +56,7 @@
 		</tr>
 		<tr class="top-aligned-row">
 			<td><strong>Last Update:</strong></td>
-			<td>Fri Nov 12 12:24:23 MST 2004</td>
+			<td>Thu Jun 08 15:54:54 MDT 2006</td>
 		</tr>
 		</table>
 	</div>
@@ -70,7 +70,7 @@
 			<map name="map">
   <area shape="RECT" coords="28,88,99,40"      href="../../classes/Slave.html" alt="Slave">
 </map>
-<img src="../../dot/f_2.jpg" usemap="#map" border=0 alt="TopLevel">
+<img src="../../dot/f_1.jpg" usemap="#map" border=0 alt="TopLevel">
 		</div>
 
 
@@ -82,6 +82,7 @@
 			fileutils&nbsp;&nbsp;
 			tmpdir&nbsp;&nbsp;
 			tempfile&nbsp;&nbsp;
+			fcntl&nbsp;&nbsp;
 			</div>
 		</div>
 

data/doc/fr_file_index.html

@@ -21,7 +21,6 @@
 	<h1 class="section-bar">Files</h1>
 	<div id="index-entries">
 		<a href="files/README.html">README</a><br />
-		<a href="files/VERSION.html">VERSION</a><br />
 		<a href="files/lib/slave_rb.html">lib/slave.rb</a><br />
 	</div>
 </div>

data/doc/fr_method_index.html

@@ -20,19 +20,25 @@
 <div id="index">
 	<h1 class="section-bar">Methods</h1>
 	<div id="index-entries">
-		<a href="classes/Slave/Heartbeat.html#M000011">child_start (Slave::Heartbeat)</a><br />
+		<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#M000005">gen_psname (Slave)</a><br />
-		<a href="classes/Slave.html#M000006">getval (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/Heartbeat.html#M000008">new (Slave::Heartbeat)</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#M000010">parent_start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000004">shutdown (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000009">start (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000012">stop (Slave::Heartbeat)</a><br />
-		<a href="classes/Slave.html#M000007">trace (Slave)</a><br />
-		<a href="classes/Slave/Heartbeat.html#M000013">trace (Slave::Heartbeat)</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 />
 	</div>
 </div>
 </body>

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

@@ -2,13 +2,43 @@ require 'drb/drb'
 require 'fileutils'
 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.
 #
   class Slave
 #--{{{
+    VERSION = '0.0.1'
+
     DEFAULT_SOCKET_CREATION_ATTEMPTS =
       Integer(ENV['SLAVE_SOCKET_CREATION_ATTEMPTS'] || 42)
 
@@ -68,9 +98,11 @@ require 'tempfile'
     attr :socket
     attr :debug
 
+    #
     # 'obj' can be any object and 'opts' may contain the keys
     # 'socket_creation_attempts', 'pulse_rate', 'psname', or 'debug'
-    def initialize obj, opts = {}
+    #
+    def initialize obj = nil, opts = {}, &block
 #--{{{
       @obj = obj
 
@@ -85,7 +117,7 @@ require 'tempfile'
 
       @shutdown = false
 
-      @heartbeat = Heartbeat::new @pulse_rate, @debug
+      # @heartbeat = Heartbeat::new @pulse_rate, @debug
       @r, @w = IO::pipe
     #
     # child
@@ -119,15 +151,16 @@ require 'tempfile'
           end
 
           if @socket and @uri
-            @heartbeat.start
+            # @heartbeat.start
             @w.write @socket 
             @w.close
             trap('SIGUSR2') do
-              @heartbeat.stop rescue nil
+              # @heartbeat.stop rescue nil
               DBb::thread.kill rescue nil
               FileUtils::rm_f @socket rescue nil
               exit!
             end
+            block[obj] if block
             DRb::thread.join
           else
             @w.close
@@ -152,7 +185,7 @@ require 'tempfile'
           at_exit{ FileUtils::rm_f @socket }
           @uri = "drbunix://#{ socket }"
           trace{ "parent - uri <#{ @uri }>" }
-          @heartbeat.start
+          # @heartbeat.start
         #
         # starting drb on localhost avoids dns lookups!
         #
@@ -164,30 +197,38 @@ require 'tempfile'
       end
 #--}}}
     end
+    #
     # 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
+    #
     def gen_psname obj
 #--{{{
       "#{ obj.class }_slave_of_#{ Process::pid }".downcase
 #--}}}
     end
-    # see docs for class.getval
+    #
+    # see docs for Slave.getval
+    #
     def getval key, opts = {}
 #--{{{
       self.class.getval key
 #--}}}
     end
+    #
     # debugging output
+    #
     def trace
 #--{{{
       STDERR.puts(yield) if @debug and STDERR.tty?
@@ -223,6 +264,7 @@ require 'tempfile'
         if Process::pid == @pid
           @w.close
           @pipe = @r
+          @pipe.fcntl Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
           parent_start
         else
           @r.close
@@ -273,6 +315,58 @@ require 'tempfile'
           end
 #--}}}
       end
+
+      def start 
+#--{{{
+        if Process::pid == @pid
+          @r.close
+          @pipe = @w
+          @pipe.fcntl Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
+          parent_start
+        else
+          @w.close
+          @pipe = @r
+          child_start
+        end
+        @beating = true 
+#--}}}
+      end
+      def parent_start
+#--{{{
+        @whoami = 'parent' 
+        @thread =
+          Thread::new(Thread::current) do |cur|
+            begin
+              sleep
+            rescue => e
+              cur.raise e
+            ensure
+              @pipe.close rescue nil
+            end
+          end
+#--}}}
+      end
+      def child_start
+#--{{{
+        @whoami = 'child' 
+        @pid = Process::pid
+        @ppid = Process::ppid
+        @thread =
+          Thread::new(Thread::current) do |cur|
+            begin
+            trace{ "child reading..." }
+              @pipe.read
+            trace{ "child read." }
+            trace{ "child exiting." }
+            exit!
+            rescue => e
+              cur.raise e
+            ensure
+              @pipe.close rescue nil
+            end
+          end
+#--}}}
+      end
       def stop 
 #--{{{
         raise "not beating" unless @beating

data/lib/slave.rb

@@ -2,13 +2,35 @@ require 'drb/drb'
 require 'fileutils'
 require 'tmpdir'
 require 'tempfile'
+require 'fcntl'
 
 #
 # 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'
+  #
+  # config
+  #
     DEFAULT_SOCKET_CREATION_ATTEMPTS =
       Integer(ENV['SLAVE_SOCKET_CREATION_ATTEMPTS'] || 42)
 
@@ -21,7 +43,9 @@ require 'tempfile'
     @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
@@ -67,10 +91,13 @@ require 'tempfile'
     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'
-    def initialize obj, opts = {}
+  #
+  # '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
 #--{{{
       @obj = obj
 
@@ -84,6 +111,7 @@ require 'tempfile'
       trace{ "psname <#{ @psname }>" }
 
       @shutdown = false
+      @waiter = @status = nil
 
       @heartbeat = Heartbeat::new @pulse_rate, @debug
       @r, @w = IO::pipe
@@ -91,6 +119,7 @@ require 'tempfile'
     # child
     #
       unless((@pid = Slave::fork))
+        e = nil
         begin
           $0 = @psname 
           @pid = Process::pid
@@ -123,25 +152,28 @@ require 'tempfile'
             @w.write @socket 
             @w.close
             trap('SIGUSR2') do
-              @heartbeat.stop rescue nil
+              # @heartbeat.stop rescue nil
               DBb::thread.kill rescue nil
               FileUtils::rm_f @socket rescue nil
               exit!
             end
+            block[obj] if block
             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
@@ -164,7 +196,27 @@ require 'tempfile'
       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
@@ -175,19 +227,25 @@ require 'tempfile'
       @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 class.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?
@@ -195,11 +253,11 @@ require 'tempfile'
     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
 #--{{{
@@ -223,6 +281,7 @@ require 'tempfile'
         if Process::pid == @pid
           @w.close
           @pipe = @r
+          @pipe.fcntl Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
           parent_start
         else
           @r.close
@@ -273,6 +332,58 @@ require 'tempfile'
           end
 #--}}}
       end
+
+      def start 
+#--{{{
+        if Process::pid == @pid
+          @r.close
+          @pipe = @w
+          @pipe.fcntl Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
+          parent_start
+        else
+          @w.close
+          @pipe = @r
+          child_start
+        end
+        @beating = true 
+#--}}}
+      end
+      def parent_start
+#--{{{
+        @whoami = 'parent' 
+        @thread =
+          Thread::new(Thread::current) do |cur|
+            begin
+              sleep
+            rescue => e
+              cur.raise e
+            ensure
+              @pipe.close rescue nil
+            end
+          end
+#--}}}
+      end
+      def child_start
+#--{{{
+        @whoami = 'child' 
+        @pid = Process::pid
+        @ppid = Process::ppid
+        @thread =
+          Thread::new(Thread::current) do |cur|
+            begin
+            trace{ "child reading..." }
+              @pipe.read
+            trace{ "child read." }
+            trace{ "child exiting." }
+            exit!
+            rescue => e
+              cur.raise e
+            ensure
+              @pipe.close rescue nil
+            end
+          end
+#--}}}
+      end
       def stop 
 #--{{{
         raise "not beating" unless @beating

data/rdoc.cmd

@@ -1 +1 @@
-rdoc -a -d -F -S -m README -I jpg -N README VERSION lib/slave.rb
+rdoc -a -d -F -S -m README -I jpg -N README lib/slave.rb

data/sample/a.rb

@@ -1,102 +1,19 @@
-$:.unshift 'lib'
-$:.unshift '../lib'
-
 require 'slave'
 
-class Incrementer
-  attr :decrementer, true
-  def increment n
-    n + 1
-  end
-  def decrement n
-    @decrementer.decrement n
-  end
-end
-
-class Decrementer
-  attr :incrementer, true
-  def increment n
-    @incrementer.increment n
-  end
-  def decrement n
-    n - 1
-  end
-end
-
-
-#
-#
-# here we set up a triangle of communicating processes
 #
-#      incrementer------decrementer
-#           \               /
-#            \             /
-#             \           /
-#              \         /
-#               \       /
-#                 parent
+# 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
 #
-#
-
-incrementer_slave = Slave::new Incrementer::new
-incrementer = incrementer_slave.object 
 
-puts '---'
-puts 'incrementer :'
-puts "  sockect   : #{ incrementer_slave.socket.inspect }"
-puts "  uri       : #{ incrementer_slave.uri.inspect }"
-puts "  pid       : #{ incrementer_slave.pid.inspect }"
-puts
-
-decrementer_slave = Slave::new Decrementer::new
-decrementer = decrementer_slave.object 
-
-puts '---'
-puts 'decrementer :'
-puts "  sockect   : #{ decrementer_slave.socket.inspect }"
-puts "  uri       : #{ decrementer_slave.uri.inspect }"
-puts "  pid       : #{ decrementer_slave.pid.inspect }"
-puts
-
-#
-# connect incrementer and decrementer
-#
-
-incrementer.decrementer = decrementer
-decrementer.incrementer = incrementer
-
-#
-# now we can call methods on each drb object, and they can also call methods on
-# each other
-#
-
-n = 0 
-
-n = incrementer.increment n
-p n #=> 1
-
-n = decrementer.decrement n 
-p n #=> 0
-
-n = decrementer.increment n
-p n #=> 1
-
-n = incrementer.decrement n
-p n #=> 0
-
-#
-# we can explicitly shutdown certain slaves
-#
+class Server
+  def add_two n
+    n + 2
+  end
+end
 
-incrementer_slave.shutdown
-n = decrementer.decrement 43 
-p n #=> 42 
+slave = Slave.new Server.new
+server = slave.object
 
-#
-# Slaves cannot live beyond their parent so we simply exit and all living slaves
-# will eventually die.  how long it takes to die is determined by the
-# pulse_rate - the next time the Heartbeat trys to ping the parent the Slave
-# will die.
-#
+p server.add_two(40) #=> 42
 
-exit

data/sample/b.rb

@@ -0,0 +1,8 @@
+require 'slave'
+
+#
+# you can wait for a slave to finish if required
+#
+  slave = Slave.new{ p $$; sleep 2; exit 42 }
+
+  p slave.wait