thespian 0.0.1 → 0.1.0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - jruby-18mode

data/CHANGELOG

@@ -1,2 +1,10 @@
+0.1.0 
+	* Added support for different modes
+		* Threaded mode (default)
+		* Fibered mode
+	* Added Thespian.actor{ ... } as alias for Thespian.actor.receive{ ... }
+	* Added Thespian::Actor#mailbox_size
+
+
 0.0.1
 	* Initial release

data/README.rdoc

@@ -1,6 +1,6 @@
-== Thespian
+== Thespian {<img src="https://secure.travis-ci.org/cjbottaro/thespian.png" />}[http://travis-ci.org/cjbottaro/thespian]
 
-Implementation of the actor pattern built on threads.
+Implementation of the actor pattern built for use with threads and/or fibers.
 
 == Quickstart
 
@@ -66,7 +66,7 @@ an error occurred).
 
 What happens if an actor causes an unhandled exception while processing a message?  The actor's
 state will be set to +:finished+, Thespian::Actor#error? will return true and subsequent calls to
-various methods will cause the exception to be raised in the calling thread.
+various methods will cause the exception to be raised in the calling thread or fiber.
 
   actor = Thespian::Actor.new do |message|
     raise "oops"
@@ -162,6 +162,49 @@ to it's parent object.
 What does that mean?  Nothing really.  The only difference is that Thespian::DeadActorError#actor
 will return an instance of ArnoldSchwarzenegger instead of an instance of Thespian::Actor.
 
+== Fibers
+
+Actors run on threads by default, but you can seamlessly run them on fibers instead:
+
+  actor = Thespian::Actor.new(:mode => :fiber){ ... }
+
+Or:
+
+  class ArnoldSchwarzenegger
+    include Thespian
+
+    # Any of these will work
+
+    actor(:mode => :fiber).receive{ |message| ... }
+
+    actor.options[:mode] = :fiber
+  end
+
+When running in fibered mode, be sure that your actors are executing inside EventMachine's reactor loop.
+Also be sure that there is a root fiber.  In other words, something like...
+
+  EventMachine.run do
+    Fiber.new do
+
+      ###
+      # Your actor code here
+      ###
+
+      EventMachine.stop
+    end.resume
+  end
+
+Thespian uses {Strand}[https://github.com/cjbottaro/strand] behind the scenes which to deal with fibers.
+{Strand}[https://github.com/cjbottaro/strand] is an abstraction that makes fibers behave like threads when
+used with EventMachine.  You will need to install {Strand}[https://github.com/cjbottaro/strand] to use
+Thespian in fibered mode:
+
+  gem "strand"
+
+You can change the default mode for all Actors with the following:
+
+  Thespian::Actor::DEFAULT_OPTIONS[:mode] = :fiber
+
 == RDoc
 
 {\http://doc.stochasticbytes.com/thespian/index.html}[http://doc.stochasticbytes.com/thespian/index.html]
@@ -169,10 +212,13 @@ will return an instance of ArnoldSchwarzenegger instead of an instance of Thespi
 == Examples
 
 A simple producer/consumer example.
+
 {\https://github.com/cjbottaro/thespian/blob/master/examples/producer_consumer.rb}[https://github.com/cjbottaro/thespian/blob/master/examples/producer_consumer.rb]
 
 An example where one actor links to another.
+
 {\https://github.com/cjbottaro/thespian/blob/master/examples/linked.rb}[https://github.com/cjbottaro/thespian/blob/master/examples/linked.rb]
 
 A complex example showing how a background job/task processor could be architected.
+
 {\https://github.com/cjbottaro/thespian/blob/master/examples/task_processor.rb}[https://github.com/cjbottaro/thespian/blob/master/examples/task_processor.rb]

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+task :default => :spec
+
+desc "Run specs (default)"
+RSpec::Core::RakeTask.new do |t|
+  # Put spec opts in a file named .rspec in root
+end

data/examples/linked.rb

@@ -1,39 +1,45 @@
 require "thespian"
+require "thespian/example"
 
-producer = nil
-consumer = nil
-n = 0
+Thespian::Example.run do
 
-producer = Thespian::Actor.new do |message|
-  case message
-  when :need_item
-    if (n += 1) < 10
-      consumer << rand
+  producer = nil
+  consumer = nil
+  n = 0
+
+  producer = Thespian::Actor.new do |message|
+    case message
+    when :need_item
+      if (n += 1) < 10
+        consumer << rand
+      else
+        consumer << "bad message"
+      end
     else
-      consumer << "bad message"
+      raise "unexpected message: #{message}"
     end
-  else
-    raise "unexpected message: #{message}"
   end
-end
 
-consumer = Thespian::Actor.new do |message|
-  case message
-  when Float
-    puts "consumer got #{message}"
-    producer << :need_item
-  else
-    raise "I can only work with numbers!"
+  consumer = Thespian::Actor.new do |message|
+    case message
+    when Float
+      puts "consumer got #{message}"
+      producer << :need_item
+    else
+      raise "I can only work with numbers!"
+    end
   end
-end
 
-producer.link(consumer)
-producer.start
-consumer.start
-producer << :need_item
-Thread.pass while consumer.running?
-puts consumer.finished?  # True
-puts consumer.error?     # True
-puts producer.finished?  # True because it's linked to the consumer
-puts producer.error?     # True because it's linked to the consumer
-puts producer.exception
+  producer.link(consumer)
+  producer.start
+  consumer.start
+  producer << :need_item
+  pass while consumer.running?
+  pass while producer.running?
+  puts consumer.finished?  # True
+  puts consumer.error?     # True
+  puts producer.finished?  # True because it's linked to the consumer
+  puts producer.error?     # True because it's linked to the consumer
+  puts producer.exception  
+
+end

data/examples/producer_consumer.rb

@@ -1,24 +1,32 @@
 require "thespian"
+require "thespian/example"
 
-producer = nil
-consumer = nil
+Thespian::Example.run do
 
-producer = Thespian::Actor.new do |message|
-  case message
-  when :need_item
-    consumer << rand
-  else
-    raise "unexpected message: #{message}"
+  producer = nil
+  consumer = nil
+
+  producer = Thespian::Actor.new do |message|
+    case message
+    when :need_item
+      consumer << rand
+    else
+      raise "unexpected message: #{message}"
+    end
+  end
+
+  consumer = Thespian::Actor.new do |message|
+    sleep(message)
+    puts "consumer got #{message}"
+    producer << :need_item
   end
-end
 
-consumer = Thespian::Actor.new do |message|
-  sleep(message)
-  puts "consumer got #{message}"
+  producer.start
+  consumer.start
   producer << :need_item
-end
+  while true
+    sleep(1)
+    puts "Total threads: #{Thread.list.length}"
+  end
 
-producer.start
-consumer.start
-producer << :need_item
-sleep
+end

data/examples/task_processor.rb

@@ -1,4 +1,5 @@
 require "thespian"
+require "thespian/example"
 
 # The actors are Supervisor, Logger, Poller, Worker(s).  There is one of each except for multiple
 # workers.  The basic idea is that the supervisor can send messages to any other actor, but all
@@ -114,7 +115,7 @@ class Supervisor
       do_log("worker(#{actor.id}) died, restarting")
       initialize_worker(actor.id)
     when Poller
-      do_log("poller died (#{@ready.length}, #{@poller.actor.instance_eval{ @mailbox }.length}), restarting")
+      do_log("poller died (#{@ready.length}, #{@poller.actor.mailbox_size}), restarting")
       initialize_poller
     end
   end
@@ -163,8 +164,11 @@ class Supervisor
 
 end
 
-s = Supervisor.new(5)
-while true
-  raise s.actor.exception unless s.actor.running?
-  sleep(1)
+Thespian::Example.run do
+  s = Supervisor.new(5)
+  while true
+    sleep(1)
+    raise s.actor.exception unless s.actor.running?
+    puts "Total threads: #{Thread.list.length}"
+  end
 end

data/lib/thespian.rb

@@ -2,6 +2,8 @@ require "thespian/actor"
 require "thespian/dsl"
 require "thespian/version"
 
+require "thespian/strategies/interface"
+
 # Include this module into classes to give them acting abilities.
 #   class ArnoldSchwarzenegger
 #     include Thespian
@@ -30,8 +32,14 @@ module Thespian
 
   module ClassMethods #:nodoc:
     
-    def actor
+    def actor(options = nil, &block)
       @actor ||= Dsl.new
+      @actor.options = options if options
+      if block_given?
+        @actor.receive(&block)
+      else
+        @actor
+      end
     end
 
   end
@@ -39,7 +47,7 @@ module Thespian
   module InstanceMethods #:nodoc:
 
     def actor
-      @actor ||= Actor.new(:object => self, &self.class.actor.receive_block)
+      @actor ||= Actor.new(self.class.actor.options.merge(:object => self), &self.class.actor.receive_block)
     end
 
   end

data/lib/thespian/actor.rb

@@ -13,6 +13,9 @@ module Thespian
     # Returns the actor's state.
     attr_reader :state
 
+    attr_reader :strategy
+    private :strategy
+
     # The state an actor is in after it has been created, but before it enters the message processing loop.
     STATE_INITIALIZED = :initialized
 
@@ -23,6 +26,7 @@ module Thespian
     STATE_FINISHED = :finished
 
     DEFAULT_OPTIONS = {
+      :mode      => :thread,
       :strict    => true,
       :trap_exit => false,
       :object    => nil
@@ -42,10 +46,12 @@ module Thespian
       @receive_block = block
       @linked_actors = Set.new
 
-      @mailbox = []
-      @mailbox_lock = Monitor.new
-      @mailbox_cond = @mailbox_lock.new_cond
+      @strategy = strategy_class.new{ run }
+    end
 
+    def strategy_class #:nodoc:
+      class_name = options[:mode].to_s.capitalize
+      Strategy.const_get(class_name)
     end
 
     # call-seq:
@@ -54,6 +60,9 @@ module Thespian
     #   options(symbol) -> value
     #
     # Get or set options.  Valid options are:
+    # [:mode (default :thread)]
+    #   What mode to create the actor in.  Choices are +:fiber+ or +:thread+.  When running in fibered mode,
+    #   be sure that EventMachine's reactor is running and there is a root fiber.
     # [:strict (default true)]
     #   Require an actor to be running in order to put messages into its mailbox.
     # [:trap_exit (default false)]
@@ -106,25 +115,7 @@ module Thespian
       # before staring the thread.
       @state = :running
 
-      # Declare local synchronization vars.
-      lock = Monitor.new
-      cond = lock.new_cond
-      wait = true
-
-       # Start the thread and have it signal when it's running.
-      @thread = Thread.new do
-        Thread.current[:actor] = options(:object).to_s
-        lock.synchronize do
-          wait = false
-          cond.signal
-        end
-        run
-      end
-
-      # Block until the thread has signaled that it's running.
-      lock.synchronize do
-        cond.wait_while{ wait }
-      end
+      @strategy.start
     end
 
     # Add a message to the actor's mailbox.
@@ -132,10 +123,7 @@ module Thespian
     def <<(message)
       check_alive! if options(:strict)
       message = message.new if message == Stop
-      @mailbox_lock.synchronize do
-        @mailbox << message
-        @mailbox_cond.signal
-      end
+      @strategy << message
       self
     end
 
@@ -145,7 +133,7 @@ module Thespian
     def stop
       check_alive! if options(:strict)
       self << Stop.new
-      @thread.join
+      @strategy.stop
       raise @exception if @exception
     end
 
@@ -169,12 +157,17 @@ module Thespian
       !!@exception
     end
 
+    # Returns how many messages are in the actor's mailbox.
+    def mailbox_size
+      @strategy.mailbox_size
+    end
+
     # Salvage mailbox contents from a dead actor (including the message it died on).
     # Useful for restarting a dead actor while preserving its mailbox.
     def salvage_mailbox
-      raise "cannot salvage mailbox from an actor that isn't finished" unless state == :finished
-      @mailbox.dup.tap do |mailbox|
-        mailbox.unshift(@last_message) if @last_message
+      raise "cannot salvage mailbox from an actor that isn't finished" unless finished?
+      @strategy.messages.tap do |messages|
+        messages.unshift(@last_message) if @last_message
       end
     end
 
@@ -202,13 +195,9 @@ module Thespian
 
     # Receive a message from the actor's mailbox.
     def receive
-      message = @mailbox_lock.synchronize do
-        @mailbox_cond.wait_while{ @mailbox.empty? }
-        @message = @mailbox.shift
-      end
 
       # Communicate with #run by possibly raising exceptions here.
-      case message
+      case (message = @strategy.receive)
       when DeadActorError
         raise message unless options(:trap_exit)
       when Stop

data/lib/thespian/dsl.rb

@@ -1,6 +1,11 @@
 module Thespian
   class Dsl #:nodoc:
     attr_reader :receive_block
+    attr_accessor :options
+
+    def initialize
+      @options = {}
+    end
 
     def receive(&block)
       @receive_block = block

data/lib/thespian/example.rb

@@ -0,0 +1,41 @@
+module Thespian
+  # This class aids in running the examples in the different modes.
+  #
+  # To run in threaded mode, just run without arguments:
+  #   bundle exec ruby examples/task_processor.rb
+  # To run in fibered mode:
+  #   bundle exec ruby examples/task_processor.rb --fiber
+  # This class does all the necessary incantations necessary to run
+  # in fibered mode (starts/stops EventMachine, wraps in root fiber, etc).
+  class Example
+
+    # Determine what mode to run in by looking at ARGV then invoke the block given.
+    # If running in fibered mode, the block will be wrapped with necessary calls
+    # to EventMachine and Fiber.  It will also make sure to define fiber
+    # safe versions of #sleep and #pass that the example can use.
+    def self.run(&example)
+      if ARGV.include?("--fiber") || ARGV.include?("--fibers")
+        require "eventmachine"
+        require "strand"
+        EM.run do
+          Strand.new do
+            puts "Running example with fibers..."
+            Thespian::Actor::DEFAULT_OPTIONS[:mode] = :fiber
+            example.binding.eval <<-CODE
+              def sleep(n); Strand.sleep(n); end
+              def pass; Strand.pass; end
+            CODE
+            example.call
+            EM.stop
+          end
+        end
+      else
+        puts "Running example with threads..."
+        example.binding.eval <<-CODE
+          def pass; Thread.pass; end
+        CODE
+        example.call
+      end
+    end
+  end
+end