celluloid 0.0.1

data/lib/celluloid/mailbox.rb

@@ -0,0 +1,97 @@
+require 'thread'
+
+module Celluloid
+  class MailboxError < StandardError; end # you can't message the dead
+  
+  # Actors communicate with asynchronous messages. Messages are buffered in
+  # Mailboxes until Actors can act upon them.
+  class Mailbox
+    include Enumerable
+    
+    def initialize
+      @messages = []
+      @lock  = Mutex.new
+      @waker = Waker.new
+    end
+    
+    # Add a message to the Mailbox
+    def <<(message)
+      @lock.synchronize do
+        @messages << message
+        @waker.signal
+      end
+      nil
+    rescue WakerError
+      raise MailboxError, "dead recipient"
+    end
+    
+    # Add a high-priority system event to the Mailbox
+    def system_event(event)
+      @lock.synchronize do
+        @messages.unshift event
+        
+        begin
+          @waker.signal
+        rescue WakerError
+          # Silently fail if messages are sent to dead actors
+        end
+      end
+      nil
+    end
+    
+    # Receive a message from the Mailbox
+    def receive(&block)
+      message = nil
+      
+      begin
+        @waker.wait
+        message = locate(&block)
+        raise message if message.is_a?(Celluloid::SystemEvent)
+      end while message.nil?
+        
+      message
+    rescue Celluloid::WakerError
+      cleanup # force cleanup of the mailbox
+      raise MailboxError, "mailbox cleanup called during receive"
+    end
+    
+    # Locate and remove a message from the mailbox which matches the given filter
+    def locate
+      @lock.synchronize do
+        if block_given?
+          index = @messages.index do |msg|
+            yield(msg) || msg.is_a?(Celluloid::SystemEvent)
+          end
+        
+          @messages.slice!(index, 1).first if index
+        else
+          @messages.shift
+        end
+      end
+    end
+    
+    # Cleanup any IO objects this Mailbox may be using
+    def cleanup
+      @lock.synchronize do
+        @waker.cleanup
+        @messages.each { |msg| msg.cleanup if msg.respond_to? :cleanup }
+        @messages.clear
+      end
+    end
+    
+    # Cast to an array
+    def to_a
+      @lock.synchronize { @messages.dup }
+    end
+    
+    # Iterate through the mailbox
+    def each(&block)
+      to_a.each(&block)
+    end
+    
+    # Inspect the contents of the Mailbox
+    def inspect
+      "#<Celluloid::Mailbox[#{map { |m| m.inspect }.join(', ')}]>"
+    end
+  end
+end

data/lib/celluloid/registry.rb

@@ -0,0 +1,33 @@
+require 'thread'
+
+module Celluloid
+  # The Registry allows us to refer to specific actors by human-meaningful names
+  module Registry
+    @@registry = {}
+    @@registry_lock = Mutex.new
+    
+    # Register an Actor
+    def []=(name, actor)
+      actor_singleton = class << actor; self; end
+      unless actor_singleton.ancestors.include?(Celluloid::ActorProxy)
+        raise ArgumentError, "not an actor"
+      end
+      
+      @@registry_lock.synchronize do
+        @@registry[name.to_sym] = actor
+      end
+    end
+    
+    # Retrieve an actor by name
+    def [](name)
+      @@registry_lock.synchronize do
+        @@registry[name.to_sym]
+      end
+    end
+  end
+  
+  # Extend the actor module with the registry methods
+  module Actor
+    extend Registry
+  end
+end

data/lib/celluloid/responses.rb

@@ -0,0 +1,16 @@
+module Celluloid
+  # Responses to calls
+  class Response
+    attr_reader :call, :value
+    
+    def initialize(call, value)
+      @call, @value = call, value
+    end
+  end
+  
+  # Call completed successfully
+  class SuccessResponse < Response; end
+  
+  # Call was aborted due to caller error
+  class ErrorResponse < Response; end
+end

data/lib/celluloid/supervisor.rb

@@ -0,0 +1,40 @@
+module Celluloid
+  # Supervisors are actors that watch over other actors and restart them if
+  # they crash
+  class Supervisor
+    include Actor
+    trap_exit :restart_actor
+    
+    # Retrieve the actor this supervisor is supervising
+    attr_reader :actor
+    
+    def self.supervise(klass, *args, &block)
+      spawn(nil, klass, *args, &block)
+    end
+    
+    def self.supervise_as(name, klass, *args, &block)
+      spawn(name, klass, *args, &block)
+    end
+    
+    def initialize(name, klass, *args, &block)
+      @name, @klass, @args, @block = name, klass, args, block
+      start_actor
+    end
+    
+    def start_actor
+      @actor = @klass.spawn_link(*@args, &@block)
+      Celluloid::Actor[@name] = @actor if @name
+    end
+    
+    # When actors die, regardless of the reason, restart them
+    def restart_actor(actor, reason)
+      start_actor
+    end
+    
+    def inspect
+      str = "#<Celluloid::Supervisor(#{@klass})"
+      str << " " << @args.map { |arg| arg.inspect }.join(' ') unless @args.empty?
+      str << ">"
+    end
+  end
+end

data/lib/celluloid/waker.rb

@@ -0,0 +1,41 @@
+module Celluloid
+  class WakerError < StandardError; end # You can't wake the dead
+  
+  # Wakes up sleepy threads so that they can check their mailbox
+  # Works like a ConditionVariable, except it's implemented as an IO object so
+  # that it can be multiplexed alongside other IO objects.
+  class Waker
+    PAYLOAD = "\0" # the payload doesn't matter. each byte is a signal
+    def initialize
+      @receiver, @sender = IO.pipe
+    end
+    
+    # Wakes up the thread that is waiting for this Waker
+    def signal
+      @sender << PAYLOAD
+      nil
+    rescue IOError, Errno::EPIPE, Errno::EBADF
+      raise WakerError, "waker is already dead"
+    end
+    
+    # Wait for another thread to signal this Waker
+    def wait
+        byte = @receiver.read(1)
+        raise WakerError, "can't wait on a dead waker" unless byte == PAYLOAD
+    rescue IOError
+        raise WakerError, "can't wait on a dead waker"
+    end
+    
+    # Return the IO object which will be readable when this Waker is signaled
+    def io
+      @receiver
+    end
+    
+    # Clean up the IO objects associated with this waker
+    def cleanup
+      @receiver.close rescue nil
+      @sender.close rescue nil
+      nil
+    end
+  end
+end

data/spec/actor_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+
+describe Celluloid::Actor do
+  before do
+    class MyActor
+      include Celluloid::Actor
+      attr_reader :name
+      
+      def initialize(name)
+        @name = name
+      end
+      
+      def change_name(new_name)
+        @name = new_name
+      end
+      
+      def greet
+        "Hi, I'm #{@name}"
+      end
+      
+      class Crash < StandardError; end
+      def crash
+        raise Crash, "the spec purposely crashed me :("
+      end
+      
+      def crash_with_abort(reason)
+        abort Crash.new(reason)
+      end
+    end
+  end
+  
+  it "handles synchronous calls" do
+    actor = MyActor.spawn "Troy McClure"
+    actor.greet.should == "Hi, I'm Troy McClure"
+  end
+  
+  it "raises NoMethodError when a nonexistent method is called" do
+    actor = MyActor.spawn "Billy Bob Thornton"
+    
+    proc do
+      actor.the_method_that_wasnt_there
+    end.should raise_exception(NoMethodError)
+  end
+  
+  it "reraises exceptions which occur during synchronous calls in the caller" do
+    actor = MyActor.spawn "James Dean" # is this in bad taste?
+    
+    proc do
+      actor.crash
+    end.should raise_exception(MyActor::Crash)
+  end
+  
+  it "raises exceptions in the caller when abort is called, but keeps running" do
+    actor = MyActor.spawn "Al Pacino"
+    
+    proc do
+      actor.crash_with_abort MyActor::Crash.new("You die motherfucker!")
+    end.should raise_exception(MyActor::Crash)
+    
+    actor.should be_alive
+  end
+  
+  it "raises DeadActorError if methods are synchronously called on a dead actor" do
+    actor = MyActor.spawn "James Dean"
+    actor.crash rescue nil
+    
+    proc do
+      actor.greet
+    end.should raise_exception(Celluloid::DeadActorError)
+  end
+  
+  it "handles asynchronous calls" do
+    actor = MyActor.spawn "Troy McClure"
+    actor.change_name! "Charlie Sheen"
+    actor.greet.should == "Hi, I'm Charlie Sheen"    
+  end
+  
+  it "knows when it's running as an actor" do
+    obj = MyActor.new "I'm an object"
+    obj.actor?.should be_false
+    
+    actor = MyActor.spawn "Troy McClure"
+    actor.actor?.should be_true
+  end
+  
+  it "inspects properly" do
+    actor = MyActor.spawn "Troy McClure"
+    actor.inspect.should match(/Celluloid::Actor\(MyActor/)
+    actor.inspect.should include('@name="Troy McClure"')
+    actor.inspect.should_not include("@celluloid")
+  end
+  
+  context :linking do
+    before :each do
+      @kevin   = MyActor.spawn "Kevin Bacon" # Some six degrees action here
+      @charlie = MyActor.spawn "Charlie Sheen"
+    end
+  
+    it "links to other actors" do    
+      @kevin.link @charlie
+      @kevin.linked_to?(@charlie).should be_true
+      @charlie.linked_to?(@kevin).should be_true
+    end
+    
+    it "unlinks from other actors" do
+      @kevin.link @charlie
+      @kevin.unlink @charlie
+      
+      @kevin.linked_to?(@charlie).should be_false
+      @charlie.linked_to?(@kevin).should be_false
+    end
+    
+    it "traps exit messages from other actors" do
+      class Boss # like a boss
+        include Celluloid::Actor
+        trap_exit :lambaste_subordinate
+        
+        def initialize(name)
+          @name = name
+          @subordinate_lambasted = false
+        end
+        
+        def subordinate_lambasted?; @subordinate_lambasted; end
+        
+        def lambaste_subordinate(actor, reason)
+          @subordinate_lambasted = true
+        end
+      end
+      
+      chuck = Boss.spawn "Chuck Lorre"
+      chuck.link @charlie
+      
+      proc do
+        @charlie.crash
+      end.should raise_exception(MyActor::Crash)
+      
+      sleep 0.1 # hax to prevent a race between exit handling and the next call
+      chuck.should be_subordinate_lambasted
+    end
+  end
+end

data/spec/future_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe Celluloid::Future do
+  it "creates future objects that can be retrieved later" do
+    future = Celluloid::Future() { 40 + 2 }
+    future.value.should == 42
+  end
+  
+  it "passes arguments to future blocks" do
+    future = Celluloid::Future(40) { |n| n + 2 }
+    future.value.should == 42
+  end
+  
+  it "reraises exceptions that occur when the value is retrieved" do
+    class ExampleError < StandardError; end
+    
+    future = Celluloid::Future() { raise ExampleError, "oh noes crash!" }
+    proc { future.value }.should raise_exception(ExampleError)
+  end
+end

data/spec/mailbox_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+class TestEvent < Celluloid::SystemEvent; end
+    
+describe Celluloid::Mailbox do
+  before :each do
+    @mailbox = Celluloid::Mailbox.new
+  end
+  
+  it "receives messages" do
+    message = :ohai
+    
+    @mailbox << message
+    @mailbox.receive.should == message
+  end
+  
+  it "raises system events when received" do
+    @mailbox.system_event TestEvent.new("example")
+    
+    proc do
+      @mailbox.receive
+    end.should raise_exception(TestEvent)
+  end
+  
+  it "prioritizes system events over other messages" do
+    @mailbox << :dummy1
+    @mailbox << :dummy2
+    @mailbox.system_event TestEvent.new("example")
+    
+    proc do
+      @mailbox.receive
+    end.should raise_exception(TestEvent)
+  end
+  
+  it "selectively receives messages with a block" do
+    class Foo; end
+    class Bar; end
+    class Baz; end
+    
+    foo, bar, baz = Foo.new, Bar.new, Baz.new
+    
+    @mailbox << baz
+    @mailbox << foo
+    @mailbox << bar
+    
+    @mailbox.receive { |msg| msg.is_a? Foo }.should == foo
+    @mailbox.receive { |msg| msg.is_a? Bar }.should == bar
+    @mailbox.receive.should == baz
+  end
+end