slave 0.2.0 → 1.0.0

data/README

@@ -12,49 +12,49 @@ SYNOPSIS
 
     obj = AnyClass::new
 
-    slave = Slave::new obj 
+    slave = Slave::new 'object' => obj 
 
     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
 
-  other usage: 
-
-  set the pulse_rate used for the Heartbeat
-
-    slave = Slave::new MyClass::new, 'pulse_rate' => 10
+  slaves may be configured via the environment, the Slave class, or via the
+  ctor for object itself.  attributes which may be configured include
 
-  same
+    * socket_creation_attempts
+    * pulse_rate 
+    * psname
+    * debug 
+    * dumped
 
-    Slave::pulse_rate = 10
-    slave = Slave::new MyClass::new
+URIS
 
-  same
+  http://rubyforge.org/projects/codeforpeople/
+  http://codeforpeople.com/lib/ruby/slave
 
-    ENV['SLAVE_PULSE_RATE'] = 10
-    slave = Slave::new MyClass::new
+HISTORY
 
-  to avoid having a copy of the object in both the parent and child use the
-  block form
+  THIS RELEASE IS !! NOT !! BACKWARD COMPATIBLE.  NOTE NEW CTOR SYNTAX.
 
-    slave = Slave::new{ Server::new }  # copy only in child!
-    server = slave.object
+  1.0.0:
 
-  if both an object AND a block are passed the object is passed to the block
-  in the child process
+    - detach method also sets up at_exit handler.  extra protection from
+      zombies.
 
-    slave = Slave::new(Server::new){|server| p 'in child!' }
+    - ezra zygmuntowicz asked for a feature whereby a parent could be notified
+      when a child exited.  obviously such a mechanism should be both async
+      and sync.  to accomplish this the wait method was extended to support a
+      callback with is either sync or async
 
-  slaves may be configured via the environment, the Slave class, or via the
-  ctor for object itself.  attributes which may be configured include
+        slave = Server.new{ Server.new }
 
-    * socket_creation_attempts
-    * pulse_rate 
-    * psname
-    * debug 
+        slave.wait and puts 'this is sync!'
 
-HISTORY
+        slave.wait(:non_block=>true){ 'this is async!' }
+   
+    - patch to getval from skaar<skaar@waste.org>.  the impl dropped opts
+      delgating to the class method from the instance one.
 
   0.2.0:
     incorporated joel vanderWerf's patch such that, if no object is passed the
@@ -77,3 +77,141 @@ HISTORY
 
   0.0.0:
     - initial version
+
+SAMPLES
+
+  <========< samples/a.rb >========>
+
+  ~ > cat samples/a.rb
+
+    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
+        end
+      end
+    
+      slave = Slave.new :object => Server.new
+      server = slave.object
+    
+      p server.add_two(40) #=> 42
+
+  ~ > ruby samples/a.rb
+
+    42
+
+
+  <========< samples/b.rb >========>
+
+  ~ > cat samples/b.rb
+
+    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!
+
+  ~ > ruby samples/b.rb
+
+    :postgresql
+    ./lib/slave.rb:276:in `initialize': undefined method `typo' for #<Server:0xb7573350> (NoMethodError)
+    	from samples/b.rb:22:in `new'
+    	from samples/b.rb:22
+
+
+  <========< samples/c.rb >========>
+
+  ~ > cat samples/c.rb
+
+    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
+
+  ~ > ruby samples/c.rb
+
+    12244
+    12245
+    ./lib/slave.rb:276:in `initialize': undefined local variable or method `fubar' for main:Object (NameError)
+    	from samples/c.rb:21:in `new'
+    	from samples/c.rb:21
+
+
+  <========< samples/d.rb >========>
+
+  ~ > cat samples/d.rb
+
+    require 'slave'
+    #
+    # at_exit hanlders are handled correctly in both child and parent 
+    #
+      at_exit{ p 'parent' }
+      slave = Slave.new{ at_exit{ p 'child' };  'the server is this string' }
+    #
+    # this will print 'child', then 'parent'
+    #
+
+  ~ > ruby samples/d.rb
+
+    "parent"
+
+
+  <========< samples/e.rb >========>
+
+  ~ > cat samples/e.rb
+
+    require 'slave'
+    #
+    # slaves never outlive their parent.  if the parent exits, even under kill -9,
+    # the child will die.
+    #
+      slave = Slave.new{ at_exit{ p 'child' };  'the server is this string' }
+    
+      Process.kill brutal=9, the_parent_pid=Process.pid
+    #
+    # even though parent dies a nasty death the child will still print 'child'
+    #
+
+  ~ > ruby samples/e.rb
+
+    "child"
+

data/README.tmpl

@@ -0,0 +1,83 @@
+SYNOPSIS
+
+  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. 
+
+  typical usage:
+
+    obj = AnyClass::new
+
+    slave = Slave::new 'object' => obj 
+
+    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
+
+  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
+
+URIS
+
+  http://rubyforge.org/projects/codeforpeople/
+  http://codeforpeople.com/lib/ruby/slave
+
+HISTORY
+
+  THIS RELEASE IS !! NOT !! BACKWARD COMPATIBLE.  NOTE NEW CTOR SYNTAX.
+
+  1.0.0:
+
+    - detach method also sets up at_exit handler.  extra protection from
+      zombies.
+
+    - ezra zygmuntowicz asked for a feature whereby a parent could be notified
+      when a child exited.  obviously such a mechanism should be both async
+      and sync.  to accomplish this the wait method was extended to support a
+      callback with is either sync or async
+
+        slave = Server.new{ Server.new }
+
+        slave.wait and puts 'this is sync!'
+
+        slave.wait(:non_block=>true){ 'this is async!' }
+   
+    - patch to getval from skaar<skaar@waste.org>.  the impl dropped opts
+      delgating to the class method from the instance one.
+
+  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
+
+SAMPLES
+
+@samples

data/doc/classes/(@object = Object.new).html

@@ -0,0 +1,117 @@
+<?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: (@object = Object.new)</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>(@object = Object.new) <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>
+
+        </table>
+    </div>
+  <!-- banner header -->
+
+	<div id="bodyContent">
+
+
+	<div id="contextContent">
+		<div id="diagram">
+			<map name="map">
+  <area shape="RECT" coords="27,98,99,50"      href="Slave.html" alt="Slave">
+  <area shape="RECT" coords="16,108,205,16"      href=".././classes" alt="(@object = Object.new).html (@object = Object.new)">
+</map>
+<img src="../dot/f_1.jpg" usemap="#map" border=0 alt="TopLevel">
+		</div>
+
+
+
+
+
+
+
+		<div id="attribute-list">
+			<h2 class="section-bar">Attributes</h2>
+
+			<div class="name-list">
+				<table>
+				<tr class="top-aligned-row context-row">
+					<td class="context-item-name">__slave_object_failure__</td>
+					<td class="context-item-value">&nbsp;[RW]&nbsp;</td>
+					<td class="context-item-desc"></td>
+				</tr>
+				</table>
+			</div>
+		</div>
+			
+
+	</div>
+
+
+
+		<!-- if includes -->
+
+
+		<!-- if method_list -->
+
+
+	</div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>

data/doc/classes/(o = Object.new).html

@@ -0,0 +1,117 @@
+<?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: (o = Object.new)</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>(o = Object.new) <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>
+
+        </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="Slave.html" alt="Slave">
+  <area shape="RECT" coords="16,108,205,16"      href=".././classes" alt="(o = Object.new).html (o = Object.new)">
+</map>
+<img src="../dot/f_1.jpg" usemap="#map" border=0 alt="TopLevel">
+		</div>
+
+
+
+
+
+
+
+		<div id="attribute-list">
+			<h2 class="section-bar">Attributes</h2>
+
+			<div class="name-list">
+				<table>
+				<tr class="top-aligned-row context-row">
+					<td class="context-item-name">__slave_object_failure__</td>
+					<td class="context-item-value">&nbsp;[RW]&nbsp;</td>
+					<td class="context-item-desc"></td>
+				</tr>
+				</table>
+			</div>
+		</div>
+			
+
+	</div>
+
+
+
+		<!-- if includes -->
+
+
+		<!-- if method_list -->
+
+
+	</div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>