revactor 0.1.1 → 0.1.2

data/CHANGES

@@ -1,3 +1,13 @@
+0.1.2:
+
+* Change Revactor::TCP::Socket#active to #active? (same for Listener)
+
+* Fix problems with Actor#inspect reporting the wrong object ID
+
+* Initial linking implementation
+
+* Fix problems with zero-length timers
+
 0.1.1:
 
 * Eliminate Actor::Scheduler singleton and replace with thread-specific

data/README

@@ -122,6 +122,76 @@ Actor.receive returns whatever value the evaluated action returned.  This means
 you don't have to depend on side effects to extract values from receive, 
 instead you can just interpret its return value.
 
+== Handling Exceptions
+
+In a concurrent environment, dealing with exceptions can be incredibly 
+confusing.  By default, any unhandled exceptions in an Actor are logged
+and any remaining Actors continue their normal operation.  However, Actors
+also provide a powerful tool for implementing fault-tolerant systems that
+can gracefully recover from exceptions.
+
+Actors can be linked to each other:  
+
+  another_actor = Actor.spawn { puts "I'm an Actor!" }
+  Actor.link(another_actor)
+
+This can also be done as a single "atomic" operation:
+
+  actor = Actor.spawn_link { puts "I'm an Actor!" }
+
+When Actors are linked, any exceptions which occur in one will be raised in the 
+other, and vice versa.  This means if one Actor dies, any Actors it's linked to 
+will also die.  Furthermore, any Actors those are linked to also die.  This 
+occurs until the entire graph of linked Actors has been walked.
+
+In this way, you can organize Actors into large groups which all die 
+simultaneously whenever an error occurs in one.  This means that if an error
+occurs and one Actor dies, you're not left with an interdependent network of
+Actors which are in an inconsistent state.  You can kill off the whole group
+and start over fresh.
+
+But if an Actor crashing kills off every Actor it's linked to, what Actor will
+be left to restart the whole group?  The answer is that an Actor can trap
+exit events from another and receive them as messages:
+
+  Actor.current.trap_exit = true
+  actor = Actor.spawn_link { puts "I'm an Actor!" }
+  Actor.receive do |filter|
+    filter.when(Case[:exit, actor, Object]) { |msg| p msg }
+  end
+
+will print something to the effect of:
+
+  I'm an Actor!
+  [:exit, #<Actor:0x54ad6c>, nil]
+
+We were sent a message in the form:
+
+  [:exit, actor, reason]
+
+and in this case reason was nil, which informs us the Actor exited normally.
+But what if it dies due to an exception instead?
+
+  Actor.current.trap_exit = true
+  actor = Actor.spawn_link { raise "I fail!" }
+  Actor.receive do |filter|
+    filter.when(Case[:exit, actor, Object]) { |msg| p msg }
+  end
+
+We now get the entire exception, captured and delivered as a message:
+
+  [:exit, #<Actor:0x53ec24>, #<RuntimeError: I fail!>]
+
+If the Actor that died were linked to any others which were not trapping exits,
+those would all die and the ones trapping exits would remain.  This allows us
+to implement supervisors which trap exits and respond to exit messages.  The
+supervisor's job is to start an Actor initially, and if it fails log the error
+then restart it.
+
+In this way Actors can be used to build complex concurrent systems which fail
+gracefully and can respond to errors by restarting interdependent components
+of the system en masse.
+
 == Revactor::TCP
 
 The TCP module lets you perform TCP operations on top of the Actor model.  For

data/lib/revactor.rb

@@ -21,7 +21,7 @@ end
 T = Tuple unless defined? T
 
 module Revactor
-  Revactor::VERSION = '0.1.1' unless defined? Revactor::VERSION
+  Revactor::VERSION = '0.1.2' unless defined? Revactor::VERSION
   def self.version() VERSION end
 end
 

data/lib/revactor/actor.rb

@@ -22,6 +22,9 @@ class Fiber
   end
 end
 
+# Error raised when attempting to link to dead Actors
+class DeadActorError < StandardError; end
+
 # Actors are lightweight concurrency primitives which communiucate via message
 # passing.  Each actor has a mailbox which it scans for matching messages.
 # An actor sleeps until it receives a message, at which time it scans messages
@@ -45,18 +48,31 @@ class Actor
     def spawn(*args, &block)
       raise ArgumentError, "no block given" unless block
       
-      fiber = Fiber.new do
-        block.call(*args)
-        Actor.current.instance_eval { @dead = true }
-      end
-      
-      actor = Actor.new(fiber)
-      fiber.instance_eval { @_actor = actor }
+      actor = _spawn(*args, &block)
+      scheduler << actor
+      actor
+    end
+    
+    # Spawn an Actor and immediately link it to the current one
+    def spawn_link(*args, &block)
+      raise ArgumentError, "no block given" unless block
       
-      Actor.scheduler << actor
+      actor = _spawn(*args, &block)
+      current.link actor
+      scheduler << actor
       actor
     end
     
+    # Link the current Actor to another one
+    def link(actor)
+      current.link actor
+    end
+    
+    # Unlink the current Actor from another one
+    def unlink(actor)
+      current.unlink actor
+    end
+    
     # Obtain a handle to the current Actor
     def current
       Fiber.current._actor
@@ -72,13 +88,15 @@ class Actor
       if scheduler.running? 
         Fiber.yield
       else
-        Actor.scheduler << Actor.current
+        scheduler << current
       end
+      
+      current.__send__(:process_events)
     end
     
     # Sleep for the specified number of seconds
     def sleep(seconds)
-      Actor.receive { |filter| filter.after(seconds) }
+      receive { |filter| filter.after(seconds) }
     end
     
     # Wait for messages matching a given filter.  The filter object is yielded
@@ -111,6 +129,20 @@ class Actor
     def delete(key, &block)
       @@registered.delete(key, &block)
     end
+    
+    #########
+    protected
+    #########
+    
+    def _spawn(*args, &block)
+      fiber = Fiber.new do
+        block.call(*args)
+        current.instance_eval { @dead = true }
+      end
+      
+      actor = Actor.new(fiber)
+      fiber.instance_eval { @_actor = actor }
+    end
   end
   
   def initialize(fiber = Fiber.current)
@@ -120,13 +152,14 @@ class Actor
     @scheduler = Actor.scheduler
     @thread = Thread.current
     @mailbox = Mailbox.new
+    @links = []
+    @events = []
+    @trap_exit = false
     @dead = false
     @dictionary = {}
   end
   
-  def inspect
-    "#<#{self.class}:0x#{object_id.to_s(16)}>"
-  end
+  alias_method :inspect, :to_s
   
   # Look up value in the actor's dictionary
   def [](key)
@@ -163,4 +196,84 @@ class Actor
   end
 
   alias_method :send, :<<
+  
+  # Establish a bidirectional link to the given Actor and notify it of any
+  # system events which occur in this Actor (namely exits due to exceptions)
+  def link(actor)
+    actor.notify_link self
+    self.notify_link actor
+  end
+  
+  # Unestablish a link with the given actor
+  def unlink(actor)
+    actor.notify_unlink self
+    self.notify_unlink actor
+  end
+  
+  # Notify this actor that it's now linked to the given one
+  def notify_link(actor)
+    raise ArgumentError, "can only link to Actors" unless actor.is_a? Actor
+    
+    # Don't allow linking to dead actors
+    raise DeadActorError, "actor is dead" if actor.dead?
+    
+    # Ignore circular links
+    return true if actor == self
+    
+    # Ignore duplicate links
+    return true if @links.include? actor
+    
+    @links << actor
+    true
+  end
+  
+  # Notify this actor that it's now unlinked from the given one
+  def notify_unlink(actor)
+    @links.delete(actor)
+    true
+  end
+  
+  # Notify this actor that one of the Actors it's linked to has exited
+  def notify_exited(actor, reason)
+    @events << T[:exit, actor, reason]
+  end
+  
+  # Actors trapping exit do not die when an error occurs in an Actor they
+  # are linked to.  Instead the exit message is sent to their regular
+  # mailbox in the form [:exit, actor, reason].  This allows certain
+  # Actors to supervise sets of others and restart them in the event
+  # of an error.
+  def trap_exit=(value)
+    raise ArgumentError, "must be true or false" unless value == true or value == false
+    @trap_exit = value
+  end
+  
+  # Is the Actor trapping exit?
+  def trap_exit?
+    @trap_exit
+  end
+  
+  #########
+  protected
+  #########
+  
+  # Process the Actor's system event queue
+  def process_events
+    @events.each do |event|
+      type, *operands = event
+      case type
+      when :exit
+        actor, ex = operands
+        notify_unlink actor
+        
+        if @trap_exit
+          self << event
+        elsif ex
+          raise ex
+        end
+      end
+    end
+    
+    @events.clear
+  end
 end

data/lib/revactor/delegator.rb

@@ -63,7 +63,7 @@ class Revactor::Delegator
     begin
       result = @obj.__send__(meth, *args, &block)
       from << T[:call_reply, Actor.current, result]
-    rescue Exception => ex
+    rescue => ex
       from << T[:call_error, Actor.current, ex]
     end
   end

data/lib/revactor/mailbox.rb

@@ -133,15 +133,7 @@ class Actor
       
         # Don't explicitly require an action to be specified for a timeout
         @mailbox.timeout_action = action || proc {}
-      
-        if seconds > 0
-          @mailbox.timer = Timer.new(seconds, Actor.current).attach(Rev::Loop.default)
-        else
-          # No need to actually set a timer if the timeout is zero, 
-          # just short-circuit waiting for one entirely...
-          @mailbox.timed_out = true
-          Actor.scheduler << Actor.current
-        end
+        @mailbox.timer = Timer.new(seconds, Actor.current).attach(Rev::Loop.default)
       end
 
       # Match a message using the filter

data/lib/revactor/mongrel.rb

@@ -1,5 +1,4 @@
 require File.dirname(__FILE__) + '/../revactor'
-require 'rubygems'
 require 'mongrel'
 
 class Revactor::TCP::Socket

data/lib/revactor/scheduler.rb

@@ -46,7 +46,12 @@ class Actor
         @queue.each do |actor|
           begin
             actor.fiber.resume
-          rescue FiberError # Fiber may have died since being scheduled 
+            handle_exit(actor) if actor.dead?
+          rescue FiberError
+            # Handle Actors whose Fibers died after being scheduled
+            handle_exit(actor)
+          rescue => ex
+            handle_exit(actor, ex)
           end
         end
       
@@ -61,5 +66,31 @@ class Actor
     def running?
       @running
     end
+    
+    #########
+    protected
+    #########
+    
+    def handle_exit(actor, ex = nil)
+      actor.instance_eval do
+        # Mark Actor as dead
+        @dead = true
+        
+        if @links.empty?
+          Actor.scheduler.__send__(:log_exception, ex) if ex
+        else
+          # Notify all linked Actors of the exception
+          @links.each do |link|
+            link.notify_exited(actor, ex)
+            Actor.scheduler << link
+          end
+        end
+      end
+    end
+    
+    def log_exception(ex)
+      # FIXME this should go to a real logger
+      STDERR.puts "#{ex.class}: #{[ex, *ex.backtrace].join("\n\t")}"
+    end
   end
 end

data/lib/revactor/tcp.rb

@@ -63,7 +63,6 @@ module Revactor
     # TCP socket class, returned by Revactor::TCP.connect and 
     # Revactor::TCP::Listener#accept
     class Socket < Rev::TCPSocket
-      attr_reader :active
       attr_reader :controller
 
       class << self
@@ -134,6 +133,9 @@ module Revactor
         @active = state
       end
       
+      # Is the socket in active mode?
+      def active?; @active; end
+      
       # Set the controlling actor
       def controller=(controller)
         raise ArgumentError, "controller must be an actor" unless controller.is_a? Actor
@@ -323,7 +325,6 @@ module Revactor
 
     # TCP Listener returned from Revactor::TCP.listen
     class Listener < Rev::TCPListener
-      attr_reader :active
       attr_reader :controller
    
       # Listen on the specified address and port.  Accepts the following options:
@@ -359,6 +360,9 @@ module Revactor
         @active = state
       end
       
+      # Will newly accepted connections be active?
+      def active?; @active; end
+      
       # Change the default controller for newly accepted connections
       def controller=(controller)
         raise ArgumentError, "controller must be an actor" unless controller.is_a? Actor

data/revactor.gemspec

@@ -2,7 +2,7 @@ require 'rubygems'
 
 GEMSPEC = Gem::Specification.new do |s|
   s.name = "revactor"
-  s.version = "0.1.1"
+  s.version = "0.1.2"
   s.authors = "Tony Arcieri"
   s.email = "tony@medioh.com"
   s.date = "2008-1-28"

data/spec/actor_spec.rb

@@ -94,6 +94,42 @@ describe Actor do
     end
   end
   
+  describe "linking" do
+    it "forwards exceptions to linked Actors" do
+      Actor.spawn do
+        actor = Actor.spawn_link do
+          Actor.receive do |m|
+            m.when(:die) { raise 'dying' }
+          end
+        end
+    
+        proc { actor << :die; Actor.sleep 0 }.should raise_error('dying')
+      end
+    end
+    
+    it "sends normal exit messages to linked Actors which are trapping exit" do
+      Actor.spawn do
+        Actor.current.trap_exit = true
+        actor = Actor.spawn_link {}
+        Actor.receive do |m|
+          m.when(Case[:exit, actor, Object]) { |_, _, reason| reason }
+        end.should be_nil
+      end
+    end
+    
+    it "delivers exceptions to linked Actors which are trapping exit" do
+      error = RuntimeError.new("I fail!")
+      
+      Actor.spawn do
+        Actor.current.trap_exit = true
+        actor = Actor.spawn_link { raise error }
+        Actor.receive do |m|
+          m.when(Case[:exit, actor, Object]) { |_, _, reason| reason }
+        end.should == error
+      end
+    end
+  end
+  
   it "detects dead actors" do
     actor = Actor.spawn do
       Actor.receive do |filter|

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: revactor
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 date: 2008-01-28 00:00:00 -07:00
 summary: Revactor is an Actor implementation for writing high performance concurrent programs
 require_paths: