celluloid 0.11.1 → 0.12.0.pre

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.rb

@@ -4,14 +4,17 @@ require 'timeout'
 require 'set'
 
 module Celluloid
+  extend self # expose all instance methods as singleton methods
+
   SHUTDOWN_TIMEOUT = 120 # How long actors have to terminate
-  @logger = Logger.new STDERR
 
   class << self
-    attr_accessor :logger # Thread-safe logger class
+    attr_accessor :logger     # Thread-safe logger class
+    attr_accessor :task_class # Default task type to use
 
     def included(klass)
-      klass.send :extend, ClassMethods
+      klass.send :extend,  ClassMethods
+      klass.send :include, InstanceMethods
     end
 
     # Are we currently inside of an actor?
@@ -19,36 +22,6 @@ module Celluloid
       !!Thread.current[:actor]
     end
 
-    # Is current actor running in exclusive mode?
-    def exclusive?
-      actor? and Thread.current[:actor].exclusive?
-    end
-
-    # Obtain the currently running actor (if one exists)
-    def current_actor
-      Actor.current
-    end
-
-    # Receive an asynchronous message
-    def receive(timeout = nil, &block)
-      actor = Thread.current[:actor]
-      if actor
-        actor.receive(timeout, &block)
-      else
-        Thread.mailbox.receive(timeout, &block)
-      end
-    end
-
-    # Sleep letting the actor continue processing messages
-    def sleep(interval)
-      actor = Thread.current[:actor]
-      if actor
-        actor.sleep(interval)
-      else
-        Kernel.sleep interval
-      end
-    end
-
     # Generate a Universally Unique Identifier
     def uuid
       UUID.generate
@@ -67,8 +40,6 @@ module Celluloid
     end
 
     # Shut down all running actors
-    # FIXME: This should probably attempt a graceful shutdown of the supervision
-    # tree before iterating through all actors and telling them to terminate.
     def shutdown
       Timeout.timeout(SHUTDOWN_TIMEOUT) do
         actors = Actor.all
@@ -78,16 +49,16 @@ module Celluloid
         Supervisor.root.terminate if Supervisor.root
 
         # Actors cannot self-terminate, you must do it for them
-        terminators = Actor.all.each do |actor|
+        Actor.all.each do |actor|
           begin
-            actor.future(:terminate)
+            actor.terminate!
           rescue DeadActorError, MailboxError
           end
         end
 
-        terminators.each do |terminator|
+        Actor.all.each do |actor|
           begin
-            terminator.value
+            Actor.join(actor)
           rescue DeadActorError, MailboxError
           end
         end
@@ -104,7 +75,7 @@ module Celluloid
   module ClassMethods
     # Create a new actor
     def new(*args, &block)
-      proxy = Actor.new(allocate).proxy
+      proxy = Actor.new(allocate, actor_options).proxy
       proxy._send_(:initialize, *args, &block)
       proxy
     end
@@ -112,11 +83,10 @@ module Celluloid
 
     # Create a new actor and link to the current one
     def new_link(*args, &block)
-      current_actor = Actor.current
-      raise NotActorError, "can't link outside actor context" unless current_actor
+      raise NotActorError, "can't link outside actor context" unless Celluloid.actor?
 
-      proxy = Actor.new(allocate).proxy
-      current_actor.link proxy
+      proxy = Actor.new(allocate, actor_options).proxy
+      Actor.link(proxy)
       proxy._send_(:initialize, *args, &block)
       proxy
     end
@@ -158,9 +128,6 @@ module Celluloid
       @exit_handler = callback.to_sym
     end
 
-    # Obtain the exit handler for this actor
-    attr_reader :exit_handler
-
     # Configure a custom mailbox factory
     def use_mailbox(klass = nil, &block)
       if block
@@ -170,31 +137,94 @@ module Celluloid
       end
     end
 
+    # Define the default task type for this class
+    def task_class(klass)
+      @task_class = klass
+    end
+
     # Mark methods as running exclusively
     def exclusive(*methods)
-      @exclusive_methods ||= Set.new
-      @exclusive_methods.merge methods.map(&:to_sym)
+      if methods.empty?
+        @exclusive_methods = :all
+      elsif @exclusive_methods != :all
+        @exclusive_methods ||= Set.new
+        @exclusive_methods.merge methods.map(&:to_sym)
+      end
     end
-    attr_reader :exclusive_methods
 
     # Create a mailbox for this actor
     def mailbox_factory
       if defined?(@mailbox_factory)
         @mailbox_factory.call
-      elsif defined?(super)
-        super
+      elsif superclass.respond_to? :mailbox_factory
+        superclass.mailbox_factory
       else
         Mailbox.new
       end
     end
 
+    # Configuration options for Actor#new
+    def actor_options
+      {
+        :mailbox => mailbox_factory,
+        :exit_handler => @exit_handler,
+        :exclusive_methods => @exclusive_methods,
+        :task_class => @task_class,
+      }
+    end
+
     def ===(other)
       other.kind_of? self
     end
   end
 
+  # These are methods we don't want added to the Celluloid singleton but to be
+  # defined on all classes that use Celluloid
+  module InstanceMethods
+    # Obtain the Ruby object the actor is wrapping. This should ONLY be used
+    # for a limited set of use cases like runtime metaprogramming. Interacting
+    # directly with the wrapped object foregoes any kind of thread safety that
+    # Celluloid would ordinarily provide you, and the object is guaranteed to
+    # be shared with at least the actor thread. Tread carefully.
+    def wrapped_object; self; end
+
+    def inspect
+      str = "#<Celluloid::Actor(#{self.class}:0x#{object_id.to_s(16)})"
+      ivars = instance_variables.map do |ivar|
+        "#{ivar}=#{instance_variable_get(ivar).inspect}"
+      end
+
+      str << " " << ivars.join(' ') unless ivars.empty?
+      str << ">"
+    end
+
+    # Process async calls via method_missing
+    def method_missing(meth, *args, &block)
+      # bang methods are async calls
+      if meth.to_s.match(/!$/)
+        unbanged_meth = meth.to_s.sub(/!$/, '')
+        args.unshift unbanged_meth
+
+        call = AsyncCall.new(:__send__, args, block)
+        begin
+          Thread.current[:actor].mailbox << call
+        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
+      end
+
+      super
+    end
+  end
+
   #
-  # Instance methods
+  # The following methods are available on both the Celluloid singleton and
+  # directly inside of all classes that include Celluloid
   #
 
   # Is this actor alive?
@@ -217,16 +247,6 @@ module Celluloid
     Thread.current[:actor].terminate
   end
 
-  def inspect
-    str = "#<Celluloid::Actor(#{self.class}:0x#{object_id.to_s(16)})"
-    ivars = instance_variables.map do |ivar|
-      "#{ivar}=#{instance_variable_get(ivar).inspect}"
-    end
-
-    str << " " << ivars.join(' ') unless ivars.empty?
-    str << ">"
-  end
-
   # Send a signal with the given name to all waiting methods
   def signal(name, value = nil)
     Thread.current[:actor].signal name, value
@@ -252,51 +272,59 @@ module Celluloid
     Thread.current[:actor].tasks.to_a
   end
 
-  # Obtain the Ruby object the actor is wrapping. This should ONLY be used
-  # for a limited set of use cases like runtime metaprogramming. Interacting
-  # directly with the wrapped object foregoes any kind of thread safety that
-  # Celluloid would ordinarily provide you, and the object is guaranteed to
-  # be shared with at least the actor thread. Tread carefully.
-  def wrapped_object; self; end
-
   # Obtain the Celluloid::Links for this actor
   def links
     Thread.current[:actor].links
   end
 
+  # Watch for exit events from another actor
+  def monitor(actor)
+    Actor.monitor(actor)
+  end
+
+  # Stop waiting for exit events from another actor
+  def unmonitor(actor)
+    Actor.unmonitor(actor)
+  end
+
   # Link this actor to another, allowing it to crash or react to errors
   def link(actor)
-    actor.notify_link Actor.current
-    notify_link actor
+    Actor.link(actor)
   end
 
   # Remove links to another actor
   def unlink(actor)
-    actor.notify_unlink Actor.current
-    notify_unlink actor
-  end
-
-  def notify_link(actor)
-    links << actor
+    Actor.unlink(actor)
   end
 
-  def notify_unlink(actor)
-    links.delete actor
+  # Are we monitoring another actor?
+  def monitoring?(actor)
+    Actor.monitoring?(actor)
   end
 
   # Is this actor linked to another?
   def linked_to?(actor)
-    Thread.current[:actor].links.include? actor
+    Actor.linked_to?(actor)
   end
 
   # Receive an asynchronous message via the actor protocol
   def receive(timeout = nil, &block)
-    Celluloid.receive(timeout, &block)
+    actor = Thread.current[:actor]
+    if actor
+      actor.receive(timeout, &block)
+    else
+      Thread.mailbox.receive(timeout, &block)
+    end
   end
 
-  # Sleep while letting the actor continue to receive messages
+  # Sleep letting the actor continue processing messages
   def sleep(interval)
-    Celluloid.sleep(interval)
+    actor = Thread.current[:actor]
+    if actor
+      actor.sleep(interval)
+    else
+      Kernel.sleep interval
+    end
   end
 
   # Run given block in an exclusive mode: all synchronous calls block the whole
@@ -307,7 +335,8 @@ module Celluloid
 
   # Are we currently exclusive
   def exclusive?
-    Celluloid.exclusive?
+    actor = Thread.current[:actor]
+    actor && actor.exclusive?
   end
 
   # Call a block after a given interval, returning a Celluloid::Timer object
@@ -338,29 +367,6 @@ module Celluloid
   def future(meth, *args, &block)
     Actor.future Thread.current[:actor].mailbox, meth, *args, &block
   end
-
-  # Process async calls via method_missing
-  def method_missing(meth, *args, &block)
-    # bang methods are async calls
-    if meth.to_s.match(/!$/)
-      unbanged_meth = meth.to_s.sub(/!$/, '')
-      args.unshift unbanged_meth
-
-      call = AsyncCall.new(:__send__, args, block)
-      begin
-        Thread.current[:actor].mailbox << call
-      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
-    end
-
-    super
-  end
 end
 
 require 'celluloid/version'
@@ -368,17 +374,18 @@ require 'celluloid/actor_proxy'
 require 'celluloid/calls'
 require 'celluloid/core_ext'
 require 'celluloid/cpu_counter'
-require 'celluloid/events'
 require 'celluloid/fiber'
 require 'celluloid/fsm'
 require 'celluloid/internal_pool'
 require 'celluloid/links'
 require 'celluloid/logger'
 require 'celluloid/mailbox'
+require 'celluloid/method'
 require 'celluloid/receivers'
 require 'celluloid/registry'
 require 'celluloid/responses'
 require 'celluloid/signals'
+require 'celluloid/system_events'
 require 'celluloid/task'
 require 'celluloid/thread_handle'
 require 'celluloid/uuid'
@@ -389,3 +396,5 @@ require 'celluloid/pool_manager'
 require 'celluloid/supervision_group'
 require 'celluloid/supervisor'
 require 'celluloid/notifications'
+
+require 'celluloid/boot'

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)
+            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,37 +268,12 @@ 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
@@ -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