celluloid 0.0.1

data/lib/celluloid.rb

@@ -0,0 +1,19 @@
+module Celluloid
+  VERSION = File.read File.expand_path('../../VERSION', __FILE__)
+  
+  def self.version; VERSION; end
+end
+
+require 'celluloid/actor'
+require 'celluloid/actor_proxy'
+require 'celluloid/calls'
+require 'celluloid/core_ext'
+require 'celluloid/events'
+require 'celluloid/linking'
+require 'celluloid/mailbox'
+require 'celluloid/registry'
+require 'celluloid/responses'
+require 'celluloid/supervisor'
+require 'celluloid/waker'
+
+require 'celluloid/future'

data/lib/celluloid/actor.rb

@@ -0,0 +1,179 @@
+module Celluloid
+  # Raised when trying to do Actor-like things outside Actor-space
+  class NotActorError < StandardError; end
+  
+  # Raised when we're asked to do something to a dead actor
+  class DeadActorError < StandardError; end
+  
+  # Raised when the caller makes an error that shouldn't crash this actor
+  class AbortError < StandardError
+    attr_reader :cause
+    
+    def initialize(cause)
+      @cause = cause
+      super "caused by #{cause.inspect}: #{cause.to_s}"
+    end
+  end
+  
+  # Actors are Celluloid's concurrency primitive. They're implemented as
+  # normal Ruby objects wrapped in threads which communicate with asynchronous
+  # messages. The implementation is inspired by Erlang's gen_server
+  module Actor
+    attr_reader :mailbox
+    
+    # Methods added to classes which include Celluloid::Actor
+    module ClassMethods
+      # Retrieve the exit handler method for this class
+      attr_reader :exit_handler
+      
+      # Create a new actor
+      def spawn(*args, &block)
+        actor = allocate
+        proxy = actor.__start_actor
+        proxy.send(:initialize, *args, &block)
+        proxy
+      end
+      
+      # Create a new actor and link to the current one
+      def spawn_link(*args, &block)
+        current_actor = Thread.current[:actor]
+        raise NotActorError, "can't link outside actor context" unless current_actor
+        
+        # FIXME: this is a bit repetitive with the code above
+        actor = allocate
+        proxy = actor.__start_actor
+        current_actor.link actor
+        proxy.send(:initialize, *args, &block)
+        
+        proxy
+      end
+      
+      # Create a supervisor which ensures an instance of an actor will restart
+      # an actor if it fails
+      def supervise(*args, &block)
+        Celluloid::Supervisor.supervise(self, *args, &block)
+      end
+      
+      # Create a supervisor which ensures an instance of an actor will restart
+      # an actor if it fails, and keep the actor registered under a given name
+      def supervise_as(name, *args, &block)
+        Celluloid::Supervisor.supervise_as(name, self, *args, &block)
+      end
+      
+      # Trap errors from actors we're linked to when they exit
+      def trap_exit(callback)
+        @exit_handler = callback.to_sym
+      end
+    end
+    
+    # Instance methods added to the public API
+    module InstanceMethods
+      # Is this object functioning as an actor?
+      def actor?
+        !!@mailbox
+      end
+      
+      # Is this actor alive?
+      def alive?
+        @thread.alive?
+      end
+      
+      # Raise an exception in caller context, but stay running
+      def abort(cause)
+        raise AbortError.new(cause)
+      end
+      
+      def inspect
+        return super unless actor?
+        str = "#<Celluloid::Actor(#{self.class}:0x#{self.object_id.to_s(16)})"
+        
+        ivars = []
+        instance_variables.each do |ivar|
+          next if %w(@mailbox @links @proxy @thread).include? ivar.to_s
+          ivars << "#{ivar}=#{instance_variable_get(ivar).inspect}"
+        end
+        
+        str << " " << ivars.join(' ') unless ivars.empty?      
+        str << ">"
+      end
+    end
+    
+    # Internal methods not intended as part of the public API
+    module InternalMethods
+      # Actor-specific initialization and startup
+      def __start_actor(*args, &block)
+        @mailbox = Mailbox.new
+        @links   = Links.new
+        @proxy   = ActorProxy.new(self, @mailbox)
+        
+        @thread  = Thread.new do
+          Thread.current[:actor]   = self
+          Thread.current[:mailbox] = @mailbox
+          __run_actor
+        end
+        
+        @proxy
+      end
+                
+      # Run the actor
+      def __run_actor
+        __process_messages
+      rescue Exception => ex
+        __handle_crash(ex)
+      end
+    
+      # Process incoming messages
+      def __process_messages
+        while true # instead of loop, for speed!
+          begin
+            call = @mailbox.receive
+          rescue ExitEvent => event
+            __handle_exit(event)
+            retry
+          end
+            
+          call.dispatch(self)
+        end
+      end
+      
+      # Handle exit events received by this actor
+      def __handle_exit(exit_event)
+        exit_handler = self.class.exit_handler
+        raise exit_event.reason unless exit_handler
+        
+        send exit_handler, exit_event.actor, exit_event.reason
+      end
+    
+      # Handle any exceptions that occur within a running actor
+      def __handle_crash(exception)
+        __log_error(exception)
+        @mailbox.cleanup
+        
+        # Report the exit event to all actors we're linked to
+        exit_event = ExitEvent.new(@proxy, exception)
+        
+        # Propagate the error to all linked actors
+        @links.each do |actor|
+          actor.mailbox.system_event exit_event
+        end
+      rescue Exception => handler_exception
+        __log_error(handler_exception, "/!\\ EXCEPTION IN ERROR HANDLER /!\\")
+      ensure
+        Thread.current.exit
+      end
+      
+      # Log errors when an actor crashes
+      # FIXME: This should probably thunk to a real logger
+      def __log_error(ex, prefix = "!!! CRASH")
+        puts "#{prefix} #{self.class}: #{ex.class}: #{ex.to_s}\n#{ex.backtrace.join("\n")}"
+      end
+    end
+  
+    def self.included(klass)
+      klass.extend ClassMethods
+      klass.send :include, InstanceMethods
+      klass.send :include, InternalMethods
+      klass.send :include, Linking
+    end
+  end
+end

data/lib/celluloid/actor_proxy.rb

@@ -0,0 +1,81 @@
+module Celluloid
+  # A proxy object returned from Celluloid::Actor.spawn/spawn_link which
+  # dispatches calls and casts to normal Ruby objects which are running inside
+  # of their own threads.
+  class ActorProxy
+    # FIXME: not nearly enough methods are delegated here
+    attr_reader :mailbox
+    
+    def initialize(actor, mailbox)
+      @actor, @mailbox = actor, mailbox
+    end
+    
+    def send(meth, *args, &block)
+      __call :send, meth, *args, &block
+    end
+    
+    def respond_to?(meth)
+      __call :respond_to?, meth
+    end
+    
+    def methods(include_ancestors = true)
+      __call :methods, include_ancestors
+    end
+    
+    def alive?
+      @actor.alive?
+    end
+    
+    def inspect
+      return __call :inspect if alive?
+      "#<Celluloid::Actor(#{@actor.class}:0x#{@actor.object_id.to_s(16)}) dead>"
+    end
+    
+    # method_missing black magic to call bang predicate methods asynchronously
+    def method_missing(meth, *args, &block)
+      # bang methods are async calls
+      if meth.to_s.match(/!$/) 
+        unbanged_meth = meth.to_s.sub(/!$/, '')
+        our_mailbox = Thread.current.mailbox
+        
+        begin
+          @mailbox << AsyncCall.new(our_mailbox, unbanged_meth, args, block)
+        rescue MailboxError
+          # Silently swallow asynchronous calls to dead actors. There's no way
+          # to reliably generate DeadActorErrors for async calls, so users of
+          # async calls should find other ways to deal with actors dying
+          # during an async call (i.e. linking/supervisors)
+        end
+        
+        return # casts are async and return immediately
+      end
+      
+      __call(meth, *args, &block)
+    end
+    
+    # Make a synchronous call to the actor we're proxying to
+    def __call(meth, *args, &block)
+      our_mailbox = Thread.current.mailbox
+      call = SyncCall.new(our_mailbox, meth, args, block)
+      
+      begin
+        @mailbox << call
+      rescue MailboxError
+        raise DeadActorError, "attempted to call a dead actor"
+      end
+      
+      response = our_mailbox.receive do |msg|
+        msg.is_a? Response and msg.call == call
+      end
+      
+      case response
+      when SuccessResponse
+        response.value
+      when ErrorResponse
+        raise response.value
+      else
+        raise "don't know how to handle #{response.class} messages!"
+      end
+    end
+  end
+end

data/lib/celluloid/calls.rb

@@ -0,0 +1,56 @@
+module Celluloid
+  # Calls represent requests to an actor
+  class Call
+    attr_reader :caller, :method, :arguments, :block
+    
+    def initialize(caller, method, arguments, block)
+      @caller, @method, @arguments, @block = caller, method, arguments, block
+    end
+  end
+  
+  # Synchronous calls wait for a response
+  class SyncCall < Call
+    def dispatch(obj)
+      unless obj.respond_to? @method
+        exception = NoMethodError.new("undefined method `#{@method}' for #{obj.inspect}")
+        @caller << ErrorResponse.new(self, exception)
+        return
+      end
+      
+      begin
+        result = obj.send @method, *@arguments, &@block
+      rescue AbortError => exception
+        # Aborting indicates a protocol error on the part of the caller
+        # It should crash the caller, but the exception isn't reraised
+        @caller << ErrorResponse.new(self, exception.cause)
+        return
+      rescue Exception => exception
+        # Exceptions that occur during synchronous calls are reraised in the
+        # context of the caller
+        @caller << ErrorResponse.new(self, exception)
+        
+        # They should also crash the actor where they occurred
+        raise exception
+      end
+          
+      @caller << SuccessResponse.new(self, result)
+      true
+    end
+    
+    def cleanup
+      exception = DeadActorError.new("attempted to call a dead actor")
+      @caller << ErrorResponse.new(self, exception)
+    end
+  end
+  
+  # Asynchronous calls don't wait for a response
+  class AsyncCall < Call
+    def dispatch(obj)
+      obj.send(@method, *@arguments, &@block) if obj.respond_to? @method
+    rescue AbortError
+      # Swallow aborted async calls, as they indicate the caller made a mistake
+      # FIXME: this should probably get logged
+    end
+  end
+end
+    

data/lib/celluloid/core_ext.rb

@@ -0,0 +1,6 @@
+# Monkeypatch Thread to allow lazy access to its Celluloid::Mailbox
+class Thread
+  def mailbox
+    @mailbox ||= Celluloid::Mailbox.new
+  end
+end

data/lib/celluloid/events.rb

@@ -0,0 +1,14 @@
+module Celluloid
+  # Exceptional system events which need to be processed out of band
+  class SystemEvent < Exception; end
+  
+  # An actor has exited for the given reason
+  class ExitEvent < SystemEvent
+    attr_reader :actor, :reason
+    
+    def initialize(actor, reason)
+      @actor, @reason = actor, reason
+      super reason.to_s
+    end
+  end
+end

data/lib/celluloid/future.rb

@@ -0,0 +1,28 @@
+module Celluloid
+  def self.Future(*args, &block)
+    future = Celluloid::Future.spawn(*args, &block)
+    future.run!
+    future
+  end
+  
+  class Future
+    include Celluloid::Actor
+    
+    def initialize(*args, &block)
+      @args, @block = args, block
+    end
+    
+    def run
+      @called = true
+      @value = @block[*@args]
+    rescue Exception => error
+      @error = error
+    end
+    
+    def value
+      raise "not run yet" unless @called
+      abort @error if @error
+      @value
+    end
+  end
+end

data/lib/celluloid/linking.rb

@@ -0,0 +1,75 @@
+require 'set'
+require 'thread'
+
+module Celluloid
+  # Thread safe storage of inter-actor links
+  class Links
+    include Enumerable
+    
+    def initialize
+      @links = Set.new
+      @lock  = Mutex.new
+    end
+    
+    def <<(actor)
+      @lock.synchronize do
+        @links << actor
+      end
+      actor
+    end
+    
+    def include?(actor)
+      @lock.synchronize do
+        @links.include? actor
+      end
+    end
+    
+    def delete(actor)
+      @lock.synchronize do
+        @links.delete actor
+      end
+      actor
+    end
+    
+    def each(&block)
+      @lock.synchronize do
+        @links.each(&block)
+      end
+    end
+    
+    def inspect
+      @lock.synchronize do
+        links = @links.to_a.map { |l| "#{l.class}:#{l.object_id}" }.join(',')
+        "#<Celluloid::Links[#{links}]>"
+      end
+    end
+  end
+  
+  # Support for linking actors together so they can crash or react to errors
+  module Linking
+    # Link this actor to another, allowing it to crash or react to errors
+    def link(actor)
+      actor.notify_link(@proxy)
+      self.notify_link(actor)
+    end
+    
+    # Remove links to another actor
+    def unlink(actor)
+      actor.notify_unlink(@proxy)
+      self.notify_unlink(actor)
+    end
+    
+    def notify_link(actor)
+      @links << actor
+    end
+    
+    def notify_unlink(actor)
+      @links.delete actor
+    end
+    
+    # Is this actor linked to another?
+    def linked_to?(actor)
+      @links.include? actor
+    end
+  end
+end