revactor 0.1.0 → 0.1.1

data/CHANGES

@@ -1,3 +1,25 @@
+0.1.1:
+
+* Eliminate Actor::Scheduler singleton and replace with thread-specific
+  scheduler objects.
+
+* Eliminate Actor.start: now there's a current Actor by default in every thread.
+  This paves the way towards thread safety.
+
+* Rename Revactor::Server to Revactor::Delegator and make more like delegator.rb
+
+* Factor apart actor.rb into scheduler.rb and mailbox.rb
+
+* Provide Revactor modules classes within the Actor namespace unless they have
+  already been defined
+
+* Fix Revactor::Filter initialization bug
+
+* Include Revactor::VERSION variable
+
+* Mailbox filters can now include only a timeout (i.e. sleep).  Added an
+  Actor.sleep shortcut to this behavior.
+
 0.1.0:
 
 * Initial release

data/README

@@ -33,34 +33,16 @@ network servers painlessly while still guaranteeing correct operation:
   can preprocess or postprocess data before it's even delivered to an Actor.
   This is useful for handling protocol framing or other streaming transforms.
 
-* Behaviors - These are patterns for implementing Actors which accomplish
-  specific tasks.  Right now only the Server behavior is supported.
-
 == Actors
 
-Actors add mailboxes to Ruby's Fiber mechanism.  They multitask cooperatively,
-meaning that many of the worries surrounding threaded programming disappear.
-Any sequence of operations you do in an Actor are executed in the order
-you specify.  You don't (generally) have to worry about another Actor doing 
-something in the background as you frob a particular data structure.
-
-Unfortunately, in Ruby 1.9, Actors are not first-class citizens.  This means
-you will need to jump from the non-Actor world to the Actor world before you
-can do anything with Actors.  This is accomplished by running Actor.start:
-
-  # Not in Actor world
-  Actor.start do
-    # In Actor world, yay
-    ...
-  end
-  # Won't get called until all Actors have processes their entire mailbox
-  # and aren't waiting for any events.
+Actors are lightweight concurrency primitives which communicate using message
+passing.  They multitask cooperatively, meaning that many of the worries 
+surrounding threaded programming disappear.  Any sequence of operations you do 
+in an Actor are executed in the order you specify.  You don't (generally) have 
+to worry about another Actor doing something in the background as you frob a 
+particular data structure.
 
-Ideally, what you place in Actor.start is a small startup routine which
-spawns all the Actors your application needs to get started and nothing else.
-
-Once you're in Actor world, you can begin making Actors and sending them
-events.  You create Actors with Actor.spawn:
+Actors are created by calling Actor.spawn:
 
   myactor = Actor.spawn { puts "I'm an Actor!" }
 
@@ -84,6 +66,9 @@ prints:
 
   "Yay, I got a dog!"
 
+You can retrieve the current Actor by calling Actor.current.  There will always 
+be a default Actor available for every Thread.
+
 == Mailboxes
 
 So, Actors can receive messages.  But where do those messages go?  The answer
@@ -101,12 +86,9 @@ against a message and a block to call if the message matches.  The pattern is
 compared to the message using ===, the same thing Ruby uses for case statements.
 You can think of the filter as a big case statement.
 
-Understanding the === statement is a bit strange, so here's a short guide:
-
-You can pass #when a class to match against the message.  Obviously passing it
-Object will match all messages.
-
-You can pass #when a regexp to match against the message.
+Like the case statement, a class matches any objects of that class.  Since all 
+classes descend from Object passing Object will match all messages.  You can
+also pass a regexp to match against a string.
 
 Revactor installs the Case gem by default.  This is useful for matching against
 messages stored in Arrays, or in fixed-size arrays called Tuples.  Case can
@@ -277,24 +259,6 @@ remaining message.  This is a simple and straightforward way to frame
 discrete messages on top of a streaming protocol like TCP, and is used for,
 among other things, DRb.
 
-== Behaviors
-
-Behaviors are kind of like design patterns for Actors.  Often you just want
-an Actor to hold some state and service calls which query or mutate that state.
-This behavior is wrapped up as a Server.
-
-To begin implementing a server, look at Revactor::Behavior::Server, which is
-a module demonstrating the API.  Servers are implemented using a set of
-callbacks which are called in response to certain events.
-
-Servers should implement a number of principles, including transactional
-semantics, however due to the side effect potential of mutable state in
-Ruby this isn't possible to achieve.
-
-Future versions of Revactor may attempt to address this, and also change the
-present implementation (which is effectively a carbon copy of Erlang's 
-gen_server) to be more Ruby-like.
-
 == Mongrel
 
 Revactor includes complete support for running Mongrel on top of Actors and

data/examples/echo_server.rb

@@ -7,32 +7,28 @@ require File.dirname(__FILE__) + '/../lib/revactor'
 HOST = 'localhost'
 PORT = 4321
 
-# Before we can begin using actors we have to call Actor.start
-# Future versions of Revactor will hopefully eliminate this
-Actor.start do
-  # Create a new listener socket on the given host and port
-  listener = Revactor::TCP.listen(HOST, PORT)
-  puts "Listening on #{HOST}:#{PORT}"
+# Create a new listener socket on the given host and port
+listener = Revactor::TCP.listen(HOST, PORT)
+puts "Listening on #{HOST}:#{PORT}"
 
-  # Begin receiving connections
-  loop do
-    # Accept an incoming connection and start a new Actor
-    # to handle it
-    Actor.spawn(listener.accept) do |sock|
-      puts "#{sock.remote_addr}:#{sock.remote_port} connected"
+# Begin receiving connections
+loop do
+  # Accept an incoming connection and start a new Actor
+  # to handle it
+  Actor.spawn(listener.accept) do |sock|
+    puts "#{sock.remote_addr}:#{sock.remote_port} connected"
 
-      # Begin echoing received data
-      loop do
-        begin
-          # Write everything we read
-          sock.write sock.read
-        rescue EOFError
-          puts "#{sock.remote_addr}:#{sock.remote_port} disconnected"
+    # Begin echoing received data
+    loop do
+      begin
+        # Write everything we read
+        sock.write sock.read
+      rescue EOFError
+        puts "#{sock.remote_addr}:#{sock.remote_port} disconnected"
 
-          # Break (and exit the current actor) if the connection
-          # is closed, just like with a normal Ruby socket
-          break
-        end
+        # Break (and exit the current actor) if the connection
+        # is closed, just like with a normal Ruby socket
+        break
       end
     end
   end

data/examples/google.rb

@@ -3,22 +3,20 @@
 require 'cgi'
 require File.dirname(__FILE__) + '/../lib/revactor'
 
-Actor.start do
-  term = ARGV[0] || 'foobar'
-  sock = Revactor::TCP.connect("www.google.com", 80)
+term = ARGV[0] || 'foobar'
+sock = Revactor::TCP.connect("www.google.com", 80)
 
-  sock.write [
-    "GET /search?q=#{CGI.escape(term)} HTTP/1.0",
-    "Host: www.google.com",
-    "\r\n"
-  ].join("\r\n")
+sock.write [
+  "GET /search?q=#{CGI.escape(term)} HTTP/1.0",
+  "Host: www.google.com",
+  "\r\n"
+].join("\r\n")
 
-  loop do
-    begin
-      STDOUT.write sock.read
-      STDOUT.flush
-    rescue EOFError
-      break
-    end
+loop do
+  begin
+    STDOUT.write sock.read
+    STDOUT.flush
+  rescue EOFError
+    break
   end
 end

data/examples/mongrel.rb

@@ -5,7 +5,7 @@ require File.dirname(__FILE__) + '/../lib/revactor/mongrel'
 ADDR = '127.0.0.1'
 PORT = 8080
 
-Actor.start do
+Actor.spawn do
   server = Mongrel::HttpServer.new(ADDR, PORT)
   server.register '/', Mongrel::DirHandler.new(".")
   server.run

data/lib/revactor.rb

@@ -4,7 +4,6 @@
 # See file LICENSE for details
 #++
 
-require 'rubygems'
 require 'rev'
 require 'case'
 
@@ -21,9 +20,18 @@ end
 # Shortcut Tuple as T
 T = Tuple unless defined? T
 
-require File.dirname(__FILE__) + '/revactor/actor'
-require File.dirname(__FILE__) + '/revactor/server'
-require File.dirname(__FILE__) + '/revactor/tcp'
-require File.dirname(__FILE__) + '/revactor/behaviors/server'
-require File.dirname(__FILE__) + '/revactor/filters/line'
-require File.dirname(__FILE__) + '/revactor/filters/packet'
+module Revactor
+  Revactor::VERSION = '0.1.1' unless defined? Revactor::VERSION
+  def self.version() VERSION end
+end
+
+%w{actor scheduler mailbox delegator tcp filters/line filters/packet}.each do |file|
+  require File.dirname(__FILE__) + '/revactor/' + file
+end
+
+# Place Revactor modules and classes under the Actor namespace
+class Actor
+  Actor::TCP = Revactor::TCP unless defined? Actor::TCP
+  Actor::Filter = Revactor::Filter unless defined? Actor::Filter
+  Actor::Delegator = Revactor::Delegator unless defined? Actor::Delegator
+end

data/lib/revactor/actor.rb

@@ -5,10 +5,22 @@
 #++
 
 require File.dirname(__FILE__) + '/../revactor'
+require 'thread'
 require 'fiber'
 
-# Raised whenever any Actor-specific problems occur
-class ActorError < StandardError; end
+# Monkeypatch Thread to include a method for obtaining the current Scheduler
+class Thread
+  def _revactor_scheduler
+    @_revactor_scheduler ||= Actor::Scheduler.new
+  end
+end
+
+# Monkeypatch Fiber to include a method for obtaining the current Actor
+class Fiber
+  def _actor
+    @_actor ||= Actor.new
+  end
+end
 
 # Actors are lightweight concurrency primitives which communiucate via message
 # passing.  Each actor has a mailbox which it scans for matching messages.
@@ -21,43 +33,52 @@ class ActorError < StandardError; end
 # should be possible to run programs written using Revactor to on top of other
 # Actor implementations.
 #
-class Actor < Fiber
-  include Enumerable
+class Actor
+  attr_reader :fiber
+  attr_reader :scheduler
+  attr_reader :mailbox
+  
   @@registered = {}
 
   class << self
-    include Enumerable
-
     # Create a new Actor with the given block and arguments
-    def new(*args, &block)
+    def spawn(*args, &block)
       raise ArgumentError, "no block given" unless block
-      actor = super() do 
+      
+      fiber = Fiber.new do
         block.call(*args)
-        Actor.current.instance_eval { @_dead = true }
+        Actor.current.instance_eval { @dead = true }
       end
-
-      # For whatever reason #initialize is never called in subclasses of Fiber
-      actor.instance_eval do 
-        @_dead = false
-        @_mailbox = Mailbox.new
-        @_dictionary = {}
-      end
-
-      Scheduler << actor
+      
+      actor = Actor.new(fiber)
+      fiber.instance_eval { @_actor = actor }
+      
+      Actor.scheduler << actor
       actor
     end
     
-    alias_method :spawn, :new
-    
-    # This will be defined differently in the future, but now the two are the same
-    alias_method :start, :new
-    
     # Obtain a handle to the current Actor
     def current
-      actor = super
-      raise ActorError, "current fiber is not an actor" unless actor.is_a? Actor
-      
-      actor 
+      Fiber.current._actor
+    end
+    
+    # Obtain a handle to the current Scheduler
+    def scheduler
+      Thread.current._revactor_scheduler
+    end
+    
+    # Reschedule the current actor for execution later
+    def reschedule
+      if scheduler.running? 
+        Fiber.yield
+      else
+        Actor.scheduler << Actor.current
+      end
+    end
+    
+    # Sleep for the specified number of seconds
+    def sleep(seconds)
+      Actor.receive { |filter| filter.after(seconds) }
     end
     
     # Wait for messages matching a given filter.  The filter object is yielded
@@ -69,11 +90,7 @@ class Actor < Fiber
     # The first filter to match a message in the mailbox is executed.  If no
     # filters match then the actor sleeps.
     def receive(&filter)
-      unless current.is_a?(Actor)
-        raise ActorError, "receive must be called in the context of an Actor"
-      end
-
-      current.__send__(:_mailbox).receive(&filter)
+      current.mailbox.receive(&filter)
     end
 
     # Look up an actor in the global dictionary
@@ -94,223 +111,56 @@ class Actor < Fiber
     def delete(key, &block)
       @@registered.delete(key, &block)
     end
-
-    # Iterate over the actors in the global dictionary
-    def each(&block)
-      @@registered.each(&block)
-    end
+  end
+  
+  def initialize(fiber = Fiber.current)
+    raise ArgumentError, "use Actor.spawn to create actors" if block_given?
+    
+    @fiber = fiber
+    @scheduler = Actor.scheduler
+    @thread = Thread.current
+    @mailbox = Mailbox.new
+    @dead = false
+    @dictionary = {}
+  end
+  
+  def inspect
+    "#<#{self.class}:0x#{object_id.to_s(16)}>"
   end
   
   # Look up value in the actor's dictionary
   def [](key)
-    @_dictionary[key]
+    @dictionary[key]
   end
   
   # Store a value in the actor's dictionary
   def []=(key, value)
-    @_dictionary[key] = value
+    @dictionary[key] = value
   end
   
   # Delete a value from the actor's dictionary
   def delete(key, &block)
-    @_dictionary.delete(key, &block)
-  end
-  
-  # Iterate over values in the actor's dictionary
-  def each(&block)
-    @_dictionary.each(&block)
+    @dictionary.delete(key, &block)
   end
   
   # Is the current actor dead?
-  def dead?; @_dead; end
+  def dead?; @dead; end
   
   # Send a message to an actor
   def <<(message)
+    return "can't send messages to actors across threads" unless @thread == Thread.current
+        
     # Erlang discards messages sent to dead actors, and if Erlang does it,
     # it must be the right thing to do, right?  Hooray for the Erlang 
     # cargo cult!  I think they do this because dealing with errors raised
-    # from dead actors complicates overall error handling too much to be worth it.
+    # from dead actors greatly overcomplicates overall error handling
     return message if dead?
     
-    @_mailbox << message
-    Scheduler << self
+    @mailbox << message    
+    @scheduler << self
+    
     message
   end
 
   alias_method :send, :<<
-  
-  #########
-  protected
-  #########
-  
-  attr_reader :_mailbox
-  
-  # The Actor Scheduler maintains a run queue of actors with outstanding
-  # messages who have not yet processed their mailbox.  If all actors have
-  # processed their mailboxes then the scheduler waits for any outstanding
-  # Rev events.  If there are no active Rev watchers then the scheduler exits.
-  class Scheduler
-    @@queue = []
-    @@running = false
-
-    class << self
-      # Schedule an Actor to be executed, and run the scheduler if it isn't
-      # currently running
-      def <<(actor)
-        @@queue << actor
-        run unless @@running
-      end
-      
-      # Run the scheduler
-      def run
-        return if @@running
-        @@running = true
-        default_loop = Rev::Loop.default
-        
-        until @@queue.empty? and default_loop.watchers.empty?
-          @@queue.each do |actor|
-            begin
-              actor.resume
-            rescue FiberError # Fiber may have died since being scheduled 
-            end
-          end
-          
-          @@queue.clear
-          
-          default_loop.run_once unless default_loop.watchers.empty?
-        end
-        
-        @@running = false
-      end
-    end
-  end
-
-  # Actor mailbox.  For purposes of efficiency the mailbox also handles 
-  # suspending and resuming an actor when no messages match its filter set.
-  class Mailbox
-    attr_accessor :timer
-    attr_accessor :timed_out
-    attr_accessor :timeout_action
-
-    def initialize
-      @timer = nil
-      @queue = []
-    end
-
-    # Add a message to the mailbox queue
-    def <<(message)
-      @queue << message
-    end
-
-    # Attempt to receive a message
-    def receive
-      raise ArgumentError, "no filter block given" unless block_given?
-
-      # Clear mailbox processing variables
-      action = matched_index = nil
-      processed_upto = 0
-      
-      # Clear timeout variables
-      @timed_out = false
-      @timeout_action = nil
-      
-      # Build the filter
-      filter = Filter.new(self)
-      yield filter
-      raise ArgumentError, "empty filter" if filter.empty?
-
-      # Process incoming messages
-      while action.nil?
-        @queue[processed_upto..@queue.size].each_with_index do |message, index|
-          unless (action = filter.match message)
-            # The filter did not match an action for the current message
-            # Keep track of which messages we've ran the filter across so it doesn't
-            # get run against messages it already failed to match
-            processed_upto += 1
-            next
-          end
-          
-          # We've found a matching action, so break out of the loop
-          matched_index = processed_upto + index
-          break
-        end
-
-        # If we've timed out, run the timeout action unless another has been found
-        action ||= @timeout_action if @timed_out
-
-        # If we didn't find a matching action, yield until we get another message
-        Actor.yield unless action
-      end
-
-      if @timer
-        @timer.detach if @timer.attached?
-        @timer = nil
-      end
-      
-      # If we encountered a timeout, call the action directly
-      return action.call if @timed_out
-      
-      # Otherwise we matched a message, so process it with the action      
-      return action.(@queue.delete_at matched_index)
-    end
-
-    # Timeout class, used to implement receive timeouts
-    class Timer < Rev::TimerWatcher
-      def initialize(timeout, actor)
-        @actor = actor
-        super(timeout)
-      end
-
-      def on_timer
-        @actor.instance_eval { @_mailbox.timed_out = true }
-        Scheduler << @actor
-      end
-    end
- 
-    # Mailbox filterset.  Takes patterns or procs to match messages with
-    # and returns the associated proc when a pattern matches.
-    class Filter
-      def initialize(mailbox)
-        @mailbox = mailbox
-        @ruleset = []
-      end
-
-      # Provide a pattern to match against with === and a block to call
-      # when the pattern is matched.
-      def when(pattern, &action)
-        raise ArgumentError, "no block given" unless action
-        @ruleset << [pattern, action]
-      end
-
-      # Provide a timeout (in seconds, can be a Float) to wait for matching
-      # messages.  If the timeout elapses, the given block is called.
-      def after(timeout, &action)
-        raise ArgumentError, "timeout already specified" if @mailbox.timer
-        raise ArgumentError, "must be zero or positive" if timeout < 0
-        
-        # Don't explicitly require an action to be specified for a timeout
-        @mailbox.timeout_action = action || proc {}
-        
-        if timeout > 0
-          @mailbox.timer = Timer.new(timeout, Actor.current).attach(Rev::Loop.default)
-        else
-          # No need to actually set a timer if the timeout is zero, 
-          # just short-circuit waiting for one entirely...
-          @timed_out = true
-          Scheduler << self
-        end
-      end
-
-      # Match a message using the filter
-      def match(message)
-        _, action = @ruleset.find { |pattern, _| pattern === message }
-        action
-      end
-
-      # Is the filterset empty?
-      def empty?
-        @ruleset.empty?
-      end
-    end
-  end
-end
+end