tribe 0.4.0 → 0.6.0

data/Rakefile

@@ -1,14 +1,10 @@
 require "bundler/gem_tasks"
+require "rake/testtask"
 
-desc 'Start an IRB console with Workers loaded'
-task :console do
-  $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
-
-  require 'tribe'
-  require 'tribe/benchmark'
-  require 'irb'
-
-  ARGV.clear
-
-  IRB.start
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
 end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tribe"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tribe.rb

@@ -2,6 +2,7 @@ require 'set'
 
 require 'workers'
 
+require 'tribe/version'
 require 'tribe/safe_set'
 require 'tribe/exceptions'
 require 'tribe/event'
@@ -19,16 +20,7 @@ module Tribe
     return @registry ||= Tribe::Registry.new
   end
 
-  def self.registry=(val)
-    @registry.dispose if @registry
-    @registry = val
-  end
-
   def self.root
     @root ||= Tribe::Root.new(:name => 'root', :permit_root => true)
   end
 end
-
-# Force initialization.
-Tribe.registry
-Tribe.root

data/lib/tribe/actable.rb

@@ -16,16 +16,20 @@ module Tribe
       end
 
       @logger = Workers::LogProxy.new(options[:logger])
-      @_as = Tribe::ActorState.new
-      @_as.dedicated = options[:dedicated] || false
-      @_as.pool = @_as.dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
-      @_as.mailbox = Tribe::Mailbox.new(@_as.pool)
-      @_as.registry = options[:registry] || Tribe.registry
-      @_as.scheduler = options[:scheduler]
-      @_as.name = options[:name]
-      @_as.parent = options[:parent]
-
-      @_as.registry.register(self)
+      @_actable = Tribe::ActorState.new
+      @_actable.dedicated = options[:dedicated] || false
+      @_actable.pool = @_actable.dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
+      @_actable.mailbox = Tribe::Mailbox.new(@_actable.pool)
+      @_actable.registry = options[:registry] || Tribe.registry
+      @_actable.scheduler = options[:scheduler]
+      @_actable.name = options[:name]
+      @_actable.parent = options[:parent]
+      @_actable.children = Tribe::SafeSet.new
+      @_actable.supervisees = Tribe::SafeSet.new
+
+      @_actable.registry.register(self)
+
+      direct_message!(:__initialize__)
     end
 
     #
@@ -38,14 +42,14 @@ module Tribe
     public
 
     def deliver_event!(event)
-      @_as.mailbox.push(event) do
+      @_actable.mailbox.push(event) do
         process_events
       end
 
       return nil
     end
 
-    def deliver_message!(command, data = nil, src = nil)
+    def direct_message!(command, data = nil, src = nil)
       deliver_event!(Tribe::Event.new(command, data, src))
 
       return nil
@@ -69,17 +73,16 @@ module Tribe
     end
 
     def shutdown!
-      return deliver_message!(:_shutdown)
+      return direct_message!(:__shutdown__)
     end
 
     def perform!(&block)
-      return deliver_message!(:_perform, block)
+      return direct_message!(:__perform__, block)
     end
 
-    def spawn(klass, actor_options = {}, spawn_options = {})
+    def spawn!(klass, actor_options = {}, spawn_options = {})
       actor_options[:parent] = self
 
-      @_as.children ||= []
       child = nil
 
       if spawn_options[:no_raise_on_failure]
@@ -92,33 +95,117 @@ module Tribe
         child = klass.new(actor_options)
       end
 
-      @_as.children << child
+      @_actable.children.add(child)
+
+      if spawn_options[:supervise]
+        @_actable.supervisees.add(child)
+      end
 
       return child
     end
 
     def alive?
-      @_as.mailbox.alive?
+      @_actable.mailbox.alive?
+    end
+
+    def dead?
+      !alive?
     end
 
     def name
-      return @_as.name
+      return @_actable.name
     end
 
     def identifier
-      return @_as.name ? "#{object_id}:#{@_as.name}" : object_id
+      return @_actable.name ? "#{object_id}:#{@_actable.name}" : object_id
+    end
+
+    def exception
+      return @_actable.exception
+    end
+
+    def registry
+      return @_actable.registry
+    end
+
+    def pool
+      return @_actable.pool
     end
 
     #
-    # Private event handlers.
-    # Notes: These methods are designed to be overriden (make sure you call super).
+    # Private command handlers.
+    # Notes: These methods are designed to be overriden in order to respond to actor system events.
     #
 
     private
 
+    def on_initialize(event)
+    end
+
+    def on_exception(event)
+    end
+
+    def on_shutdown(event)
+    end
+
+    def on_child_died(event)
+    end
+
+    def on_child_shutdown(event)
+    end
+
+    def on_parent_died(event)
+    end
+
+    #
+    # Private event system methods.
+    # Notes: These methods are designed to be overriden by advanced users only.  Overriding is very rare!
+    #
+
+    private
+
+    # All system commands are prefixed with an underscore.
+    def process_events
+      while (event = @_actable.mailbox.obtain_and_shift)
+        event_handler(event)
+      end
+
+    rescue Exception => exception
+      cleanup_handler(exception)
+      exception_handler(exception)
+    ensure
+      @_actable.mailbox.release do
+        process_events
+      end
+
+      return nil
+    end
+
     def event_handler(event)
+      case event.command
+      when :__initialize__
+        initialize_handler(event)
+      when :__shutdown__
+        cleanup_handler
+        shutdown_handler(event)
+      when :__perform__
+        perform_handler(event)
+      when :__child_died__
+        child_died_handler(event.data[0], event.data[1])
+      when :__child_shutdown__
+        child_shutdown_handler(event.data)
+      when :__parent_died__
+        parent_died_handler(event.data[0], event.data[1])
+      when :initialize, :shutdown, :perform, :child_died, :child_shutdown, :parent_died
+        raise ActorReservedCommand.new("Reserved commands are not allowed (command=#{event.command}).")
+      else
+        custom_event_handler(event)
+      end
+    end
+
+    def custom_event_handler(event)
       result = nil
-      @_as.active_event = event
+      @_actable.active_event = event
 
       begin
         result = send("on_#{event.command}", event)
@@ -126,30 +213,44 @@ module Tribe
         result = e
         raise
       ensure
-        if event.future && @_as.active_event
+        if event.future && @_actable.active_event
           event.future.result = result
         end
-        @_as.active_event = nil
+        @_actable.active_event = nil
       end
 
       return nil
     end
 
+    def initialize_handler(event)
+      on_initialize(event)
+    end
+
     def exception_handler(exception)
-      if @_as.parent
-        @_as.parent.deliver_message!(:_child_died, [self, exception])
+      if @_actable.parent
+        @_actable.parent.direct_message!(:__child_died__, [self, exception])
       end
 
-      if @_as.children
-        @_as.children.each { |c| c.deliver_message!(:_parent_died, [self, exception]) }
-        @_as.children.clear
-        @_as.children = nil
-      end
+      @_actable.children.each { |c| c.direct_message!(:__parent_died__, [self, exception]) }
+      @_actable.children.clear
+      @_actable.supervisees.clear
+
+      on_exception(Event.new(:exception, {:exception => exception}))
 
       return nil
     end
 
     def shutdown_handler(event)
+      if @_actable.parent
+        @_actable.parent.direct_message!(:__child_shutdown__, self)
+      end
+
+      @_actable.children.each { |c| c.shutdown! }
+      @_actable.children.clear
+      @_actable.supervisees.clear
+
+      on_shutdown(Event.new(:shutdown, {}))
+
       return nil
     end
 
@@ -160,27 +261,42 @@ module Tribe
     end
 
     def cleanup_handler(exception = nil)
-      @_as.exception = exception
-      @_as.pool.shutdown if @_as.dedicated
-      @_as.mailbox.kill
-      @_as.registry.unregister(self)
-      @_as.timers.each { |t| t.cancel } if @_as.timers
-
-      if @_as.children && exception.nil?
-        @_as.children.each { |c| c.shutdown! }
-        @_as.children.clear
-        @_as.children = nil
-      end
+      @_actable.exception = exception
+      @_actable.pool.shutdown if @_actable.dedicated
+      @_actable.mailbox.kill
+      @_actable.registry.unregister(self)
+      @_actable.timers.each { |t| t.cancel } if @_actable.timers
 
       return nil
     end
 
     def child_died_handler(child, exception)
-      raise Tribe::ActorChildDied.new("#{child.identifier} died.")
+      @_actable.children.delete(child)
+      supervising = !!@_actable.supervisees.delete?(child)
+
+      on_child_died(Event.new(:child_died, {:child => child, :exception => exception}))
+
+      if !supervising
+        raise Tribe::ActorChildDied.new("#{child.identifier} died.")
+      end
+
+      return nil
+    end
+
+    def child_shutdown_handler(child)
+      @_actable.children.delete(child)
+      @_actable.supervisees.delete(child)
+
+      on_child_shutdown(Event.new(:child_shutdown, {:child => child}))
+
+      return nil
     end
 
     def parent_died_handler(parent, exception)
+      on_parent_died(Event.new(:parent_died, {:parent => parent, :exception => exception}))
       raise Tribe::ActorParentDied.new("#{parent.identifier} died.")
+
+      return nil
     end
 
     #
@@ -190,86 +306,66 @@ module Tribe
 
     private
 
-    def registry
-      return @_as.registry
-    end
-
-    def pool
-      return @_as.pool
-    end
-
-    def timer(delay, command, data = nil)
+    def timer!(delay, command, data = nil)
       # Lazy instantiation for performance.
-      @_as.scheduler ||= Workers.scheduler
-      @_as.timers ||= Tribe::SafeSet.new
+      @_actable.scheduler ||= Workers.scheduler
+      @_actable.timers ||= Tribe::SafeSet.new
 
-      timer = Workers::Timer.new(delay, :scheduler => @_as.scheduler) do
-        @_as.timers.delete(timer)
-        deliver_message!(command, data)
+      timer = Workers::Timer.new(delay, :scheduler => @_actable.scheduler) do
+        @_actable.timers.delete(timer)
+        direct_message!(command, data)
       end
 
-      @_as.timers.add(timer)
+      @_actable.timers.add(timer)
 
       return timer
     end
 
-    def periodic_timer(delay, command, data = nil)
+    def periodic_timer!(delay, command, data = nil)
       # Lazy instantiation for performance.
-      @_as.scheduler ||= Workers.scheduler
-      @_as.timers ||= Tribe::SafeSet.new
+      @_actable.scheduler ||= Workers.scheduler
+      @_actable.timers ||= Tribe::SafeSet.new
 
-      timer = Workers::PeriodicTimer.new(delay, :scheduler => @_as.scheduler) do
-        deliver_message!(command, data)
+      timer = Workers::PeriodicTimer.new(delay, :scheduler => @_actable.scheduler) do
+        direct_message!(command, data)
         unless alive?
-          @_as.timers.delete(timer)
+          @_actable.timers.delete(timer)
           timer.cancel
         end
       end
 
-      @_as.timers.add(timer)
+      @_actable.timers.add(timer)
 
       return timer
     end
 
-    #
-    # Private internal methods.
-    # Notes: These are used by the actor system and you should never call them directly.
-    #
-
     def forward!(dest)
-      dest.deliver_event!(@_as.active_event)
-      @_as.active_event = nil
+      dest.deliver_event!(@_actable.active_event)
+      @_actable.active_event = nil
 
       return nil
     end
 
-    # All system commands are prefixed with an underscore.
-    def process_events
-      while (event = @_as.mailbox.obtain_and_shift)
-        case event.command
-        when :_shutdown
-          cleanup_handler
-          shutdown_handler(event)
-        when :_perform
-          perform_handler(event)
-        when :_child_died
-          child_died_handler(event.data[0], event.data[1])
-        when :_parent_died
-          parent_died_handler(event.data[0], event.data[1])
-        else
-          event_handler(event)
+    # Wrap blocking code using this method to automatically expand/contract the pool.
+    # This way you avoid potential deadlock with blocking code.
+    # Not needed for dedicated actors since they already have their own thread.
+    def blocking!
+      if @_actable.dedicated
+        yield
+      else
+        pool.expand(1)
+        begin
+          yield
+        ensure
+          pool.contract(1)
         end
       end
+    end
 
-    rescue Exception => exception
-      cleanup_handler(exception)
-      exception_handler(exception)
-    ensure
-      @_as.mailbox.release do
-        process_events
+    def wait!(future)
+      blocking! do
+        future.wait
       end
-
-      return nil
     end
   end
 end