celluloid 0.11.1 → 0.12.0

data/README.md

@@ -1,4 +1,4 @@
-![Celluloid](https://github.com/celluloid/celluloid/raw/master/logo.png)
+![Celluloid](https://raw.github.com/celluloid/celluloid-logos/master/celluloid/celluloid.png)
 =========
 [![Build Status](https://secure.travis-ci.org/celluloid/celluloid.png?branch=master)](http://travis-ci.org/celluloid/celluloid)
 [![Dependency Status](https://gemnasium.com/celluloid/celluloid.png)](https://gemnasium.com/celluloid/celluloid)
@@ -17,7 +17,7 @@ Much of the difficulty with building concurrent programs in Ruby arises because
 the object-oriented mechanisms for structuring code, such as classes and
 inheritance, are separate from the concurrency mechanisms, such as threads and
 locks. Celluloid combines these into a single structure, an active object
-running within a thread, called an "actor".
+running within a thread, called an "actor", or in Celluloid vernacular, a "cell".
 
 By combining concurrency with object oriented programming, Celluloid frees you
 up from worry about where to use threads and locks. Celluloid combines them
@@ -72,15 +72,32 @@ for more detailed documentation and usage notes.
 Like Celluloid? [Join the Google Group](http://groups.google.com/group/celluloid-ruby)
 or visit us on IRC at #celluloid on freenode
 
-### Is it any good?
-
-[Yes.](http://news.ycombinator.com/item?id=3067434)
-
 ### Is It "Production Ready™"?
 
 Yes, many users are now running Celluloid in production by using
 [Sidekiq](https://github.com/mperham/sidekiq)
 
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'celluloid'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install celluloid
+
+Inside of your Ruby program do:
+
+    require 'celluloid'
+
+...to pull it in as a dependency.
+
 Supported Platforms
 -------------------
 

data/lib/celluloid/actor.rb

@@ -7,6 +7,9 @@ module Celluloid
   # Trying to do something to a dead actor
   class DeadActorError < StandardError; end
 
+  # A timeout occured before the given request could complete
+  class TimeoutError < StandardError; end
+
   # The caller made an error, not the current actor
   class AbortError < StandardError
     attr_reader :cause
@@ -17,6 +20,8 @@ module Celluloid
     end
   end
 
+  LINKING_TIMEOUT = 5 # linking times out after 5 seconds
+
   # Actors are Celluloid's concurrency primitive. They're implemented as
   # normal Ruby objects wrapped in threads which communicate with asynchronous
   # messages.
@@ -64,9 +69,13 @@ module Celluloid
           # The current task will be automatically resumed when we get a response
           Task.suspend(:callwait).value
         else
-          # Otherwise we're inside a normal thread, so block
-          response = Thread.mailbox.receive do |msg|
-            msg.respond_to?(:call) and msg.call == call
+          # Otherwise we're inside a normal thread or exclusive, so block
+          response = loop do
+            message = Thread.mailbox.receive do |msg|
+              msg.respond_to?(:call) and msg.call == call
+            end
+            break message unless message.is_a?(SystemEvent)
+            Thread.current[:actor].handle_system_event(message)
           end
 
           response.value
@@ -97,18 +106,68 @@ module Celluloid
         actors = []
         Thread.list.each do |t|
           actor = t[:actor]
-          actors << actor.proxy if actor
+          actors << actor.proxy if actor and actor.respond_to?(:proxy)
         end
         actors
       end
+
+      # Watch for exit events from another actor
+      def monitor(actor)
+        raise NotActorError, "can't link outside actor context" unless Celluloid.actor?
+        Thread.current[:actor].linking_request(actor, :link)
+      end
+
+      # Stop waiting for exit events from another actor
+      def unmonitor(actor)
+        raise NotActorError, "can't link outside actor context" unless Celluloid.actor?
+        Thread.current[:actor].linking_request(actor, :unlink)
+      end
+
+      # Link to another actor
+      def link(actor)
+        monitor actor
+        Thread.current[:actor].links << actor
+      end
+
+      # Unlink from another actor
+      def unlink(actor)
+        unmonitor actor
+        Thread.current[:actor].links.delete actor
+      end
+
+      # Are we monitoring the given actor?
+      def monitoring?(actor)
+        actor.links.include? Actor.current
+      end
+
+      # Are we bidirectionally linked to the given actor?
+      def linked_to?(actor)
+        monitoring?(actor) && Thread.current[:actor].links.include?(actor)
+      end
+
+      # Forcibly kill a given actor
+      def kill(actor)
+        actor.thread.kill
+        begin
+          actor.mailbox.shutdown
+        rescue DeadActorError
+        end
+      end
+
+      # Wait for an actor to terminate
+      def join(actor)
+        actor.thread.join
+        actor
+      end
     end
 
     # Wrap the given subject with an Actor
-    def initialize(subject)
+    def initialize(subject, options = {})
       @subject      = subject
-      @mailbox      = subject.class.mailbox_factory
-      @exit_handler = subject.class.exit_handler
-      @exclusives   = subject.class.exclusive_methods
+      @mailbox      = options[:mailbox] || Mailbox.new
+      @exit_handler = options[:exit_handler]
+      @exclusives   = options[:exclusive_methods]
+      @task_class   = options[:task_class] || Celluloid.task_class
 
       @tasks     = Set.new
       @links     = Links.new
@@ -128,6 +187,33 @@ module Celluloid
       @proxy = ActorProxy.new(self)
     end
 
+    # Run the actor loop
+    def run
+      begin
+        while @running
+          if message = @mailbox.receive(timeout_interval)
+            handle_message message
+          else
+            # No message indicates a timeout
+            @timers.fire
+            @receivers.fire_timers
+          end
+        end
+      rescue MailboxShutdown
+        # If the mailbox detects shutdown, exit the actor
+      end
+
+      shutdown
+    rescue Exception => ex
+      handle_crash(ex)
+      raise unless ex.is_a? StandardError
+    end
+
+    # Terminate this actor
+    def terminate
+      @running = false
+    end
+
     # Is this actor running in exclusive mode?
     def exclusive?
       @exclusive
@@ -141,9 +227,33 @@ module Celluloid
       @exclusive = false
     end
 
-    # Terminate this actor
-    def terminate
-      @running = false
+    # Perform a linking request with another actor
+    def linking_request(receiver, type)
+      exclusive do
+        start_time = Time.now
+
+        receiver.mailbox << LinkingRequest.new(Actor.current, type)
+        system_events = []
+        loop do
+          wait_interval = start_time + LINKING_TIMEOUT - Time.now
+          message = @mailbox.receive(wait_interval) do |msg|
+            msg.is_a?(LinkingResponse) && msg.actor == receiver && msg.type == type
+          end
+
+          case message
+          when LinkingResponse
+            # We're done!
+            system_events.each { |ev| handle_system_event(ev) }
+            return
+          when NilClass
+            raise TimeoutError, "linking timeout of #{LINKING_TIMEOUT} seconds exceeded"
+          when SystemEvent
+            # Queue up pending system events to be processed after we've successfully linked
+            system_events << message
+          else raise 'wtf'
+          end
+        end
+      end
     end
 
     # Send a signal with the given name to all waiting methods
@@ -158,41 +268,16 @@ module Celluloid
 
     # Receive an asynchronous message
     def receive(timeout = nil, &block)
-      begin
-        @receivers.receive(timeout, &block)
-      rescue SystemEvent => event
-        handle_system_event(event)
-        retry
-      end
-    end
+      loop do
+        message = @receivers.receive(timeout, &block)
+        break message unless message.is_a?(SystemEvent)
 
-    # Run the actor loop
-    def run
-      begin
-        while @running
-          if message = @mailbox.receive(timeout)
-            handle_message message
-          else
-            # No message indicates a timeout
-            @timers.fire
-            @receivers.fire_timers
-          end
-        end
-      rescue SystemEvent => event
-        handle_system_event event
-        retry
-      rescue MailboxShutdown
-        # If the mailbox detects shutdown, exit the actor
+        handle_system_event(message)
       end
-
-      shutdown
-    rescue Exception => ex
-      handle_crash(ex)
-      raise unless ex.is_a? StandardError
     end
 
     # How long to wait until the next timer fires
-    def timeout
+    def timeout_interval
       i1 = @timers.wait_interval
       i2 = @receivers.wait_interval
 
@@ -206,17 +291,13 @@ module Celluloid
     end
 
     # Schedule a block to run at the given time
-    def after(interval)
-      @timers.after(interval) do
-        Task.new(:timer) { yield }.resume
-      end
+    def after(interval, &block)
+      @timers.after(interval) { task(:timer, &block) }
     end
 
     # Schedule a block to run at the given time
-    def every(interval)
-      @timers.every(interval) do
-        Task.new(:timer) { yield }.resume
-      end
+    def every(interval, &block)
+      @timers.every(interval) { task(:timer, &block) }
     end
 
     # Sleep for the given amount of time
@@ -233,12 +314,10 @@ module Celluloid
     # Handle standard low-priority messages
     def handle_message(message)
       case message
+      when SystemEvent
+        handle_system_event message
       when Call
-        if @exclusives && @exclusives.include?(message.method)
-          exclusive { message.dispatch(@subject) }
-        else
-          Task.new(:message_handler) { message.dispatch(@subject) }.resume
-        end
+        task(:message_handler, message.method) { message.dispatch(@subject) }
       when Response
         message.dispatch
       else
@@ -251,7 +330,9 @@ module Celluloid
     def handle_system_event(event)
       case event
       when ExitEvent
-        Task.new(:exit_handler) { handle_exit_event event }.resume
+        task(:exit_handler, @exit_handler) { handle_exit_event event }
+      when LinkingRequest
+        event.process(links)
       when NamingRequest
         @name = event.name
       when TerminationRequest
@@ -289,7 +370,7 @@ module Celluloid
     # Run the user-defined finalizer, if one is set
     def run_finalizer
       return unless @subject.respond_to? :finalize
-      Task.new(:finalizer) { @subject.finalize }.resume
+      task(:finalizer, :finalize) { @subject.finalize }
     rescue => ex
       Logger.crash("#{@subject.class}#finalize crashed!", ex)
     end
@@ -302,5 +383,14 @@ module Celluloid
     rescue => ex
       Logger.crash("#{@subject.class}: CLEANUP CRASHED!", ex)
     end
+
+    # Run a method inside a task unless it's exclusive
+    def task(task_type, method_name = nil, &block)
+      if @exclusives && (@exclusives == :all || @exclusives.include?(method_name))
+        exclusive { block.call }
+      else
+        @task_class.new(:message_handler, &block).resume
+      end
+    end
   end
 end

data/lib/celluloid/boot.rb

@@ -0,0 +1,9 @@
+# Things to run after Celluloid is fully loaded
+
+# Configure default systemwide settings
+Celluloid.logger     = Logger.new STDERR
+Celluloid.task_class = Celluloid::TaskFiber
+
+# Launch the notifications fanout actor
+# FIXME: We should set up the supervision hierarchy here
+Celluloid::Notifications::Fanout.supervise_as :notifications_fanout

data/lib/celluloid/calls.rb

@@ -9,7 +9,7 @@ module Celluloid
 
     def check_signature(obj)
       unless obj.respond_to? @method
-        raise NoMethodError, "undefined method `#{@method}' for #{obj.inspect}"
+        raise NoMethodError, "undefined method `#{@method}' for #{obj.to_s}"
       end
 
       begin
@@ -39,7 +39,7 @@ module Celluloid
   class SyncCall < Call
     attr_reader :caller, :task
 
-    def initialize(caller, method, arguments = [], block = nil, task = Fiber.current.task)
+    def initialize(caller, method, arguments = [], block = nil, task = Thread.current[:task])
       super(method, arguments, block)
       @caller = caller
       @task = task
@@ -99,7 +99,7 @@ module Celluloid
       obj.send(@method, *@arguments, &@block)
     rescue AbortError => ex
       # Swallow aborted async calls, as they indicate the caller made a mistake
-      Logger.crash("#{obj.class}: async call `#{@method}' aborted!", ex)
+      Logger.crash("#{obj.class}: async call `#{@method}' aborted!", ex.cause)
     end
   end
 end

data/lib/celluloid/core_ext.rb

@@ -17,9 +17,4 @@ class Thread
       mailbox.receive(timeout, &block)
     end
   end
-end
-
-class Fiber
-  # Celluloid::Task associated with this Fiber
-  attr_accessor :task
-end
+end

data/lib/celluloid/cpu_counter.rb

@@ -7,6 +7,8 @@ module Celluloid
       @cores = Integer(`sysctl hw.ncpu`[/\d+/])
     when 'linux'
       @cores = File.read("/proc/cpuinfo").scan(/core id\s+: \d+/).uniq.size
+    when 'mingw', 'mswin'
+      @cores = Integer(`SET NUMBER_OF_PROCESSORS`[/\d+/])
     else
       @cores = nil
     end

data/lib/celluloid/future.rb

@@ -35,6 +35,11 @@ module Celluloid
       receiver << @call
     end
 
+    # Check if this future has a value yet
+    def ready?
+      @ready
+    end
+
     # Obtain the value for this Future
     def value(timeout = nil)
       ready = result = nil

data/lib/celluloid/links.rb

@@ -1,5 +1,3 @@
-require 'thread'
-
 module Celluloid
   # Linked actors send each other system events
   class Links
@@ -31,7 +29,7 @@ module Celluloid
 
     # Send an event message to all actors
     def send_event(event)
-      each { |actor| actor.mailbox.system_event event }
+      each { |actor| actor.mailbox << event }
     end
 
     # Generate a string representation

data/lib/celluloid/mailbox.rb

@@ -13,9 +13,9 @@ module Celluloid
     alias_method :address, :object_id
 
     def initialize
-      @messages = []
-      @mutex = Mutex.new
-      @dead = false
+      @messages  = []
+      @mutex     = Mutex.new
+      @dead      = false
       @condition = ConditionVariable.new
     end
 
@@ -23,9 +23,18 @@ module Celluloid
     def <<(message)
       @mutex.lock
       begin
-        raise MailboxError, "dead recipient" if @dead
+        if message.is_a?(SystemEvent)
+          # Silently swallow system events sent to dead actors
+          return if @dead
+
+          # SystemEvents are high priority messages so they get added to the
+          # head of our message queue instead of the end
+          @messages.unshift message
+        else
+          raise MailboxError, "dead recipient" if @dead
+          @messages << message
+        end
 
-        @messages << message
         @condition.signal
         nil
       ensure
@@ -33,20 +42,6 @@ module Celluloid
       end
     end
 
-    # Add a high-priority system event to the Mailbox
-    def system_event(event)
-      @mutex.lock
-      begin
-        unless @dead # Silently fail if messages are sent to dead actors
-          @messages.unshift event
-          @condition.signal
-        end
-        nil
-      ensure
-        @mutex.unlock rescue nil
-      end
-    end
-
     # Receive a message from the Mailbox
     def receive(timeout = nil, &block)
       message = nil
@@ -92,7 +87,6 @@ module Celluloid
         message = @messages.shift
       end
 
-      raise message if message.is_a? SystemEvent
       message
     end
 

data/lib/celluloid/method.rb

@@ -0,0 +1,19 @@
+module Celluloid
+  # Method handles that route through an actor proxy
+  class Method
+    def initialize(actor, name)
+      raise NameError, "undefined method `#{name}'" unless actor.respond_to? name
+
+      @actor, @name = actor, name
+      @klass = @actor.class
+    end
+
+    def call(*args, &block)
+      @actor._send_(@name, *args, &block)
+    end
+
+    def inspect
+      "#<Celluloid::Method #{@klass}#{@name}>"
+    end
+  end
+end

data/lib/celluloid/notifications.rb

@@ -1,5 +1,21 @@
 module Celluloid
   module Notifications
+    def self.notifier
+      Actor[:notifications_fanout] or raise DeadActorError, "notifications fanout actor not running"
+    end
+
+    def publish(pattern, *args)
+      Celluloid::Notifications.notifier.publish(pattern, *args)
+    end
+
+    def subscribe(pattern, method)
+      Celluloid::Notifications.notifier.subscribe(Actor.current, pattern, method)
+    end
+
+    def unsubscribe(*args)
+      Celluloid::Notifications.notifier.unsubscribe(*args)
+    end
+
     class Fanout
       include Celluloid
       trap_exit :prune
@@ -63,22 +79,5 @@ module Celluloid
           @pattern && @pattern === subscriber_or_pattern
       end
     end
-
-    class << self
-      attr_accessor :notifier
-    end
-    self.notifier = Fanout.new
-    
-    def publish(pattern, *args)
-      Celluloid::Notifications.notifier.publish(pattern, *args)
-    end
-
-    def subscribe(pattern, method)
-      Celluloid::Notifications.notifier.subscribe(Actor.current, pattern, method)
-    end
-
-    def unsubscribe(*args)
-      Celluloid::Notifications.notifier.unsubscribe(*args)
-    end
   end
 end

data/lib/celluloid/pool_manager.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 module Celluloid
   # Manages a fixed-size pool of workers
   # Delegates work (i.e. methods) and supervises workers
@@ -7,14 +9,28 @@ module Celluloid
     trap_exit :crash_handler
 
     def initialize(worker_class, options = {})
-      @size = options[:size]
-      raise ArgumentError, "minimum pool size is 2" if @size && @size < 2
+      @size = options[:size] || [Celluloid.cores, 2].max
+      raise ArgumentError, "minimum pool size is 2" if @size < 2
 
-      @size ||= [Celluloid.cores, 2].max
+      @worker_class = worker_class
       @args = options[:args] ? Array(options[:args]) : []
 
-      @worker_class = worker_class
       @idle = @size.times.map { worker_class.new_link(*@args) }
+
+      # FIXME: Another data structure (e.g. Set) would be more appropriate
+      # here except it causes MRI to crash :o
+      @busy = []
+    end
+
+    def finalize
+      terminators = (@idle + @busy).each do |actor|
+        begin
+          actor.future(:terminate)
+        rescue DeadActorError, MailboxError
+        end
+      end
+
+      terminators.compact.each { |terminator| terminator.value rescue nil }
     end
 
     def _send_(method, *args, &block)
@@ -22,10 +38,17 @@ module Celluloid
 
       begin
         worker._send_ method, *args, &block
+      rescue DeadActorError # if we get a dead actor out of the pool
+        wait :respawn_complete
+        worker = __provision_worker
+        retry
       rescue Exception => ex
         abort ex
       ensure
-        @idle << worker if worker.alive?
+        if worker.alive?
+          @idle << worker
+          @busy.delete worker
+        end
       end
     end
 
@@ -56,23 +79,29 @@ module Celluloid
     # Provision a new worker
     def __provision_worker
       while @idle.empty?
-        # Using exclusive mode blocks incoming messages, so they don't pile
-        # up as waiting Celluloid::Tasks
-        response = exclusive { receive { |msg| msg.is_a? Response } }
+        # Wait for responses from one of the busy workers
+        response = exclusive { receive { |msg| msg.is_a?(Response) } }
         Thread.current[:actor].handle_message(response)
       end
-      @idle.shift
+
+      worker = @idle.shift
+      @busy << worker
+
+      worker
     end
 
     # Spawn a new worker for every crashed one
     def crash_handler(actor, reason)
+      @busy.delete actor
       @idle.delete actor
-      return unless reason # don't restart workers that exit cleanly
+      return unless reason
+
       @idle << @worker_class.new_link(*@args)
+      signal :respawn_complete
     end
 
     def respond_to?(method)
-      super || (@worker_class ? @worker_class.instance_methods.include?(method.to_sym) : false)
+      super || @worker_class.instance_methods.include?(method.to_sym)
     end
 
     def method_missing(method, *args, &block)

data/lib/celluloid/proxies/abstract_proxy.rb

@@ -0,0 +1,17 @@
+module Celluloid
+  # Base class of all Celluloid proxies
+  class AbstractProxy < BasicObject
+    # Needed for storing proxies in data structures
+    needed = [:object_id, :__id__, :hash] - instance_methods
+    if needed.any?
+      include ::Kernel.dup.module_eval {
+        undef_method *(instance_methods - needed)
+        self
+      }
+
+      # rubinius bug?  These methods disappear when we include hacked kernel
+      define_method :==, ::BasicObject.instance_method(:==) unless instance_methods.include?(:==)
+      alias_method(:equal?, :==) unless instance_methods.include?(:equal?)
+    end
+  end
+end