future_agent 0.1

data/README.rdoc

@@ -0,0 +1,32 @@
+= FutureAgent
+
+One of the things of Clojure that appeal to me are the agents. Agents in Clojure
+are functions that process their body asynchronously in a separate thread. 
+If you try to read the result of an agent before it completes, it blocks until
+the result is available. Otherwise the parallelism is transparent for the 
+enduser. 
+
+This library tries to emulate that behaviour to a certain degree; since 
+threading isn't what it could be under ruby (GIL, reentrant libraries, ... )
+I decided to work with processes instead of threads for this library.
+Since most modern unices use COW forking, doing multi-processing instead of multi-threading probably isn't as painful performance and memory wise as you might imagine.
+
+Not heavily tested at the moment, any feedback would be welcome.
+
+== Signal Handlers
+FutureAgent installs a SIGCHLD/SIGCLD handler when the class is loaded. It tries to hand off to the previous signal handler installed for the SIGCHLD/SIGCLD signals, if one was installed (caveat: handlers in classes or modules are not yet supported).
+
+This means that if you install your own SIGCLD handler after requiring FutureAgent, you have to take care to hand off any childern notifications of terminated agents to FutureAgent.handle_pid, otherwise you'll risk zombies and memory leaks (because the Zombies will eat your computes brains).
+
+== Usage
+    require 'future_agent/future_agent'
+    
+    agent = FutureAgent.fork { compute_value() }
+    # do other stuff
+    begin
+      agent.result # will block if compute_value is not done yet,
+                   # returns the result of compute_value()
+    rescue FutureAgent::ChildDied
+      # compute_value() raised an exception. deal with it here
+    end
+

data/common_test_cases

@@ -0,0 +1,11 @@
+require './lib/future_agent/future_agent'
+
+fa = FutureAgent.fork { :foo }
+fa.result
+
+fa = FutureAgent.fork { nil }
+fa.result
+
+
+fa = FutureAgent.fork { raise }
+fa.result

data/lib/future_agent/future_agent.rb

@@ -0,0 +1,143 @@
+class FutureAgent
+  class ChildDied < StandardError; end
+
+  @agents = {}
+
+=begin rdoc
+  Installs the SIGCHLD/SIGCLD signal handler for FutureAgent. Usually this
+  will not need to be invoked manually; it is invoked when the class is required.
+  If you overwrite the SIGCHLD handler somewhere after requiring this class
+  and you want to reset the default behaviour, you can call this method.
+
+  Caution: The signal handler will try to call the previously installed
+  handler for non-agent children that die. You can probably build a handler
+  invocation cycle if you aren't careful.
+=end
+  def self.setup_signal_handler
+    @old_handler = Signal.trap( "SIGCLD" ) { |signo| child_handler( signo ) }
+  end
+
+=begin rdoc
+  Handles the death of a signel agent child identified by the PID.
+  Usually invoked automatically by the FutureAgent SIGCHLD/SIGCLD handler. 
+  If you overwrite this handler with your own however, you will need to 
+  call this method to clean up the agent state if an agent dies.
+=end
+  def self.handle_pid( signal_number, pid )
+    unless @agents.has_key?( pid )
+      call_original_child_handler signal_number
+      return
+    end
+
+    agent = @agents.delete(pid)
+    agent.result if( $?.success? )
+  end
+
+
+  setup_signal_handler
+
+=begin rdoc
+  Returns a new agent instances that has been forked and is already running.
+  Retrieve the result from this agent by calling agent.result
+=end
+  def self.fork( &block )
+    agent = new( &block )
+    child_pid = agent.send :fork!
+    @agents[child_pid] = agent
+    agent
+  end
+
+  def initialize( &block ) # :nodoc:
+    @async_block = block
+  end
+
+=begin rdoc
+  Returns the result of the agent. If the result isn't available yet, calling
+  this method will block until the agent is done.
+
+  Calling this method will raise a FutureAgent::ChildDied exception if the
+  child process died with an exit status other than 0 (usually due to a raised
+  exception)
+=end
+  def result
+    return @result if defined?( @result )
+
+    begin
+      read_result
+    ensure
+      @read_pipe.close
+    end
+  end
+
+  protected
+  def self.child_handler( signal_number )
+    # since signals can get lost of too many are triggered in too short a time,
+    # we will have to loop over Process.wait until no more children can be
+    # reaped, i.e. Errno::ECHILD is raised
+    loop do
+
+      begin
+        exited_child_pid = Process.wait
+        handle_pid( signal_number, exited_child_pid )
+
+      rescue Errno::ECHILD
+        break
+      end
+
+    end
+  end
+
+  def self.call_original_child_handler( signal_number )
+    return unless @old_handler
+
+    case @old_handler
+      when String, Symbol
+        #TODO: deal with handlers in classes
+        Kernel.send @old_handler, signal_number
+
+      when Proc
+        @old_handler.call( signal_number )
+    end
+  end
+
+  def read_result
+    begin
+      @result = Marshal.load( @read_pipe.read )
+    rescue ArgumentError
+      # the write pipe closed without writing any data; this means the
+      # other side died somewhere
+      @result = nil
+      raise FutureAgent::ChildDied
+    end
+  end
+
+  def fork!
+    @read_pipe, @write_pipe = IO.pipe
+    retval = fork
+
+    if( retval ) # parent
+      @write_pipe.close
+      return retval
+
+    else         # child
+      @read_pipe.close
+      process_block
+      exit
+    end
+  end
+
+  def process_block # child method
+    begin
+      result = @async_block.call
+    rescue Exception
+      #TODO: How do we handle fatal errors/exceptions for the child?
+      #      Some debug logging would be nice... Push this task to the
+      #      user of this class for now
+      exit( -1 )
+    else
+      Marshal.dump( result, @write_pipe )
+    ensure
+      @write_pipe.close
+    end
+  end
+end

data/spec/future_agent/future_agent_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe FutureAgent do
+  describe ".fork" do
+    it "should return nil if the block gives nil" do
+      fa = FutureAgent.fork { nil }
+      fa.result.should be_nil
+    end
+
+    it "should return :foo if the block gives :foo" do
+      fa = FutureAgent.fork { :foo }
+      fa.result.should == :foo
+    end
+
+    it "should return a Time instance if the block gives Time.now" do
+      fa = FutureAgent.fork { Time.now }
+      fa.result.should be_a( Time )
+    end
+
+    it "should raise FutureAgent::ChildDied if the block raises an exception" do
+      fa = FutureAgent.fork { raise }
+      lambda { fa.result }.should raise_error( FutureAgent::ChildDied )
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$: << File.expand_path( File.join( '..', 'lib' ), __FILE__ )
+require 'future_agent/future_agent'
+

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: future_agent
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Sven Riedel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-17 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: Compute values asynchronously as seen with Clojure agents, but uses multi-processing instead of multi-threading.
+email: sr@gimp.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- lib/future_agent/future_agent.rb
+- spec/spec_helper.rb
+- spec/future_agent/future_agent_spec.rb
+- common_test_cases
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Computes values asynchronously.
+test_files: []
+