theatre 0.8.0

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2008 Jay Phillips
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,64 @@
+Theatre
+=======
+
+Present status: **Release candidate**
+
+A library for choreographing a dynamic pool of hierarchically organized actors. This was originally extracted from the [Adhearsion](http://adhearsion.com) framework by Jay Phillips.
+
+In the Adhearsion framework, it was necessary to develop an internal message-passing system that could work either synchronously or asynchronously. This is used by the framework itself and for framework extensions (called _components_) to talk with each other. The source of the events is completely undefined -- events could originate from within the framework out outside the framework. For example, a Message Queue such as [Stomp](http://stomp.codehaus.org) can wire incoming events into Theatre and catch events going to a particular destination so it can proxy them out to the server.
+
+Motivations and Design Decisions
+--------------------------------
+
+* Must maintain Ruby 1.8 and JRuby compatibility
+* Must be Thread-safe
+* Must provide some level of transparency into the events going through it
+* Must be dynamic enough to reallocate the number of triggerrs based on load
+* Must help facilitate test-driven development of Actor functionality
+* Must allow external persistence in case of a crash
+
+Example
+-------
+
+Below is an example taken from Adhearsion for executing framework-level callbacks. Note: the framework treats this callback synchronously.
+
+    events.framework.asterisk.before_call.each do |event|
+      # Pull headers from event and respond to it here.
+    end
+
+Below is an example of integration with [Stomp](http://stomp.codehaus.org/), a simple yet robust open-protocol message queue.
+
+    events.stomp.new_call.each do |event|
+      # Handle all events from the Stomp MQ server whose name is "new_call" (the String)
+    end
+
+This will filter all events whose name is "new_call" and yield the Stomp::Message to the block.
+
+Framework terminology
+--------------------
+
+Below are definitions of terms I use in Theatre. See the respective links for more information.
+
+* **callback**: This is the block given to the `each` method which triggers events coming in.
+* **payload**: This is the "message" sent to the Theatre and is what will ultimately be yielded to the callback
+* **[Actor](http://en.wikipedia.org/wiki/Actor_model)**: This refers to concurrent responders to events in a concurrent system.
+
+Synchronous vs. Asynchronous
+----------------------------
+
+With Theatre, all events are asynchronous with the optional ability to synchronously block until the event is scheduled, triggered, and has returned. If you wish to synchronously trigger the event, simple call `wait` on an `Invocation` object returned from `trigger` and then check the `Invocation#current_state` property for `:success` or `:error`. Optionally the `Invocation#success?` and `Invocation#error?` methods also provide more intuitive access to the finished state. If the event finished with `:success`, you may retrieve the returned value of the event Proc by calling `Invocation#returned_value`. If the event finished with `:error`, you may get the Exception with `Invocation#error`.
+
+Because many callbacks can be registered for a particular namespace, each needing its own Invocation object, the `Theatre#trigger` method returns an Array of Invocation objects.
+
+    # We'll assume only one callback is registered and call #first on the Array of Invocations returned by #trigger
+    invocation = my_theatre.trigger("your/namespace/here", YourSpecialClass.new("this can be anything")).first
+    invocation.wait
+    raise invocation.error if invocation.error?
+    log "Actor finished with return value #{invocation.returned_value}"
+
+Ruby 1.8 vs. Ruby 1.9 vs. JRuby
+-------------------------------
+
+Theatre was created for Ruby 1.8 because no good Actor system existed on Ruby 1.8 that met Adhearsion's needs (e.g. hierarchal with synchronous and asynchronous modes. If you wish to achieve real processor-level concurrency, use JRuby.
+
+Presently Ruby 1.9 compatibility is not a priority but patches for compatibility will be accepted, as long as they preserve compatibility with both MRI and JRuby.

data/Rakefile

@@ -0,0 +1,67 @@
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ['lib/**/*.rb'] + %w[README.markdown TODO.markdown LICENSE]
+  end
+rescue LoadError
+  STDERR.puts "\nCould not require() YARD! Install with 'gem install yard' to get the 'yardoc' task\n\n"
+end
+
+require 'rake/gempackagetask'
+require 'rubygems'
+require 'spec/rake/spectask'
+
+SPEC_GLOB = 'spec/**/*_spec.rb'
+GEMSPEC   = eval File.read("theatre.gemspec")
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.test_files = Dir[*SPEC_GLOB]
+    t.output_dir = 'coverage'
+    t.verbose = true
+    t.rcov_opts.concat %w[--sort coverage --sort-reverse -x gems -x /var --no-validator-links]
+  end
+rescue LoadError
+  STDERR.puts "Could not load rcov tasks -- rcov does not appear to be installed. Continuing anyway."
+end
+
+Rake::GemPackageTask.new(GEMSPEC).define
+
+desc "Run all RSpecs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList[SPEC_GLOB]
+end
+
+desc "Compares Theatre's files with those listed in theatre.gemspec"
+task :check_gemspec_files do
+  
+  files_from_gemspec    = THEATRE_FILES
+  files_from_filesystem = Dir.glob(File.dirname(__FILE__) + "/**/*").map do |filename|
+    filename[0...Dir.pwd.length] == Dir.pwd ? filename[(Dir.pwd.length+1)..-1] : filename
+  end.sort
+  files_from_filesystem.reject! { |f| File.directory? f }
+  
+  puts
+  puts 'Pipe this command to "grep -v \'spec/\'" to ignore spec files'
+  puts
+  puts '##########################################'
+  puts '## Files on filesystem not in the gemspec:'
+  puts '##########################################'
+  puts((files_from_filesystem - files_from_gemspec).map { |f| "  " + f })
+  
+  
+  puts '##########################################'
+  puts '## Files in gemspec not in the filesystem:'
+  puts '##########################################'
+  puts((files_from_gemspec - files_from_filesystem).map { |f| "  " + f })
+end
+
+desc "Test that the .gemspec file executes"
+task :debug_gem do
+  require 'rubygems/specification'
+  gemspec = File.read('adhearsion.gemspec')
+  spec = nil
+  Thread.new { spec = eval("$SAFE = 3\n#{gemspec}") }.join
+  puts "SUCCESS: Gemspec runs at the $SAFE level 3."
+end

data/TODO.markdown

@@ -0,0 +1,18 @@
+Ideas for improvement
+=====================
+
+Want to contribute to Theatre? See if any of these features may interest you and improve the way you work with the library. If so, feel free to fork this project on Github and add it!
+
+Theatre-owned namespaces
+------------------------
+
+Theatre would register event callbacks within its own Theatre-specific namespace. When responding to these events, it could do something such as report the average runtime for a particular namespace or how long it's been since the Theatre started.
+
+Prioritized namespaces
+----------------------
+
+Certain events should be executed as fast as possible. For example, in Adhearsion, maybe `before_call` and `after_call` events should be prioritized over other events.
+
+Handling within the caller's Thread
+-----------------------------------
+When calling Theatre#trigger, maybe it'd make sense to have some events run within the caller's Thread instead of running it in another Thread. This should probably be split into a separate method called `trigger_syncrhonously` or something.

data/algorithms.markdown

@@ -0,0 +1,43 @@
+Formulas
+========
+
+This is a work-in-progress document covering the mathematical algorithms behind Theatre.
+
+Running average without history
+-------------------------------
+
+In our system, we're either given or can calculate for the following information. When I say "number", in this case I mean "a stored time in seconds it took to execute a callback."
+
+    current_average = current average of all numbers in data set
+              count = quantity of data items in current_average's data set
+    reduced_average = current average adjusted for one more number to be added to the data set
+               data = new item for the dataset
+        new_average = new average of all numbers in data set, including "data"
+
+
+      count / (count+1) = current_average / reduced_average
+    ∴   reduced_average = (current_average * (count + 1)) / count
+    
+            new_average = reduced_average + (data / (count + 1))
+        
+
+Accounting for variations
+-------------------------
+
+Two things can happen which would make the system have an inappropriate number of responders:
+
+* Spikes or sudden drops in traffic
+* A singularity input to a callback which causes it to take a uniquely long time to execute
+
+If only a "running average" algorithm is used to track average callback time, the system will respond to variations in throughput less effectively the longer the system runs. The solution is to calculate several running times.
+
+For these reasons, the system should allow the user to specify sampling times and accuracy rates. Some systems may
+
+Erlang B/C calculations
+-----------------------
+
+With Agner Erlang's formulas, we calculate the appropriate number of responders to a given throughput of actions. For his formulas, we must know the following information:
+
+* What is the average runtime of each callback?
+* How many callbacks do we execute per hour?
+* What is an acceptable amount of wait time?

data/benchmark/growing_usage.rb

@@ -0,0 +1,46 @@
+# Adds messages to the Theatre with growing intensity
+
+require File.dirname(__FILE__) + "/../lib/theatre.rb"
+
+theatre = Theatre.new
+
+# TODO: Register namespaces here
+
+
+# As the current time diverges from the start time, enqueue more messages per second
+start_time  = Time.now
+
+# This is a function of the number of seconds that have passed since starting. For example, at 10 seconds into the demo,
+# we'll be pushing in 13 messages per second. At 100 seconds (1 minute, 40 seconds), we'll be doing 130 messages per second.
+growth_rate = 1.3
+
+# We need to keep a running count of how long it takes to actually dispatch a payload into the theatre.
+trigger_count = 0
+average_time = 0
+
+loop do
+  
+  seconds_since_start = (Time.now - start_time).to_i
+  times_per_second = (time_since_start * growth_rate).to_i
+
+  times_per_second.times do
+  
+    before_handling = Time.now
+    theatre.trigger "/my/special/namespace", :payload
+    after_handling = Time.now
+    
+    trigger_times.push after_handling - before_handling
+    
+    # Update the running average
+    #   count / (count+1) = current_average / reduced_average
+    # ∴   reduced_average = (current_average * (count + 1)) / count
+    # 
+    #         new_average = reduced_average + (data / (count + 1))
+    
+    trigger_count / (trigger_count + 1)
+
+    sleep average_time
+  
+  end
+  
+end

data/lib/theatre.rb

@@ -0,0 +1,144 @@
+require 'thread'
+require 'rubygems'
+
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'theatre/version'
+require 'theatre/namespace_manager'
+require 'theatre/invocation'
+require 'theatre/dsl/callback_definition_loader'
+
+module Theatre
+  
+  class Theatre
+    
+    attr_reader :namespace_manager
+    
+    ##
+    # Creates a new stopped Theatre. You must call start!() after you instantiate this for it to begin processing events.
+    #
+    # @param [Fixnum] thread_count Number of Threads to spawn when started.
+    #
+    def initialize(thread_count=6)
+      @thread_count      = thread_count
+      @started           = false
+      @namespace_manager = ActorNamespaceManager.new
+      @thread_group      = ThreadGroup.new
+      @master_queue      = Queue.new
+    end
+    
+    ##
+    # Send a message to this Theatre for asynchronous processing.
+    #
+    # @param [String] namespace The namespace to which the payload should be sent
+    # @param [Object] payload The actual content to be sent to the callback. Optional.
+    # @return [Array<Theatre::Invocation>] An Array of Invocation objects
+    # @raise Theatre::NamespaceNotFound Raised when told to enqueue an unrecognized namespace
+    #
+    def trigger(namespace, payload=:argument_undefined)
+      @namespace_manager.callbacks_for_namespaces(namespace).map do |callback|
+        invocation = if payload.equal?(:argument_undefined)
+          Invocation.new(namespace, callback)
+        else
+          Invocation.new(namespace, callback, payload)
+        end
+        invocation.queued
+        @master_queue << invocation
+        invocation
+      end
+    end
+    
+    ##
+    # Send a message to this Theatre for synchronous processing. The execution of this will not go through this Theatre's
+    # Thread pool. If an error occurred in any of callbacks, the Exception object will be placed in the returned Array 
+    # instead for you to act upon.
+    #
+    # @param [String] namespace The namespace to which the payload should be sent
+    # @param [Object] payload The actual content to be sent to the callback. Optional.
+    # @return [Array] An Array containing each callback's return value (or Exception raised, if any) when given the payload
+    # @raise Theatre::NamespaceNotFound Raised when told to enqueue an unrecognized namespace
+    #
+    def trigger_immediately(namespace, payload=:argument_undefined)
+      @namespace_manager.callbacks_for_namespaces(namespace).map do |callback|
+        begin
+          invocation = if payload.equal?(:argument_undefined)
+            callback.call
+          else
+            callback.call payload
+          end
+        rescue => captured_error_to_be_returned
+          captured_error_to_be_returned
+        end
+      end
+    end
+    
+    def load_events_code(code, *args)
+      CallbackDefinitionLoader.new(self, *args).load_events_code(code)
+    end
+    
+    def load_events_file(file, *args)
+      CallbackDefinitionLoader.new(self, *args).load_events_file(file)
+    end
+    
+    def register_namespace_name(*args)
+      @namespace_manager.register_namespace_name(*args)
+    end
+    
+    def register_callback_at_namespace(*args)
+      @namespace_manager.register_callback_at_namespace(*args)
+    end
+    
+    def join
+      @thread_group.list.each do |thread|
+        begin
+          thread.join
+        rescue
+          # Ignore any exceptions
+        end
+      end
+    end
+    
+    ##
+    # Starts this Theatre.
+    #
+    # When this method is called, the Threads are spawned and begin pulling messages off this Theatre's master queue.
+    #
+    def start!
+      return false if @thread_group.list.any? # Already started
+      @started_time = Time.now
+      @thread_count.times do
+        @thread_group.add Thread.new(&method(:thread_loop))
+      end
+    end
+    
+    ##
+    # Notifies all Threads for this Theatre to stop by sending them special messages. Any messages which were queued and
+    # untriggered when this method is received will still be processed. Note: you may start this Theatre again later once it
+    # has been stopped.
+    #
+    def graceful_stop!
+      @thread_count.times { @master_queue << :THEATRE_SHUTDOWN! }
+      @started_time = nil
+    end
+    
+    protected
+    
+    # This will use the Adhearsion logger eventually.
+    def warn(exception)
+      # STDERR.puts exception.message, *exception.backtrace
+    end
+    
+    def thread_loop
+      loop do
+        begin
+          next_invocation = @master_queue.pop
+          return :stopped if next_invocation.equal? :THEATRE_SHUTDOWN!
+          next_invocation.start
+        rescue => error
+          warn error
+        end
+      end
+    end
+    
+  end
+end

data/lib/theatre/dsl/callback_definition_loader.rb

@@ -0,0 +1,83 @@
+module Theatre
+  
+  ##
+  # This class provides the a wrapper aroung which an events.rb file can be instance_eval'd.
+  #
+  class CallbackDefinitionLoader
+    
+    attr_reader :theatre, :root_name
+    def initialize(theatre, root_name=:events)
+      @theatre = theatre
+      @root_name = root_name
+      create_recorder_method root_name
+    end
+    
+    def anonymous_recorder
+      BlankSlateMessageRecorder.new(&method(:callback_registered))
+    end
+    
+    ##
+    # Parses the given Ruby source code file and returns this object.
+    #
+    # @param [String, File] file The filename or File object for the Ruby source code file to parse.
+    #
+    def load_events_file(file)
+      file = File.open(file) if file.kind_of? String
+      instance_eval file.read, file.path
+      self
+    end
+    
+    ##
+    # Parses the given Ruby source code and returns this object.
+    #
+    # NOTE: Only use this if you're generating the code yourself! If you're loading a file from the filesystem, you should
+    # use load_events_file() since load_events_file() will properly attribute errors in the code to the file from which the
+    # code was loaded.
+    #
+    # @param [String] code The Ruby source code to parse
+    #
+    def load_events_code(code)
+      instance_eval code
+      self
+    end
+    
+    protected
+    
+    ##
+    # Immediately register the namespace and callback with the Theatre instance given to the constructor. This method is only
+    # called when a new BlankSlateMessageRecorder is instantiated and receives #each().
+    #
+    def callback_registered(namespaces, callback)
+      # Get rid of all arguments passed to the namespaces. Will support arguments in the future.
+      namespaces = namespaces.map { |namespace| namespace.first }
+      
+      theatre.namespace_manager.register_callback_at_namespace namespaces, callback
+    end
+    
+    def create_recorder_method(record_method_name)
+      (class << self; self; end).send(:alias_method, record_method_name, :anonymous_recorder)
+    end
+    
+    class BlankSlateMessageRecorder
+      
+      (instance_methods - %w[__send__ __id__]).each { |m| undef_method m }
+      
+      def initialize(&notify_on_completion)
+        @notify_on_completion = notify_on_completion
+        @namespaces = []
+      end
+      
+      def method_missing(*method_name_and_args)
+        raise ArgumentError, "Supplying a block is not supported" if block_given?
+        @namespaces << method_name_and_args
+        self
+      end
+      
+      def each(&callback)
+        @notify_on_completion.call(@namespaces, callback)
+      end
+      
+    end
+    
+  end
+end

data/lib/theatre/guid.rb

@@ -0,0 +1,23 @@
+# Right now Adhearsion also defines this method. The eventual solution will be to extract the Adhearsion features on which
+# Theatre depends and make that a dependent library.
+
+unless respond_to? :new_guid
+  
+  def random_character
+    case random_digit = rand(62)
+      when  0...10 : random_digit.to_s
+      when 10...36 : (random_digit + 55).chr
+      when 36...62 : (random_digit + 61).chr
+    end
+  end
+  
+  def random_string(length_of_string=8)
+    Array.new(length_of_string) { random_character }.join
+  end
+  
+  # This GUID implementation doesn't adhere to the RFC which wants to make certain segments based on the MAC address of a
+  # network interface card and other wackiness. It's sufficiently random for our needs.
+  def new_guid
+    [8,4,4,4,12].map { |segment_length| random_string(segment_length) }.join('-')
+  end
+end

data/lib/theatre/invocation.rb

@@ -0,0 +1,121 @@
+require 'theatre/guid'
+require 'thread'
+require 'monitor'
+
+module Theatre
+  
+  ##
+  # An Invocation is an object which Theatre generates and returns from Theatre#trigger.
+  #
+  class Invocation
+    
+    attr_reader :queued_time, :started_time, :finished_time, :unique_id, :callback, :namespace, :error, :returned_value
+    
+    class InvalidStateError < Exception; end
+    
+    ##
+    # Create a new Invocation.
+    #
+    # @param [String] namespace The "/foo/bar/qaz" path to the namespace to which this Invocation belongs.
+    # @param [Proc] callback The block which should be executed by an Actor scheduler.
+    # @param [Object] payload The message that will be sent to the callback for processing.
+    #
+    def initialize(namespace, callback, payload=:theatre_no_payload)
+      raise ArgumentError, "Callback must be a Proc" unless callback.kind_of? Proc
+      @payload       = payload
+      @unique_id     = new_guid.freeze
+      @callback      = callback
+      @current_state = :new
+      @state_lock    = Mutex.new
+      
+      # Used just to protect access to the @returned_value instance variable
+      @returned_value_lock = Monitor.new
+      
+      # Used when wait() is called to notify all waiting threads by using a ConditionVariable
+      @returned_value_blocker = Monitor::ConditionVariable.new @returned_value_lock
+    end
+    
+    def queued
+      with_state_lock do
+        raise InvalidStateError unless @current_state == :new
+        @current_state = :queued
+        @queued_time = Time.now.freeze
+      end
+      true
+    end
+    
+    def current_state
+      with_state_lock { @current_state }
+    end
+    
+    def start
+      with_state_lock do
+        raise InvalidStateError unless @current_state == :queued
+        @current_state = :running
+      end
+      @started_time = Time.now.freeze
+      
+      begin
+        self.returned_value = if @payload.equal? :theatre_no_payload
+          @callback.call
+        else
+          @callback.call @payload
+        end
+        with_state_lock { @current_state = :success }
+      rescue => @error
+        with_state_lock { @current_state = :error }
+      ensure
+        @finished_time = Time.now.freeze
+      end
+    end
+    
+    def execution_duration
+      return nil unless @finished_time
+      @finished_time - @started_time
+    end
+    
+    def error?
+      current_state.equal? :error
+    end
+    
+    def success?
+      current_state.equal? :success
+    end
+    
+    ##
+    # When this Invocation has been queued, started, and entered either the :success or :error state, this method will
+    # finally return. Until then, it blocks the Thread.
+    #
+    # @return [Object] The result of invoking this Invocation's callback
+    #
+    def wait
+      with_returned_value_lock { return @returned_value if defined? @returned_value }
+      @returned_value_blocker.wait
+      # Return the returned_value
+      with_returned_value_lock { @returned_value }
+    end
+    
+    protected
+    
+    ##
+    # Protected setter which does some other housework when the returned value is found (such as notifying wait()ers)
+    #
+    # @param [returned_value] The value to set this returned value to.
+    #
+    def returned_value=(returned_value)
+      with_returned_value_lock do
+        @returned_value = returned_value
+        @returned_value_blocker.broadcast
+      end
+    end
+    
+    def with_returned_value_lock(&block)
+      @returned_value_lock.synchronize(&block)
+    end
+    
+    def with_state_lock(&block)
+      @state_lock.synchronize(&block)
+    end
+    
+  end
+end

data/lib/theatre/namespace_manager.rb

@@ -0,0 +1,153 @@
+module Theatre
+  
+  ##
+  # Manages the hierarchial namespaces of a Theatre. This class is Thread-safe.
+  #
+  class ActorNamespaceManager
+
+    VALID_NAMESPACE = %r{^(/[\w_]+)+$}
+    
+    class << self
+      def valid_namespace_path?(namespace_path)
+        namespace_path =~ VALID_NAMESPACE
+      end
+      
+      ##
+      # Since there are a couple ways to represent namespaces, this is a helper method which will normalize
+      # them into the most practical: an Array of Symbols
+      # @param [String, Array] paths The namespace to register. Can be in "/foo/bar" or *[foo,bar] format
+      def normalize_path_to_array(paths)
+        paths = paths.is_a?(Array) ? paths.flatten : Array(paths)
+        paths.map! { |path_segment| path_segment.kind_of?(String) ? path_segment.split('/') : path_segment }
+        paths.flatten!
+        paths.reject! { |path| path.nil? || (path.kind_of?(String) && path.empty?) }
+        paths.map { |path| path.to_sym }
+      end
+
+    end
+    
+    def initialize
+      @registry_lock = Mutex.new
+      @root          = RootNamespaceNode.new
+    end
+    
+    ## 
+    # Have this registry recognize a new path and prepare it for callback registrations. All path segements will be created
+    # in order. For example, when registering "/foo/bar/qaz" when no namespaces at all have been registered, this method will
+    # first register "foo", then "bar", then "qaz". If the namespace was already registered, it will not be affected.
+    #
+    # @param [String, Array] paths The namespace to register. Can be in "/foo/bar" or *[foo,bar] format
+    # @return [NamespaceNode] The NamespaceNode representing the path given.
+    # @raise NamespaceNotFound if a segment has not been registered yet
+    #
+    def register_namespace_name(*paths)
+      paths = self.class.normalize_path_to_array paths
+      
+      paths.inject(@root) do |node, name|
+        node.register_namespace_name name
+      end
+    end
+    
+    ##
+    # Returns a Proc found after searching with the namespace you provide
+    #
+    # @raise NamespaceNotFound if a segment has not been registered yet
+    #
+    def callbacks_for_namespaces(*paths)
+      search_for_namespace(paths).callbacks
+    end
+    
+    ##
+    # Find a namespace in the tree.
+    #
+    # @param [Array, String] paths Must be an Array of segments or a name like "/foo/bar/qaz"
+    # @raise NamespaceNotFound if a segment has not been registered yet
+    #
+    def search_for_namespace(paths)
+      paths = self.class.normalize_path_to_array paths
+      path_string = "/"
+      
+      found_namespace = paths.inject(@root) do |last_node,this_node_name|
+        raise NamespaceNotFound.new(path_string) if last_node.nil?
+        path_string << this_node_name.to_s
+        last_node.child_named this_node_name
+      end
+      raise NamespaceNotFound.new("/#{paths.join('/')}") unless found_namespace
+      found_namespace
+    end
+    
+    ##
+    # Registers the given callback at a namespace, assuming the namespace was already registered.
+    #
+    # @param [Array] paths Must be an Array of segments
+    # @param [Proc] callback 
+    # @raise NamespaceNotFound if a segment has not been registered yet
+    #
+    def register_callback_at_namespace(paths, callback)
+      raise ArgumentError, "callback must be a Proc" unless callback.kind_of? Proc
+      search_for_namespace(paths).register_callback callback
+    end
+    
+    protected
+    
+    ##
+    # Used by NamespaceManager to build a tree of namespaces. Has a Hash of children which is not 
+    # Thread-safe. For Thread-safety, all access should semaphore through the NamespaceManager.
+    class NamespaceNode
+      
+      attr_reader :name
+      def initialize(name)
+        @name = name.freeze
+        @children  = {}
+        @callbacks = []
+      end
+      
+      def register_namespace_name(name)
+        @children[name] ||= NamespaceNode.new(name)
+      end
+      
+      def register_callback(callback)
+        @callbacks << callback
+        callback
+      end
+      
+      def callbacks
+        @callbacks.clone
+      end
+      
+      def delete_callback(callback)
+        @callbacks.delete callback
+      end
+      
+      def child_named(name)
+        @children[name]
+      end
+      
+      def destroy_namespace(name)
+        @children.delete name
+      end
+      
+      def root?
+        false
+      end
+      
+    end
+    
+    class RootNamespaceNode < NamespaceNode
+      def initialize
+        super :ROOT
+      end
+      def root?
+        true
+      end
+    end
+    
+  end
+  
+  class NamespaceNotFound < Exception
+    def initialize(full_path)
+      super "Could not find #{full_path.inspect} in the namespace registry. Did you register it yet?"
+    end
+  end
+  
+end

data/lib/theatre/version.rb

@@ -0,0 +1,2 @@
+THEATRE_VERSION_MAJOR, THEATRE_VERSION_MINOR, THEATRE_VERSION_REVISION = THEATRE_VERSION = [0,8,0]
+THEATRE_VERSION_STRING = THEATRE_VERSION.join '.'

data/theatre.gemspec

@@ -0,0 +1,41 @@
+THEATRE_FILES = %w[
+  MIT-LICENSE
+  README.markdown
+  Rakefile
+  TODO.markdown
+  algorithms.markdown
+  benchmark/growing_usage.rb
+  lib/theatre.rb
+  lib/theatre/dsl/callback_definition_loader.rb
+  lib/theatre/guid.rb
+  lib/theatre/invocation.rb
+  lib/theatre/namespace_manager.rb
+  lib/theatre/version.rb
+  theatre.gemspec
+]
+
+Gem::Specification.new do |s|
+  s.name    = "theatre"
+  s.version = "0.8.0"
+  
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :require_rubygems_version=
+  
+  s.authors = ["Jay Phillips"]
+  s.date = "2008-08-21"
+  
+  s.description = "A library for choreographing a dynamic pool of hierarchially organized actors on Ruby v1.8"
+  s.summary     = "A library for choreographing a dynamic pool of hierarchially organized actors on Ruby v1.8"
+  
+  s.email = "Jay -at- Codemecca.com"
+  
+  s.files = THEATRE_FILES
+  
+  s.has_rdoc = false
+  
+  s.rubyforge_project = "theatre"
+  s.homepage          = "http://github.com/jicksta/theatre"
+  
+  s.require_paths    = ["lib"]
+  s.rubygems_version = "1.2.0"
+  
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: theatre
+version: !ruby/object:Gem::Version 
+  version: 0.8.0
+platform: ruby
+authors: 
+- Jay Phillips
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-21 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A library for choreographing a dynamic pool of hierarchially organized actors on Ruby v1.8
+email: Jay -at- Codemecca.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- MIT-LICENSE
+- README.markdown
+- Rakefile
+- TODO.markdown
+- algorithms.markdown
+- benchmark/growing_usage.rb
+- lib/theatre.rb
+- lib/theatre/dsl/callback_definition_loader.rb
+- lib/theatre/guid.rb
+- lib/theatre/invocation.rb
+- lib/theatre/namespace_manager.rb
+- lib/theatre/version.rb
+- theatre.gemspec
+has_rdoc: false
+homepage: http://github.com/jicksta/theatre
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: theatre
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A library for choreographing a dynamic pool of hierarchially organized actors on Ruby v1.8
+test_files: []
+