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:

    slave = Slave::new{ AnyObject.new }

    slave.object                  #=> handle on drb object
    slave.uri                     #=> uri of the drb object
    slave.socket                  #=> unix domain socket path for drb object
    slave.psname                  #=> title shown in ps/top

    object = slave.object

    value = object.any_method     #=> 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

    * 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 

URIS

  http://rubyforge.org/projects/codeforpeople/
  http://codeforpeople.com/lib/ruby/slave

HISTORY
  1.3.0:
    - fixes for 1.9.2 (undef object_id)
    - fixes for osx (too long socket names) 

  1.2.1:
    - jruby/ThreadSafe patches from skaar and ez.  using slave.rb with jruby,
      how is that!?

  1.2.0:
    - cleaned up a bunch of warnings.  thanks eric kolve <ekolve@gmail.com>
      for reporting them.

  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.

    - 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/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
    
      slave.shutdown

  ~ > 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
    samples/b.rb:22: undefined method `typo' for #<Server:0x10030aa60> (NoMethodError)
    	from ./lib/slave.rb:367:in `[]'
    	from ./lib/slave.rb:367:in `initialize'
    	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

    48871
    48872
    samples/c.rb:21: undefined local variable or method `fubar' for main:Object (NameError)
    	from ./lib/slave.rb:359:in `call'
    	from ./lib/slave.rb:359:in `initialize'
    	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

    "child"
    "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"


  <========< samples/f.rb >========>

  ~ > 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 << 42
      puts a #=> 42

  ~ > ruby samples/f.rb

    42


  <========< samples/g.rb >========>

  ~ > 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' => this, 'that' => that
    
    #
    # any object can be returned and it can be returned asychronously via a thread
    #
      thread = Slave.object(:async => true){ sleep 2 and [ Process.pid, Time.now ] }
      this = [ Process.pid, Time.now ]
      that = thread.value 
      
      p 'this' => this, 'that' => that

  ~ > ruby samples/g.rb

    {"that"=>48890, "this"=>48889}
    {"that"=>[48891, Mon Oct 10 08:21:47 -0600 2011], "this"=>[48889, Mon Oct 10 08:21:45 -0600 2011]}