celluloid 0.1.0 → 0.2.0

data/README.md

@@ -1,5 +1,6 @@
 Celluloid
 =========
+[![Build Status](http://travis-ci.org/tarcieri/celluloid.png)](http://travis-ci.org/tarcieri/celluloid)
 
 > "I thought of objects being like biological cells and/or individual 
 > computers on a network, only able to communicate with messages"  
@@ -27,10 +28,10 @@ Celluloid works on Rubinius in either 1.8 or 1.9 mode.
 Usage
 -----
 
-To use Celluloid, define a normal Ruby class that includes Celluloid::Actor
+To use Celluloid, define a normal Ruby class that includes Celluloid:
 
     class Sheen
-      include Celluloid::Actor
+      include Celluloid
   
       def initialize(name)
         @name = name
@@ -45,10 +46,10 @@ To use Celluloid, define a normal Ruby class that includes Celluloid::Actor
       end
     end
     
-If you call Sheen.new, you'll wind up with a plain old Ruby object. To
-create a concurrent object instead of a regular one, use Sheen.spawn:
+Now when you create new instances of this class, they're actually concurrent
+objects, each running in their own thread:
 
-    >> charlie = Sheen.spawn "Charlie Sheen"
+    >> charlie = Sheen.new "Charlie Sheen"
      => #<Celluloid::Actor(Sheen:0x00000100a312d0) @name="Charlie Sheen">
     >> charlie.set_status "winning!"
      => "winning!" 
@@ -59,10 +60,9 @@ create a concurrent object instead of a regular one, use Sheen.spawn:
     >> charlie.report
      => "Charlie Sheen is asynchronously winning!" 
 
-Calling spawn creates a concurrent object running inside its own thread. You
-can call methods on this concurrent object just like you would any other Ruby
-object. The Sheen#set_status method works exactly like you'd expect, returning
-the last expression evaluated.
+You can call methods on this concurrent object just like you would any other 
+Ruby object. The Sheen#set_status method works exactly like you'd expect,
+returning the last expression evaluated.
 
 However, Celluloid's secret sauce kicks in when you call banged predicate
 methods (i.e. methods ending in !). Even though the Sheen class has no 
@@ -89,6 +89,38 @@ crashed object will not raise an error.
 However, you can still handle errors created by asynchronous calls using
 two features of Celluloid called _supervisors_ and _linking_.
 
+Futures
+-------
+
+Futures allow you to request a computation and get the result later. There are
+two types of futures supported by Celluloid: method futures and block futures.
+Method futures work by invoking the _future_ method on an actor. This method
+is analogous to the typical _send_ method in that it takes a method name, 
+followed by an arbitrary number of arguments, and a block. Let's invoke the
+report method from the charlie object used in the above example using a future:
+
+	>> future = charlie.future :report
+	 => #<Celluloid::Future:0x000001009759b8>
+	>> future.value
+	 => "Charlie Sheen is winning!"
+
+The call to charlie.future immediately returns a Celluloid::Future object,
+regardless of how long it takes to execute the "report" method. To obtain
+the result of the call to "report", we call the _value_ method of the
+future object. This call will block until the method call is available.
+
+Futures also allow you to background the computation of any block:
+
+	>> future = Celluloid::Future.new { 2 + 2 }
+	 => #<Celluloid::Future:0x000001008425f0> 
+	>> future.value
+	 => 4 
+
+One thing to be aware of when using futures: always make sure to obtain the
+value of any future you make. Futures create a thread in the background which
+will continue to run until the future's value is obtained. Failing to obtain
+the value of futures you create will leak threads.
+
 Supervisors
 -----------
 
@@ -106,7 +138,7 @@ class from the example above:
  
 This created a new Celluloid::Supervisor actor, and also created a new Sheen
 actor, giving its initialize method the argument "Charlie Sheen". The 
-_supervise_ method has the same method signature as _spawn_. However, rather
+_supervise_ method has the same method signature as _new_. However, rather
 than returning the newly created actor, _supervise_ returns the supervisor.
 To retrieve the actor that the supervisor is currently using, use the
 Celluloid::Supervisor#actor method:
@@ -128,7 +160,7 @@ In this case, the supervisor will ensure that an actor of the Sheen class,
 created using the given arguments, is aways available by calling
 Celluloid::Actor[:charlie]. The first argument to supervise_as is the name
 you'd like the newly created actor to be registered under. The remaining
-arguments are passed to initialize just like you called _new_ or _spawn_.
+arguments are passed to initialize just like you called _new_.
 
 See the "Registry" section below for more information on the actor registry
 
@@ -139,7 +171,7 @@ Whenever any unhandled exceptions occur in any of the methods of an actor,
 that actor crashes and dies. Let's start with an example:
 
     class JamesDean
-      include Celluloid::Actor
+      include Celluloid
       class CarInMyLaneError < StandardError; end
       
       def drive_little_bastard
@@ -149,7 +181,7 @@ that actor crashes and dies. Let's start with an example:
     
 Now, let's have James drive Little Bastard and see what happens:
 
-    >> james = JamesDean.spawn
+    >> james = JamesDean.new
      => #<Celluloid::Actor(JamesDean:0x1068)> 
     >> james.drive_little_bastard!
      => nil 
@@ -166,7 +198,7 @@ trap_exit method to be notified of them. Let's look at how a hypothetical
 Elizabeth Taylor object could be notified that James Dean has crashed:
 
     class ElizabethTaylor
-      include Celluloid::Actor
+      include Celluloid
       trap_exit :actor_died
   
       def actor_died(actor, reason)
@@ -178,9 +210,9 @@ We've now used the trap_exit method to configure a callback which is invoked
 whenever any linked actors crashed. Now we need to link Elizabeth to James so
 James' crash notifications get sent to her:
 
-    >> james = JamesDean.spawn
+    >> james = JamesDean.new
      => #<Celluloid::Actor(JamesDean:0x11b8)> 
-    >> elizabeth = ElizabethTaylor.spawn
+    >> elizabeth = ElizabethTaylor.new
      => #<Celluloid::Actor(ElizabethTaylor:0x11f0)> 
     >> elizabeth.link james
      => #<Celluloid::Actor(JamesDean:0x11b8)> 
@@ -197,7 +229,7 @@ if she weren't trapping exits? Let's break James apart into two separate
 objects, one for James himself and one for Little Bastard, his car:
 
     class PorscheSpider
-      include Celluloid::Actor
+      include Celluloid
       class CarInMyLaneError < StandardError; end
   
       def drive_on_route_466
@@ -206,10 +238,10 @@ objects, one for James himself and one for Little Bastard, his car:
     end
     
     class JamesDean
-      include Celluloid::Actor
+      include Celluloid
       
       def initialize
-        @little_bastard = PorscheSpider.spawn_link
+        @little_bastard = PorscheSpider.new_link
       end
       
       def drive_little_bastard
@@ -218,17 +250,17 @@ objects, one for James himself and one for Little Bastard, his car:
     end
     
 If you take a look in JamesDean#initialize, you'll notice that to create an
-instance of PorcheSpider, James is calling the spawn_link method.
+instance of PorcheSpider, James is calling the new_link method.
 
-This method works similarly to _spawn_, except it combines _spawn_ and _link_ 
+This method works similarly to _new_, except it combines _new_ and _link_ 
 into a single call.
 
 Now what happens if we repeat the same scenario with Elizabeth Taylor watching
 for James Dean's crash?
 
-    >> james = JamesDean.spawn
+    >> james = JamesDean.new
      => #<Celluloid::Actor(JamesDean:0x1108) @little_bastard=#<Celluloid::Actor(PorscheSpider:0x10ec)>> 
-    >> elizabeth = ElizabethTaylor.spawn
+    >> elizabeth = ElizabethTaylor.new
      => #<Celluloid::Actor(ElizabethTaylor:0x1144)> 
     >> elizabeth.link james
      => #<Celluloid::Actor(JamesDean:0x1108) @little_bastard=#<Celluloid::Actor(PorscheSpider:0x10ec)>> 
@@ -250,7 +282,7 @@ This allows you to factor your problem into several actors. If an error occurs
 in any of them, it will kill off all actors used in a particular system. In
 general, you'll probably want to have a supervisor start a single actor which
 is in charge of a particular part of your system, and have that actor 
-spawn_link to other actors which are part of the same system. If any error
+new_link to other actors which are part of the same system. If any error
 occurs in any of these actors, all of them will be killed off and the entire
 subsystem will be restarted by the supervisor in a clean state.
 
@@ -263,7 +295,7 @@ Registry
 Celluloid lets you register actors so you can refer to them symbolically.
 You can register Actors using Celluloid::Actor[]:
 
-    >> james = JamesDean.spawn
+    >> james = JamesDean.new
      => #<Celluloid::Actor(JamesDean:0x80c27ce0)> 
     >> Celluloid::Actor[:james] = james
      => #<Celluloid::Actor(JamesDean:0x80c27ce0)> 
@@ -280,6 +312,41 @@ working, freshly-restarted version.
 The main use of the registry is for interfacing with actors that are
 automatically restarted by supervisors when they crash.
 
+Signaling
+---------
+
+Signaling is an advanced technique similar to condition variables in typical
+multithreaded programming. One method within a concurrent object can suspend
+itself waiting for a particular event, allowing other methods to run. Another
+method can then signal all methods waiting for a particular event, and even
+send them a value in the process:
+
+	class SignalingExample
+	  include Celluloid
+	  attr_reader :signaled
+  
+	  def initialize
+	    @signaled = false
+	  end
+  
+	  def wait_for_signal
+	    value = wait :ponycopter
+	    @signaled = true
+	    value
+	  end
+  
+	  def send_signal(value)
+	    signal :ponycopter, value
+	  end
+	end
+	
+The wait_for_signal method in turn calls a method called "wait". Wait suspends
+the running method until another method of the same object calls the "signal"
+method with the same label.
+
+The send_signal method of this class does just that, signaling "ponycopter"
+with the given value. This value is returned from the original wait call.
+
 Logging
 -------
 
@@ -300,4 +367,4 @@ Contributing to Celluloid
 Copyright
 ---------
 
-Copyright (c) 2011 Tony Arcieri. See LICENSE.txt for further details.
+Copyright (c) 2011 Tony Arcieri. See LICENSE.txt for further details.

data/lib/celluloid.rb

@@ -1,5 +1,22 @@
 require 'logger'
 
+module Celluloid    
+  @@logger_lock = Mutex.new
+  @@logger = Logger.new STDERR
+
+  def self.logger
+    @@logger_lock.synchronize { @@logger }
+  end
+  
+  def self.logger=(logger)
+    @@logger_lock.synchronize { @@logger = logger }
+  end
+  
+  def self.included(klass)
+    klass.send :include, Actor
+  end
+end
+
 require 'celluloid/version'
 require 'celluloid/actor'
 require 'celluloid/actor_proxy'
@@ -10,19 +27,7 @@ require 'celluloid/linking'
 require 'celluloid/mailbox'
 require 'celluloid/registry'
 require 'celluloid/responses'
+require 'celluloid/signals'
 require 'celluloid/supervisor'
 
 require 'celluloid/future'
-
-module Celluloid    
-  @@logger_lock = Mutex.new
-  @@logger = Logger.new STDERR
-
-  def self.logger
-    @@logger_lock.synchronize { @@logger }
-  end
-  
-  def self.logger=(logger)
-    @@logger_lock.synchronize { @@logger = logger }
-  end
-end

data/lib/celluloid.rbc

@@ -1,5 +1,5 @@
 !RBIX
-3578385345186687227
+3246536075095810518
 18
 M
 1
@@ -9,7 +9,7 @@ x
 10
 __script__
 i
-145
+154
 5
 7
 0
@@ -19,9 +19,35 @@ i
 1
 1
 15
-5
+99
 7
 2
+65
+49
+3
+2
+13
+99
+12
+7
+4
+12
+7
+5
+12
+65
+12
+49
+6
+4
+15
+49
+4
+0
+15
+5
+7
+7
 64
 47
 49
@@ -30,7 +56,7 @@ i
 15
 5
 7
-3
+8
 64
 47
 49
@@ -39,7 +65,7 @@ i
 15
 5
 7
-4
+9
 64
 47
 49
@@ -48,7 +74,7 @@ i
 15
 5
 7
-5
+10
 64
 47
 49
@@ -57,7 +83,7 @@ i
 15
 5
 7
-6
+11
 64
 47
 49
@@ -66,7 +92,7 @@ i
 15
 5
 7
-7
+12
 64
 47
 49
@@ -75,7 +101,7 @@ i
 15
 5
 7
-8
+13
 64
 47
 49
@@ -84,7 +110,7 @@ i
 15
 5
 7
-9
+14
 64
 47
 49
@@ -93,7 +119,7 @@ i
 15
 5
 7
-10
+15
 64
 47
 49
@@ -102,7 +128,7 @@ i
 15
 5
 7
-11
+16
 64
 47
 49
@@ -111,7 +137,7 @@ i
 15
 5
 7
-12
+17
 64
 47
 49
@@ -120,38 +146,21 @@ i
 15
 5
 7
-13
+18
 64
 47
 49
 1
 1
 15
-99
-7
-14
-65
-49
-15
-2
-13
-99
-12
-7
-16
-12
+5
 7
-17
-12
-65
-12
-49
-18
-4
-15
+19
+64
+47
 49
-16
-0
+1
+1
 15
 2
 11
@@ -167,49 +176,13 @@ I
 0
 n
 p
-19
+20
 s
 6
 logger
 x
 7
 require
-s
-17
-celluloid/version
-s
-15
-celluloid/actor
-s
-21
-celluloid/actor_proxy
-s
-15
-celluloid/calls
-s
-18
-celluloid/core_ext
-s
-16
-celluloid/events
-s
-17
-celluloid/linking
-s
-17
-celluloid/mailbox
-s
-18
-celluloid/registry
-s
-19
-celluloid/responses
-s
-20
-celluloid/supervisor
-s
-16
-celluloid/future
 x
 9
 Celluloid
@@ -227,7 +200,7 @@ x
 9
 Celluloid
 i
-92
+103
 5
 66
 5
@@ -319,6 +292,17 @@ i
 49
 15
 4
+15
+99
+7
+18
+7
+19
+65
+5
+49
+15
+4
 11
 I
 5
@@ -332,7 +316,7 @@ I
 0
 n
 p
-18
+20
 x
 13
 @@logger_lock
@@ -453,7 +437,7 @@ p
 I
 0
 I
-16
+8
 I
 7
 x
@@ -469,11 +453,11 @@ p
 I
 -1
 I
-15
+7
 I
 0
 I
-16
+8
 I
 c
 x
@@ -576,7 +560,7 @@ p
 I
 0
 I
-1a
+c
 I
 a
 x
@@ -592,11 +576,11 @@ p
 I
 -1
 I
-19
+b
 I
 0
 I
-1a
+c
 I
 c
 x
@@ -607,26 +591,96 @@ p
 x
 6
 logger
+x
+8
+included
+M
+1
+n
+n
+x
+8
+included
+i
+11
+20
+0
+7
+0
+45
+1
+2
+49
+3
+2
+11
+I
+4
+I
+1
+I
+1
+I
+0
+I
+1
+n
 p
-9
+4
+x
+7
+include
+x
+5
+Actor
+n
+x
+4
+send
+p
+5
+I
+-1
+I
+f
+I
+0
+I
+10
+I
+b
+x
+42
+/Users/tony/src/celluloid/lib/celluloid.rb
+p
+1
+x
+5
+klass
+p
+11
 I
 2
 I
-12
+4
 I
 21
 I
-13
+5
 I
 46
 I
-15
+7
 I
 51
 I
-19
+b
 I
 5c
+I
+f
+I
+67
 x
 42
 /Users/tony/src/celluloid/lib/celluloid.rb
@@ -635,8 +689,47 @@ p
 x
 13
 attach_method
+s
+17
+celluloid/version
+s
+15
+celluloid/actor
+s
+21
+celluloid/actor_proxy
+s
+15
+celluloid/calls
+s
+18
+celluloid/core_ext
+s
+16
+celluloid/events
+s
+17
+celluloid/linking
+s
+17
+celluloid/mailbox
+s
+18
+celluloid/registry
+s
+19
+celluloid/responses
+s
+17
+celluloid/signals
+s
+20
+celluloid/supervisor
+s
+16
+celluloid/future
 p
-29
+31
 I
 0
 I
@@ -646,55 +739,59 @@ I
 I
 3
 I
-12
+23
 I
-4
+14
 I
-1b
+2c
 I
-5
+15
 I
-24
+35
 I
-6
+16
 I
-2d
+3e
 I
-7
+17
 I
-36
+47
 I
-8
+18
 I
-3f
+50
 I
-9
+19
 I
-48
+59
 I
-a
+1a
 I
-51
+62
 I
-b
+1b
 I
-5a
+6b
 I
-c
+1c
 I
-63
+74
 I
-d
+1d
 I
-6c
+7d
 I
-f
+1e
 I
-75
+86
 I
-11
+1f
+I
+8f
+I
+21
 I
-91
+9a
 x
 42
 /Users/tony/src/celluloid/lib/celluloid.rb