kulesa-celluloid 0.10.2

data/lib/celluloid/fsm.rb

@@ -0,0 +1,151 @@
+module Celluloid
+  # Simple finite state machines with integrated Celluloid timeout support
+  # Inspired by Erlang's gen_fsm (http://www.erlang.org/doc/man/gen_fsm.html)
+  #
+  # Basic usage:
+  #
+  #     class MyMachine
+  #       include Celluloid::FSM # NOTE: this does NOT pull in the Celluloid module
+  #     end
+  #
+  # Inside an actor:
+  #
+  #     #
+  #     machine = MyMachine.new(current_actor)
+  module FSM
+    class UnattachedError < StandardError; end # Not attached to an actor
+
+    DEFAULT_STATE = :default # Default state name unless one is explicitly set
+
+    # Included hook to extend class methods
+    def self.included(klass)
+      klass.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      # Obtain or set the default state
+      # Passing a state name sets the default state
+      def default_state(new_default = nil)
+        if new_default
+          @default_state = new_default.to_sym
+        else
+          defined?(@default_state) ? @default_state : DEFAULT_STATE
+        end
+      end
+
+      # Obtain the valid states for this FSM
+      def states
+        @states ||= {}
+      end
+
+      # Declare an FSM state and optionally provide a callback block to fire
+      # Options:
+      # * to: a state or array of states this state can transition to
+      def state(*args, &block)
+        if args.last.is_a? Hash
+          # Stringify keys :/
+          options = args.pop.inject({}) { |h,(k,v)| h[k.to_s] = v; h }
+        else
+          options = {}
+        end
+
+        args.each do |name|
+          name = name.to_sym
+          default_state name if options['default']
+          states[name] = State.new(name, options['to'], &block)
+        end
+      end
+    end
+
+    attr_reader :actor
+
+    # Be kind and call super if you must redefine initialize
+    def initialize(actor = nil)
+      @state = self.class.default_state
+      @actor = actor
+      @actor ||= Celluloid.current_actor if Celluloid.actor?
+    end
+
+    # Obtain the current state of the FSM
+    attr_reader :state
+
+    # Attach this FSM to an actor. This allows FSMs to wait for and initiate
+    # events in the context of a particular actor
+    def attach(actor)
+      @actor = actor
+    end
+    alias_method :actor=, :attach
+
+    # Transition to another state
+    # Options:
+    # * delay: don't transition immediately, wait the given number of seconds.
+    #          This will return a Celluloid::Timer object you can use to
+    #          cancel the pending state transition.
+    #
+    # Note: making additional state transitions will cancel delayed transitions
+    def transition(state_name, options = {})
+      state_name = state_name.to_sym
+      current_state = self.class.states[@state]
+
+      return if current_state && current_state.name == state_name
+
+      if current_state and not current_state.valid_transition? state_name
+        valid = current_state.transitions.map(&:to_s).join(", ")
+        raise ArgumentError, "#{self.class} can't change state from '#{@state}' to '#{state_name}', only to: #{valid}"
+      end
+
+      new_state = self.class.states[state_name]
+
+      unless new_state
+        return if state_name == self.class.default_state
+        raise ArgumentError, "invalid state for #{self.class}: #{state_name}"
+      end
+
+      if options[:delay]
+        raise UnattachedError, "can't delay unless attached" unless @actor
+        @delayed_transition.cancel if @delayed_transition
+
+        @delayed_transition = @actor.after(options[:delay]) do
+          transition! new_state.name
+          new_state.call(self)
+        end
+
+        return @delayed_transition
+      end
+
+      if defined?(@delayed_transition) and @delayed_transition
+        @delayed_transition.cancel
+        @delayed_transition = nil
+      end
+
+      transition! new_state.name
+      new_state.call(self)
+    end
+
+    # Immediate state transition with no sanity checks. "Dangerous!"
+    def transition!(state_name)
+      @state = state_name
+    end
+
+    # FSM states as declared by Celluloid::FSM.state
+    class State
+      attr_reader :name, :transitions
+
+      def initialize(name, transitions = nil, &block)
+        @name, @block = name, block
+        @transitions = Array(transitions).map { |t| t.to_sym } if transitions
+      end
+
+      def call(obj)
+        obj.instance_eval(&@block) if @block
+      end
+
+      def valid_transition?(new_state)
+        # All transitions are allowed unless expressly
+        return true unless @transitions
+
+        @transitions.include? new_state.to_sym
+      end
+    end
+  end
+end

data/lib/celluloid/future.rb

@@ -0,0 +1,110 @@
+require 'thread'
+
+module Celluloid
+  # Celluloid::Future objects allow methods and blocks to run in the
+  # background, their values requested later
+  class Future
+    # Create a future bound to a given receiver, or with a block to compute
+    def initialize(*args, &block)
+      @mutex = Mutex.new
+      @ready = false
+      @result = nil
+      @forwards = nil
+
+      if block
+        @call = SyncCall.new(self, :call, args)
+        InternalPool.get do
+          begin
+            @call.dispatch(block)
+          rescue
+            # Exceptions in blocks will get raised when the value is retrieved
+          end
+        end
+      else
+        @call = nil
+      end
+    end
+
+    # Execute the given method in future context
+    def execute(receiver, method, args, block)
+      @mutex.synchronize do
+        raise "already calling" if @call
+        @call = SyncCall.new(self, method, args, block)
+      end
+
+      receiver << @call
+    end
+
+    # Obtain the value for this Future
+    def value(timeout = nil)
+      ready = result = nil
+
+      begin
+        @mutex.lock
+        raise "no call requested" unless @call
+
+        if @ready
+          ready = true
+          result = @result
+        else
+          case @forwards
+          when Array
+            @forwards << Thread.mailbox
+          when NilClass
+            @forwards = Thread.mailbox
+          else
+            @forwards = [@forwards, Thread.mailbox]
+          end
+        end
+      ensure
+        @mutex.unlock
+      end
+
+      unless ready
+        result = Thread.receive(timeout) do |msg|
+          msg.is_a?(Future::Result) && msg.future == self
+        end
+      end
+
+      if result
+        result.value
+      else
+        raise "Timed out"
+      end
+    end
+    alias_method :call, :value
+
+    # Signal this future with the given result value
+    def signal(value)
+      result = Result.new(value, self)
+
+      @mutex.synchronize do
+        raise "the future has already happened!" if @ready
+
+        if @forwards
+          @forwards.is_a?(Array) ? @forwards.each { |f| f << result } : @forwards << result
+        end
+
+        @result = result
+        @ready = true
+      end
+    end
+    alias_method :<<, :signal
+
+    # Inspect this Celluloid::Future
+    alias_method :inspect, :to_s
+
+    # Wrapper for result values to distinguish them in mailboxes
+    class Result
+      attr_reader :future
+
+      def initialize(result, future)
+        @result, @future = result, future
+      end
+
+      def value
+        @result.value
+      end
+    end
+  end
+end

data/lib/celluloid/group.rb

@@ -0,0 +1,90 @@
+module Celluloid
+  # Supervise collections of actors as a group
+  class Group
+    include Celluloid
+    trap_exit :restart_actor
+
+    class << self
+      # Actors or sub-applications to be supervised
+      def members
+        @members ||= []
+      end
+
+      # Start this application (and watch it with a supervisor)
+      alias_method :run!, :supervise
+
+      # Run the application in the foreground with a simple watchdog
+      def run
+        loop do
+          supervisor = run!
+
+          # Take five, toplevel supervisor
+          sleep 5 while supervisor.alive?
+
+          Logger.error "!!! Celluloid::Group #{self} crashed. Restarting..."
+        end
+      end
+
+      # Register an actor class or a sub-application class to be launched and
+      # supervised while this application is running. Available options are:
+      #
+      # * as: register this application in the Celluloid::Actor[] directory
+      # * args: start the actor with the given arguments
+      def supervise(klass, options = {})
+        members << Member.new(klass, options)
+      end
+    end
+
+    # Start the group
+    def initialize
+      @actors = {}
+
+      # This is some serious lolcode, but like... start the supervisors for
+      # this group
+      self.class.members.each do |member|
+        actor = member.start
+        @actors[actor] = member
+      end
+    end
+
+    # Terminate the group
+    def finalize
+      @actors.each do |actor, _|
+        begin
+          actor.terminate
+        rescue DeadActorError
+        end
+      end
+    end
+
+    # Restart a crashed actor
+    def restart_actor(actor, reason)
+      member = @actors.delete actor
+      raise "a group member went missing. This shouldn't be!" unless member
+
+      # Ignore supervisors that shut down cleanly
+      return unless reason
+
+      actor = member.start
+      @actors[actor] = member
+    end
+
+    # A member of the group
+    class Member
+      def initialize(klass, options = {})
+        @klass = klass
+
+        # Stringify keys :/
+        options = options.inject({}) { |h,(k,v)| h[k.to_s] = v; h }
+
+        @name = options['as']
+        @args = options['args'] ? Array(options['args']) : []
+      end
+
+      def start
+        actor = @klass.new_link(*@args)
+        Actor[@name] = actor if @name
+      end
+    end
+  end
+end

data/lib/celluloid/internal_pool.rb

@@ -0,0 +1,62 @@
+require 'thread'
+
+module Celluloid
+  # Maintain a thread pool FOR SPEED!!
+  module InternalPool
+    @pool = []
+    @mutex = Mutex.new
+
+    # TODO: should really adjust this based on usage
+    @max_idle = 16
+
+    class << self
+      attr_accessor :max_idle
+
+      # Get a thread from the pool, running the given block
+      def get(&block)
+        @mutex.synchronize do
+          begin
+            if @pool.empty?
+              thread = create
+            else
+              thread = @pool.shift
+            end
+          end until thread.status # handle crashed threads
+
+          thread[:queue] << block
+          thread
+        end
+      end
+
+      # Return a thread to the pool
+      def put(thread)
+        @mutex.synchronize do
+          if @pool.size >= @max_idle
+            thread[:queue] << nil
+          else
+            @pool << thread
+          end
+        end
+      end
+
+      # Create a new thread with an associated queue of procs to run
+      def create
+        queue = Queue.new
+        thread = Thread.new do
+          while proc = queue.pop
+            begin
+              proc.call
+            rescue => ex
+              Logger.crash("thread crashed", ex)
+            end
+
+            put thread
+          end
+        end
+
+        thread[:queue] = queue
+        thread
+      end
+    end
+  end
+end

data/lib/celluloid/links.rb

@@ -0,0 +1,61 @@
+require 'thread'
+
+module Celluloid
+  # Thread safe storage of inter-actor links
+  class Links
+    include Enumerable
+
+    def initialize
+      @links = {}
+      @lock  = Mutex.new
+    end
+
+    # Add an actor to the current links
+    def <<(actor)
+      @lock.synchronize do
+        @links[actor.mailbox.address] = actor
+      end
+      actor
+    end
+
+    # Do links include the given actor?
+    def include?(actor)
+      @lock.synchronize do
+        @links.has_key? actor.mailbox.address
+      end
+    end
+
+    # Remove an actor from the links
+    def delete(actor)
+      @lock.synchronize do
+        @links.delete actor.mailbox.address
+      end
+      actor
+    end
+
+    # Iterate through all links
+    def each
+      @lock.synchronize do
+        @links.each { |_, actor| yield(actor) }
+      end
+    end
+
+    # Map across links
+    def map
+      result = []
+      each { |actor| result << yield(actor) }
+      result
+    end
+
+    # Send an event message to all actors
+    def send_event(event)
+      each { |actor| actor.mailbox.system_event event }
+    end
+
+    # Generate a string representation
+    def inspect
+      links = self.map(&:inspect).join(',')
+      "#<#{self.class}[#{links}]>"
+    end
+  end
+end

data/lib/celluloid/logger.rb

@@ -0,0 +1,53 @@
+module Celluloid
+  module Logger
+    @exception_handlers = []
+    module_function
+
+    # Send a debug message
+    def debug(string)
+      Celluloid.logger.debug(string) if Celluloid.logger
+    end
+
+    # Send a info message
+    def info(string)
+      Celluloid.logger.info(string) if Celluloid.logger
+    end
+
+    # Send a warning message
+    def warn(string)
+      Celluloid.logger.warn(string) if Celluloid.logger
+    end
+
+    # Send an error message
+    def error(string)
+      Celluloid.logger.error(string) if Celluloid.logger
+    end
+
+    # Handle a crash
+    def crash(string, exception)
+      string << "\n" << format_exception(exception)
+      error string
+
+      @exception_handlers.each do |handler|
+        begin
+          handler.call(exception)
+        rescue => ex
+          error "EXCEPTION HANDLER CRASHED:\n" << format_exception(ex)
+        end
+      end
+    end
+
+    # Format an exception message
+    def format_exception(exception)
+      str = "#{exception.class}: #{exception.to_s}\n"
+      str << exception.backtrace.join("\n")
+    end
+
+    # Define an exception handler
+    # NOTE: These should be defined at application start time
+    def exception_handler(&block)
+      @exception_handlers << block
+      nil
+    end
+  end
+end

data/lib/celluloid/mailbox.rb

@@ -0,0 +1,134 @@
+require 'thread'
+
+module Celluloid
+  class MailboxError < StandardError; end # you can't message the dead
+  class MailboxShutdown < StandardError; end # raised if the mailbox can no longer be used
+
+  # Actors communicate with asynchronous messages. Messages are buffered in
+  # Mailboxes until Actors can act upon them.
+  class Mailbox
+    include Enumerable
+
+    # A unique address at which this mailbox can be found
+    alias_method :address, :object_id
+
+    def initialize
+      @messages = []
+      @mutex = Mutex.new
+      @dead = false
+      @condition = ConditionVariable.new
+    end
+
+    # Add a message to the Mailbox
+    def <<(message)
+      @mutex.lock
+      begin
+        raise MailboxError, "dead recipient" if @dead
+
+        @messages << message
+        @condition.signal
+        nil
+      ensure
+        @mutex.unlock rescue nil
+      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
+
+      @mutex.lock
+      begin
+        raise MailboxError, "attempted to receive from a dead mailbox" if @dead
+
+        begin
+          message = next_message(&block)
+
+          unless message
+            if timeout
+              now = Time.now
+              wait_until ||= now + timeout
+              wait_interval = wait_until - now
+              return if wait_interval <= 0
+            else
+              wait_interval = nil
+            end
+
+            @condition.wait(@mutex, wait_interval)
+          end
+        end until message
+
+        message
+      ensure
+        @mutex.unlock rescue nil
+      end
+    end
+
+    # Retrieve the next message in the mailbox
+    def next_message
+      message = nil
+
+      if block_given?
+        index = @messages.index do |msg|
+          yield(msg) || msg.is_a?(SystemEvent)
+        end
+
+        message = @messages.slice!(index, 1).first if index
+      else
+        message = @messages.shift
+      end
+
+      raise message if message.is_a? SystemEvent
+      message
+    end
+
+    # Shut down this mailbox and clean up its contents
+    def shutdown
+      @mutex.lock
+      begin
+        messages = @messages
+        @messages = []
+        @dead = true
+      ensure
+        @mutex.unlock rescue nil
+      end
+
+      messages.each { |msg| msg.cleanup if msg.respond_to? :cleanup }
+      true
+    end
+
+    # Is the mailbox alive?
+    def alive?
+      !@dead
+    end
+
+    # Cast to an array
+    def to_a
+      @mutex.synchronize { @messages.dup }
+    end
+
+    # Iterate through the mailbox
+    def each(&block)
+      to_a.each(&block)
+    end
+
+    # Inspect the contents of the Mailbox
+    def inspect
+      "#<#{self.class}:#{object_id.to_s(16)} @messages=[#{map { |m| m.inspect }.join(', ')}]>"
+    end
+  end
+end