RubyGems - slave - Versions diffs - 1.0.0 → 1.1.0 - Mend

slave 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

data/README +90 -17
data/README.tmpl +29 -12
data/doc/classes/Slave.html +430 -298
data/doc/classes/Slave/LifeLine.html +406 -0
data/doc/classes/Slave/ThreadSafe.html +284 -0
data/doc/classes/Slave/ThreadSafeHash.html +151 -0
data/doc/created.rid +1 -1
data/doc/files/README.html +88 -18
data/doc/files/lib/slave_rb.html +6 -2
data/doc/fr_class_index.html +3 -1
data/doc/fr_method_index.html +19 -11
data/lib/slave-1.1.0.rb +623 -0
data/lib/slave.rb +293 -203
data/samples/a.rb +3 -1
data/samples/f.rb +13 -0
data/samples/g.rb +19 -0
metadata +26 -30
data/doc/classes/(@object = Object.new).html +0 -117
data/doc/classes/(o = Object.new).html +0 -117
data/doc/classes/@object.html +0 -117
data/doc/classes/Slave/Heartbeat.html +0 -458
data/doc/classes/object.html +0 -117
data/doc/dot/f_2.dot +0 -29
data/doc/dot/f_2.jpg +0 -0
data/doc/files/VERSION.html +0 -107
data/lib/slave-1.0.0.rb +0 -533
data/slave-1.0.0.gem +0 -0

data/doc/classes/Slave/ThreadSafeHash.html ADDED Viewed

@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+	<title>Class: Slave::ThreadSafeHash</title>
+	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+	<meta http-equiv="Content-Script-Type" content="text/javascript" />
+	<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
+	<script type="text/javascript">
+	// <![CDATA[
+	function popupCode( url ) {
+		window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+	}
+	function toggleCode( id ) {
+		if ( document.getElementById )
+			elem = document.getElementById( id );
+		else if ( document.all )
+			elem = eval( "document.all." + id );
+		else
+			return false;
+		elemStyle = elem.style;
+		if ( elemStyle.display != "block" ) {
+			elemStyle.display = "block"
+		} else {
+			elemStyle.display = "none"
+		}
+		return true;
+	}
+	// Make codeblocks hidden by default
+	document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+	// ]]>
+	</script>
+</head>
+<body>
+    <div id="classHeader">
+        <h1>Slave::ThreadSafeHash <sup class="type-note">(Class)</sup></h1>
+        <table class="header-table">
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../../files/lib/slave_rb.html">
+                lib/slave.rb
+                </a>
+				<br />
+            </td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>Parent:</strong></td>
+            <td>
+                Hash
+            </td>
+        </tr>
+        </table>
+    </div>
+  <!-- banner header -->
+	<div id="bodyContent">
+	<div id="contextContent">
+		<div id="diagram">
+			<map name="map">
+  <area shape="RECT" coords="123,98,195,50"      href="../o.html" alt="o">
+  <area shape="RECT" coords="27,98,99,50"      href="../Slave.html" alt="Slave">
+</map>
+<img src="../../dot/f_1.jpg" usemap="#map" border=0 alt="TopLevel">
+		</div>
+		<div id="description">
+			<p>
+a simple thread safe hash used to map object_id to a set of file
+descriptors in the <a href="LifeLine.html">LifeLine</a> class. see
+LifeLine::FDS
+</p>
+		</div>
+		<div id="method-list">
+			<h2 class="section-bar">Methods</h2>
+			<div class="name-list">
+			<a href="#M000031">new</a>&nbsp;&nbsp;
+			</div>
+		</div>
+	</div>
+		<!-- if includes -->
+		<!-- if method_list -->
+		<div id="methods">
+			<h2 class="section-bar">Public Class methods</h2>
+			<div id="method-M000031" class="method-detail">
+				<a name="M000031"></a>
+				<div class="method-heading">
+					<a href="#M000031" class="method-signature">
+					<span class="method-name">new</span><span class="method-args">(*a, &amp;b)</span>
+					</a>
+				</div>
+				<div class="method-description">
+					<p><a class="source-toggle" href="#"
+					  onclick="toggleCode('M000031-source');return false;">[Source]</a></p>
+					<div class="method-source-code" id="M000031-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/slave.rb, line 156</span>
+156:       <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">new</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">a</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">b</span>) <span class="ruby-constant">ThreadSafe</span>.<span class="ruby-identifier">new</span>(<span class="ruby-keyword kw">super</span>) <span class="ruby-keyword kw">end</span>
+</pre>
+					</div>
+				</div>
+			</div>
+		</div>
+	</div>
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+</body>
+</html>

data/doc/created.rid CHANGED Viewed

	@@ -1 +1 @@
1	- ~~Fri~~ ~~Oct~~ 13 13:24:48 ~~MDT~~ 2006
1	+ Tue Nov 28 09:47:34 MST 2006

data/doc/files/README.html CHANGED Viewed

@@ -56,7 +56,7 @@
 		</tr>
 		<tr class="top-aligned-row">
 			<td><strong>Last Update:</strong></td>
-			<td>Fri Oct 13 13:23:22 MDT 2006</td>
+			<td>Tue Nov 28 09:47:31 MST 2006</td>
 		</tr>
 		</table>
 	</div>
@@ -87,23 +87,27 @@ SYNOPSIS
   typical usage:
-    obj = AnyClass::new
+    slave = Slave::new{ AnyObject.new }
-    slave = Slave::new 'object' =&gt; obj
+    slave.object                  #=&gt; handle on drb object
+    slave.uri                     #=&gt; uri of the drb object
+    slave.socket                  #=&gt; unix domain socket path for drb object
+    slave.psname                  #=&gt; title shown in ps/top
-    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
+    object = slave.object
+    value = object.any_method     #=&gt; use the object normally
   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
-    * dumped
+    * object : specify the slave object.  otherwise block value is used.
+    * socket_creation_attempts : specify how many attempts to create a unix domain socket will be made
+    * debug : turn on some logging to STDERR
+    * psname : specify the name that will appear in 'top' ($0)
+    * at_exit : specify a lambda to be called in the *parent* when the child dies
+    * dumped : specify that the slave object should *not* be DRbUndumped (default is DRbUndumped)
+    * threadsafe : wrap the slave object with ThreadSafe to implement gross thread safety
 </pre>
 <p>
 URIS
@@ -116,9 +120,21 @@ URIS
 HISTORY
 </p>
 <pre>
-  THIS RELEASE IS !! NOT !! BACKWARD COMPATIBLE.  NOTE NEW CTOR SYNTAX.
+  1.1.0:
+    - replaced HeartBeat class with LifeLine.
+    - __HUGE__ cleanup of file descriptor/fork management with tons of help
+      from skaar and ezra.  thanks guys!
+    - introduced Slave.object method used to return any object directory from
+      a child process.  see samples/g.rb.
+    - indroduced keyword to automatically make slave objects threadsafe.
+      remember that your slave object must be threadsafe because they are
+      being server via DRb!!!
   1.0.0:
+    - THIS RELEASE IS !! NOT !! BACKWARD COMPATIBLE.  NOTE NEW CTOR SYNTAX.
     - detach method also sets up at_exit handler.  extra protection from
       zombies.
@@ -179,10 +195,12 @@ SAMPLES
       end
       slave = Slave.new :object =&gt; Server.new
-      server = slave.object
+      server = slave.object
       p server.add_two(40) #=&gt; 42
+      slave.shutdown
   ~ &gt; ruby samples/a.rb
     42
@@ -217,7 +235,7 @@ SAMPLES
   ~ &gt; ruby samples/b.rb
     :postgresql
-    ./lib/slave.rb:276:in `initialize': undefined method `typo' for #&lt;Server:0xb7573350&gt; (NoMethodError)
+    ./lib/slave.rb:460:in `initialize': undefined method `typo' for #&lt;Server:0xb7565694&gt; (NoMethodError)
         from samples/b.rb:22:in `new'
         from samples/b.rb:22
@@ -249,9 +267,9 @@ SAMPLES
   ~ &gt; ruby samples/c.rb
-    12244
-    12245
-    ./lib/slave.rb:276:in `initialize': undefined local variable or method `fubar' for main:Object (NameError)
+    14387
+    14388
+    ./lib/slave.rb:460:in `initialize': undefined local variable or method `fubar' for main:Object (NameError)
         from samples/c.rb:21:in `new'
         from samples/c.rb:21
@@ -271,6 +289,7 @@ SAMPLES
   ~ &gt; ruby samples/d.rb
+    &quot;child&quot;
     &quot;parent&quot;
   &lt;========&lt; samples/e.rb &gt;========&gt;
@@ -292,6 +311,57 @@ SAMPLES
   ~ &gt; ruby samples/e.rb
     &quot;child&quot;
+  &lt;========&lt; samples/f.rb &gt;========&gt;
+  ~ &gt; cat samples/f.rb
+    require 'slave'
+    #
+    # slaves created previously are visible to newly created slaves - in this
+    # example the child process of slave_a communicates directly with the child
+    # process of slave_a
+    #
+      slave_a = Slave.new{ Array.new }
+      slave_b = Slave.new{ slave_a.object }
+      a, b = slave_b.object, slave_a.object
+      b &lt;&lt; 42
+      puts a #=&gt; 42
+  ~ &gt; ruby samples/f.rb
+    42
+  &lt;========&lt; samples/g.rb &gt;========&gt;
+  ~ &gt; cat samples/g.rb
+    require 'slave'
+    #
+    # Slave.object can used when you want to construct an object in another
+    # process.  in otherwords you want to fork a process and retrieve a single
+    # returned object from that process as opposed to setting up a server.
+    #
+      this = Process.pid
+      that = Slave.object{ Process.pid }
+      p 'this' =&gt; this, 'that' =&gt; that
+    #
+    # any object can be returned and it can be returned asychronously via a thread
+    #
+      thread = Slave.object(:async =&gt; true){ sleep 2 and [ Process.pid, Time.now ] }
+      this = [ Process.pid, Time.now ]
+      that = thread.value
+      p 'this' =&gt; this, 'that' =&gt; that
+  ~ &gt; ruby samples/g.rb
+    {&quot;that&quot;=&gt;14406, &quot;this&quot;=&gt;14405}
+    {&quot;that&quot;=&gt;[14407, Tue Nov 28 09:47:31 MST 2006], &quot;this&quot;=&gt;[14405, Tue Nov 28 09:47:29 MST 2006]}
 </pre>
 		</div>

data/doc/files/lib/slave_rb.html CHANGED Viewed

@@ -56,7 +56,7 @@
 		</tr>
 		<tr class="top-aligned-row">
 			<td><strong>Last Update:</strong></td>
-			<td>Fri Oct 13 13:24:25 MDT 2006</td>
+			<td>Tue Nov 28 09:47:22 MST 2006</td>
 		</tr>
 		</table>
 	</div>
@@ -84,6 +84,8 @@
 			tmpdir&nbsp;&nbsp;
 			tempfile&nbsp;&nbsp;
 			fcntl&nbsp;&nbsp;
+			socket&nbsp;&nbsp;
+			sync&nbsp;&nbsp;
 			</div>
 		</div>
@@ -96,7 +98,9 @@
 			<h2 class="section-bar">Classes and Modules</h2>
 			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 />
+&nbsp;&nbsp;::Class <a href="../../classes/Slave/LifeLine.html" class="link">Slave::LifeLine</a><br />
+&nbsp;&nbsp;::Class <a href="../../classes/Slave/ThreadSafe.html" class="link">Slave::ThreadSafe</a><br />
+&nbsp;&nbsp;::Class <a href="../../classes/Slave/ThreadSafeHash.html" class="link">Slave::ThreadSafeHash</a><br />
 Class <a href="../../classes/o.html" class="link">o</a><br />
 		</div>

data/doc/fr_class_index.html CHANGED Viewed

@@ -21,7 +21,9 @@
 	<h1 class="section-bar">Classes</h1>
 	<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/Slave/LifeLine.html">Slave::LifeLine</a><br />
+		<a href="classes/Slave/ThreadSafe.html">Slave::ThreadSafe</a><br />
+		<a href="classes/Slave/ThreadSafeHash.html">Slave::ThreadSafeHash</a><br />
 		<a href="classes/o.html">o</a><br />
 	</div>
 </div>

data/doc/fr_method_index.html CHANGED Viewed

@@ -20,26 +20,34 @@
 <div id="index">
 	<h1 class="section-bar">Methods</h1>
 	<div id="index-entries">
-		<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/LifeLine.html#M000026">catch (Slave::LifeLine)</a><br />
+		<a href="classes/Slave/ThreadSafe.html#M000022">class (Slave::ThreadSafe)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000030">cling (Slave::LifeLine)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000027">close_unused_sockets_after_forking (Slave::LifeLine)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000028">cut (Slave::LifeLine)</a><br />
 		<a href="classes/Slave.html#M000002">default (Slave)</a><br />
+		<a href="classes/Slave.html#M000012">default (Slave)</a><br />
 		<a href="classes/Slave.html#M000006">detach (Slave)</a><br />
+		<a href="classes/Slave/ThreadSafe.html#M000018">ex (Slave::ThreadSafe)</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#M000013">getopts (Slave)</a><br />
+		<a href="classes/Slave/ThreadSafe.html#M000021">inspect (Slave::ThreadSafe)</a><br />
+		<a href="classes/Slave/ThreadSafe.html#M000019">method_missing (Slave::ThreadSafe)</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/ThreadSafe.html#M000017">new (Slave::ThreadSafe)</a><br />
+		<a href="classes/Slave/ThreadSafeHash.html#M000031">new (Slave::ThreadSafeHash)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000023">new (Slave::LifeLine)</a><br />
+		<a href="classes/Slave.html#M000015">object (Slave)</a><br />
+		<a href="classes/Slave.html#M000016">object (Slave)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000029">on_cut (Slave::LifeLine)</a><br />
+		<a href="classes/Slave/LifeLine.html#M000024">owner? (Slave::LifeLine)</a><br />
+		<a href="classes/Slave/ThreadSafe.html#M000020">respond_to? (Slave::ThreadSafe)</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/LifeLine.html#M000025">throw (Slave::LifeLine)</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 />

data/lib/slave-1.1.0.rb ADDED Viewed

@@ -0,0 +1,623 @@
+require 'drb/drb'
+require 'fileutils'
+require 'tmpdir'
+require 'tempfile'
+require 'fcntl'
+require 'socket'
+require 'sync'
+# TODO - lifeline need close-on-exec set in it!
+#
+# the Slave class encapsulates the work of setting up a drb server in another
+# process running on localhost via unix domain sockets.  the slave process is
+# attached to it's parent via a LifeLine 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 '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 = '1.1.0'
+    def self.version() VERSION end
+  #
+  # env config
+  #
+    DEFAULT_SOCKET_CREATION_ATTEMPTS = Integer(ENV['SLAVE_SOCKET_CREATION_ATTEMPTS'] || 42)
+    DEFAULT_DEBUG = (ENV['SLAVE_DEBUG'] ? true : false)
+    DEFAULT_THREADSAFE = (ENV['SLAVE_THREADSAFE'] ? true : false)
+  #
+  # class initialization
+  #
+    @socket_creation_attempts = DEFAULT_SOCKET_CREATION_ATTEMPTS
+    @debug = DEFAULT_DEBUG
+    @threadsafe = DEFAULT_THREADSAFE
+  #
+  # class methods
+  #
+    class << self
+#--{{{
+      # defineds how many attempts will be made to create a temporary unix domain
+      # socket
+      attr :socket_creation_attempts, true
+      # if this is true and you are running from a terminal information is printed
+      # on STDERR
+      attr :debug, true
+      # if this is true all slave objects will be wrapped such that any call
+      # to the object is threadsafe.  if you do not use this you must ensure
+      # that your objects are threadsafe __yourself__ as this is required of
+      # any object acting as a drb server
+      attr :threadsafe, true
+      # get a default value
+      def default key
+#--{{{
+        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
+#--{{{
+        v = $VERBOSE
+        begin
+          $VERBOSE = nil
+          Process::fork &block
+        ensure
+        $VERBOSE = v
+        end
+#--}}}
+      end
+#--}}}
+    end
+  #
+  # helper classes
+  #
+  #
+  # ThreadSafe is a delegate wrapper class used for implementing gross thread
+  # safety around existing objects.  when an object is wrapped with this class
+  # as
+  #
+  #   ts = ThreadSafe.new{ AnyObject.new }
+  #
+  # then ts can be used exactly as the normal object would have been, only all
+  # calls are now thread safe.  this is the mechanism behind the
+  # 'threadsafe'/:threadsafe keyword to Slave#initialize
+  #
+    class ThreadSafe
+#--{{{
+      instance_methods.each{|m| undef_method unless m[%r/__/]}
+      def initialize object
+        @object = object
+        @sync = Sync.new
+      end
+      def ex
+        @sync.synchronize{ yield }
+      end
+      def method_missing m, *a, &b
+        ex{ @object.send m, *a, &b }
+      end
+      def respond_to? m
+        ex{ @object.respond_to? m }
+      end
+      def inspect
+        ex{ @object.inspect }
+      end
+      def class
+        ex{ @object.class }
+      end
+#--}}}
+    end
+  #
+  # a simple thread safe hash used to map object_id to a set of file
+  # descriptors in the LifeLine class.  see LifeLine::FDS
+  #
+    class ThreadSafeHash < Hash
+      def self.new(*a, &b) ThreadSafe.new(super) end
+    end
+  #
+  # the LifeLine class is used to communitacte between child and parent
+  # processes and to prevent child processes from ever becoming zombies or
+  # otherwise abandoned by their parents.  the basic concept is that a socket
+  # pair is setup between child and parent.  the child process, because it is
+  # a Slave, sets up a handler such that, should it's socket ever grow stale,
+  # will exit the process.  this class replaces the HeartBeat class from
+  # previous Slave versions.
+  #
+    class LifeLine
+#--{{{
+      FDS = ThreadSafeHash.new
+      def initialize
+        @pair = Socket.pair Socket::AF_UNIX, Socket::SOCK_STREAM, 0
+        @owner = Process.pid
+        @pid = nil
+        @socket = nil
+        @object_id = object_id
+        @fds = @pair.map{|s| s.fileno}
+        oid, fds = @object_id, @fds
+        FDS[oid] = fds
+        ObjectSpace.define_finalizer(self){ FDS.delete oid }
+      end
+      def owner?
+        Process.pid == @owner
+      end
+      def throw *ignored
+        raise unless owner?
+        @pair[-1].close
+        @pair[-1] = nil
+        @pid = Process.pid
+        @socket = @pair[0]
+        @socket.sync = true
+      end
+      def catch *ignored
+        raise if owner?
+        @pair[0].close
+        @pair[0] = nil
+        @pid = Process.pid
+        @socket = @pair[-1]
+        @socket.sync = true
+        close_unused_sockets_after_forking
+      end
+      def close_unused_sockets_after_forking
+        begin
+          to_delete = []
+          begin
+            FDS.each do |oid, fds|
+              next if oid == @object_id
+              begin
+                IO.for_fd(fds.first).close
+              rescue Exception => e
+                STDERR.puts "#{ e.message } (#{ e.class })\n#{ e.backtrace.join 10.chr }"
+              ensure
+                to_delete << oid
+              end
+            end
+          ensure
+            FDS.ex{ to_delete.each{|oid| FDS.delete oid rescue 42} }
+          end
+          GC.start
+        rescue Exception => e
+          42
+        end
+      end
+      def cut
+        raise unless owner?
+        raise unless @socket
+        @socket.close rescue nil
+        FDS.delete object_id
+      end
+      alias_method "release", "cut"
+      DELEGATED = %w( puts gets read write close flush each )
+      DELEGATED.each do |m|
+        code = <<-code
+          def #{ m }(*a, &b)
+            raise unless @socket
+            @socket.#{ m } *a, &b
+          end
+        code
+        module_eval code, __FILE__, __LINE__
+      end
+      def on_cut &b
+        at_exit{ begin; b.call; ensure; b = nil; end if b}
+        Thread.new(Thread.current){|current|
+          Thread.current.abort_on_exception = true
+          begin
+            each{|*a|}
+          rescue Exception
+            current.raise $!
+            42
+          ensure
+            begin; b.call; ensure; b = nil; end if b
+          end
+        }
+      end
+      def cling &b
+        on_cut{ begin; b.call if b; ensure; Kernel.exit; end }.join
+      end
+#--}}}
+    end
+  #
+  # attrs
+  #
+    attr :obj
+    attr :socket_creation_attempts
+    attr :debug
+    attr :psname
+    attr :at_exit
+    attr :dumped
+    attr :shutdown
+    attr :status
+    attr :object
+    attr :pid
+    attr :ppid
+    attr :uri
+    attr :socket
+  #
+  # sets up a child process serving any object as a DRb server running locally
+  # on unix domain sockets.  the child process has a LifeLine established
+  # between it and the parent, making it impossible for the child to outlive
+  # the parent (become a zombie).  the object to serve is specfied either
+  # directly using the 'object'/:object keyword
+  #
+  #   Slave.new :object => MyServer.new
+  #
+  # or, preferably, using the block form
+  #
+  #   Slave.new{ MyServer.new }
+  #
+  # when the block form is used the object is contructed in the child process
+  # itself.  this is quite advantageous if the child object consumes resources
+  # or opens file handles (db connections, etc).  by contructing the object in
+  # the child any resources are consumed from the child's address space and
+  # things like open file handles will not be carried into subsequent child
+  # processes (via standard unix fork semantics).  in the event that a block
+  # is specified but the object cannot be constructed and, instead, throws and
+  # Exception, that exception will be propogated to the parent process.
+  #
+  # opts may contain the following keys, as either strings or symbols
+  #
+  #   object : specify the slave object.  otherwise block value is used.
+  #   socket_creation_attempts : specify how many attempts to create a unix domain socket will be made
+  #   debug : turn on some logging to STDERR
+  #   psname : specify the name that will appear in 'top' ($0)
+  #   at_exit : specify a lambda to be called in the *parent* when the child dies
+  #   dumped : specify that the slave object should *not* be DRbUndumped (default is DRbUndumped)
+  #   threadsafe : wrap the slave object with ThreadSafe to implement gross thread safety
+  #
+    def initialize opts = {}, &block
+#--{{{
+      getopt = getopts opts
+      @obj = getopt['object']
+      @socket_creation_attempts = getopt['socket_creation_attempts'] || default('socket_creation_attempts')
+      @debug = getopt['debug'] || default('debug')
+      @psname = getopt['psname']
+      @at_exit = getopt['at_exit']
+      @dumped = getopt['dumped']
+      @threadsafe = getopt['threadsafe'] || default('threadsafe')
+      raise ArgumentError, 'no slave object or slave object block provided!' if
+        @obj.nil? and block.nil?
+      @shutdown = false
+      @waiter = @status = nil
+      @lifeline = LifeLine.new
+      # weird syntax because dot/rdoc chokes on this!?!?
+      init_failure = lambda do |e|
+        trace{ %Q[#{ e.message } (#{ e.class })\n#{ e.backtrace.join "\n" }] }
+        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
+          Kernel.at_exit{ Kernel.exit! }
+          @lifeline.catch
+          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
+          if @threadsafe
+            @object = ThreadSafe.new @object
+          end
+          @ppid, @pid = Process::ppid, Process::pid
+          @socket = nil
+          @uri = nil
+          tmpdir, basename = Dir::tmpdir, File::basename(@psname)
+          @socket_creation_attempts.times do |attempt|
+            se = nil
+            begin
+              s = File::join(tmpdir, "#{ basename }_#{ attempt }_#{ rand }")
+              u = "drbunix://#{ s }"
+              DRb::start_service u, @object
+              @socket = s
+              @uri = u
+              trace{ "child - socket <#{ @socket }>" }
+              trace{ "child - uri <#{ @uri }>" }
+              break
+            rescue Errno::EADDRINUSE => se
+              nil
+            end
+          end
+          if @socket and @uri
+            trap('SIGUSR2') do
+              DBb::thread.kill rescue nil
+              FileUtils::rm_f @socket rescue nil
+              exit
+            end
+            @lifeline.puts @socket
+            @lifeline.cling
+          else
+            @lifeline.release
+            warn "slave(#{ $$ }) could not create socket!"
+            exit
+          end
+        rescue Exception => e
+          trace{ %Q[#{ e.message } (#{ e.class })\n#{ e.backtrace.join "\n" }] }
+        ensure
+          status = e.respond_to?('status') ? e.status : 1
+          exit(status)
+        end
+    #
+    # parent
+    #
+      else
+        detach
+        @lifeline.throw
+        buf = @lifeline.gets
+        raise "failed to find slave socket" if buf.nil? or buf.strip.empty?
+        @socket = buf.strip
+        trace{ "parent - socket <#{ @socket }>" }
+        if @at_exit
+          @at_exit_thread = @lifeline.on_cut{
+            @at_exit.respond_to?('call') ? @at_exit.call(self) : send(@at_exit.to_s, self)
+          }
+        end
+        if @socket and File::exist? @socket
+          Kernel.at_exit{ FileUtils::rm_f @socket }
+          @uri = "drbunix://#{ socket }"
+          trace{ "parent - uri <#{ @uri }>" }
+        #
+        # starting drb on localhost avoids dns lookups!
+        #
+          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
+            trace{ %Q[#{ e.message } (#{ e.class })\n#{ e.backtrace.join "\n" }] }
+            raise e
+          end
+          @psname ||= gen_psname(@object)
+        else
+          raise "failed to find slave socket <#{ @socket }>"
+        end
+      end
+#--}}}
+    end
+  #
+  # 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
+#--{{{
+      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.  if the keyword 'non_block'=>true is given a
+  # thread is returned to do the waiting in an async fashion. eg
+  #
+  #   thread = slave.wait(:non_block=>true){|value| "background <#{ value }>"}
+  #
+    def wait opts = {}, &b
+#--{{{
+      b ||= lambda{|exit_status|}
+      non_block = getopts(opts)['non_block']
+      non_block ? Thread.new{ b[ @waiter.value ] } : b[ @waiter.value ]
+#--}}}
+    end
+    alias :wait2 :wait
+  #
+  # cuts the lifeline and kills the child process - give the key 'quiet' to
+  # ignore errors shutting down, including having already shutdown
+  #
+    def shutdown opts = {}
+#--{{{
+      quiet = getopts(opts)['quiet']
+      raise "already shutdown" if @shutdown unless quiet
+      begin; Process::kill 'SIGUSR2', @pid; rescue Exception => e; end
+      begin; @lifeline.cut; rescue Exception; end
+      raise e if e unless quiet
+      @shutdown = true
+#--}}}
+    end
+  #
+  # true
+  #
+    def shutdown?
+#--{{{
+      @shutdown
+#--}}}
+    end
+  #
+  # generate a default name to appear in ps/top
+  #
+    def gen_psname obj
+#--{{{
+      "slave_#{ 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.getopts
+  #
+    def getopts opts
+#--{{{
+      self.class.getopts opts
+#--}}}
+    end
+  #
+  # debugging output - ENV['SLAVE_DEBUG']=1 to enable
+  #
+    def trace
+#--{{{
+      if @debug
+        STDERR.puts yield
+        STDERR.flush
+      end
+#--}}}
+    end
+  #
+  # a simple convenience method which returns an *object* from another
+  # process.  the object returned is the result of the supplied block. eg
+  #
+  #   object = Slave.object{ processor_intensive_object_built_in_child_process() }
+  #
+  # eg.
+  #
+  # the call can be made asynchronous via the 'async'/:async keyword
+  #
+  #   thread = Slave.object(:async=>true){ long_processor_intensive_object_built_in_child_process() }
+  #
+  #   # go on about your coding business then, later
+  #
+  #   object = thread.value
+  #
+    def self.object opts = {}, &b
+#--{{{
+      l = lambda{ begin; b.call; ensure; exit; end }
+      async = opts.delete('async') || opts.delete(:async)
+      opts['object'] = opts[:object] = l
+      opts['dumped'] = opts[:dumped] = true
+      slave = Slave.new opts
+      async ? Thread.new{ slave.object.call } : slave.object.call
+#--}}}
+    end
+    def self.object opts = {}, &b
+#--{{{
+      async = opts.delete('async') || opts.delete(:async)
+      opts['object'] = opts[:object] = lambda(&b)
+      opts['dumped'] = opts[:dumped] = true
+      slave = Slave.new opts
+      value = lambda do |slave|
+        begin
+          slave.object.call
+        ensure
+          slave.shutdown
+        end
+      end
+      async ? Thread.new{ value[slave] } : value[slave]
+#--}}}
+    end
+#--}}}
+  end # class Slave