sevenscale-adhearsion 0.7.1003 → 0.8.0

data/lib/adhearsion/events_support.rb

@@ -1,259 +1,81 @@
-require 'thread'
+%w[theatre jicksta-theatre].each do |theatre_gem_name|
+  # Some older versions of the master branch required the theatre gem be installed. This is deprecation logic to inform the
+  # user to uninstall the gem if they happened to have used theatre in the past.
+  begin
+    gem theatre_gem_name
+  rescue LoadError
+    # Good. It should not be installed.
+  else
+    abort <<-MESSAGE
+It seems you have the "#{theatre_gem_name}" gem installed. As of Dec. 7th, 2008 Theatre has been rolled into Adhearsion
+and will be distributed with it.
+
+Please uninstall the gem by doing "sudo gem uninstall #{theatre_gem_name}".
+
+You will not need to install it again in the future. Sorry for the inconvenience.
+    MESSAGE
+  end
+end
+
+require 'theatre'
+
+
 module Adhearsion
   module Events
     
-    class << self
-      
-      def framework_events_container
-        defined?(@@framework_events_container) ? @@framework_events_container : reinitialize_framework_events_container!
-      end
-      
-      def load_definitions_from_files(*files)
-        files.each do |file|
-          framework_events_container.instance_eval File.read(file)
-        end
-      end
-      alias load_definitions_from_file load_definitions_from_files
-      
-      def namespace_registered?(*paths)
-        framework_events_container.namespace_registered?(*paths)
-      end
-      
-      def reinitialize_framework_events_container!
-        @@framework_events_container = EventsDefinitionContainer.new
-      end
-      
-      def register_namespace_path(*paths)
-        framework_events_container.register_namespace_path(*paths)
-      end
-      
-    end
+    DEFAULT_FRAMEWORK_EVENT_NAMESPACES = %w[
+      /after_initialized
+      /shutdown
+      /asterisk/manager_interface
+      /asterisk/before_call
+      /asterisk/after_call
+      /asterisk/hungup_call
+      /asterisk/failed_call
+    ]
     
-    class EventsDefinitionContainer
-
-      attr_reader :root
-      def initialize
-        @root = RootEventNamespace.new
-      end
-      
-      def register_namespace_path(*paths)
-        inject_across_path(*paths) do |namespace, path|
-          namespace.namespace_registered?(path) ? namespace[path] : namespace.register_namespace(path)
-        end
-      end
-      
-      def events
-        root.capturer
-      end
-      
-      def namespace_registered?(*paths)
-        !! inject_across_path(*paths) { |namespace,path| namespace[path] }
-      rescue UndefinedEventNamespace
-        false
-      end
-      
-      def callbacks_at_path(*paths)
-        inject_across_path(*paths) { |namespace,path| namespace[path] }.callbacks
-      end
-      
-      private
-      
-      def inject_across_path(*paths, &block)
-        paths.map(&:to_sym).inject(root, &block)
-      end
-    end
-    
-    class NamespaceDefinitionCapturer
-      
-      attr_reader :namespace
-      def initialize(namespace)
-        @namespace = namespace
-      end
-      
-      def method_missing(name, *args)
-        super if name == :each # Added to prevent confusion
-        nested_namespace_or_registrar = namespace[name.to_sym]
-        raise UndefinedEventNamespace.new(name) unless nested_namespace_or_registrar
-        case nested_namespace_or_registrar
-          when EventCallbackRegistrar
-            nested_namespace_or_registrar
-          when RegisteredEventNamespace
-            nested_namespace_or_registrar.capturer
-        end
-      end
-    end
-    
-    class UndefinedEventNamespace < Exception
-      def initialize(name)
-        super "Undefined namespace '#{name}'"
-      end
-    end
-    
-    class AbstractEventNamespace
-      
-      attr_reader :children
-      def initialize
-        @children = {}
-      end
-      
-      def [](namespace_name)
-        raise UndefinedEventNamespace.new(namespace_name) unless namespace_registered? namespace_name
-        children[namespace_name]
-      end
-      
-      def namespace_registered?(namespace_name)
-        children.has_key?(namespace_name)
-      end
-      
-      def register_namespace(namespace)
-        children[namespace] = RegisteredEventNamespace.new(self)
-      end
-      
-      def root?
-        false
-      end
-      
-      def capturer
-        @capturer ||= NamespaceDefinitionCapturer.new(self)
-      end
-      
-    end
-
-    class RootEventNamespace < AbstractEventNamespace
-      
-      def parent
-        nil
-      end
-      
-      def root?
-        true
-      end
-    end
-    
-    class RegisteredEventNamespace < AbstractEventNamespace
-      attr_reader :parent
-      def initialize(parent)
-        super()
-        @parent = parent
-      end
-      
-      def register_callback_name(name, mode=:sync, &block)
-        children[name] = case mode
-          when :sync  then  SynchronousEventCallbackRegistrar
-          when :async then AsynchronousEventCallbackRegistrar
-          else
-            raise ArgumentError, "Unsupported mode #{mode.inspect} !"
-        end.new(self, &block)
-      end
-      
-    end
-
-    class EventCallbackRegistrar
-      
-      attr_reader   :namespace, :callbacks
-      attr_accessor :notified_on_new_callback
-      
-      
-      def initialize(namespace, &notified_on_new_callback)
-        @namespace = namespace
-        @callbacks = []
-        @mutex     = Mutex.new
-        @notified_on_new_callback = notified_on_new_callback
-      end
-      
-      # This is effectively called when you define a new callback with each()
-      def register_callback(&block)
-        returning RegisteredEventCallback.new(self, &block) do |callback|
-          with_lock { callbacks << callback }
-          notified_on_new_callback.call callback if notified_on_new_callback
-        end
-      end
-      alias each register_callback
+    class << self
       
-      def <<(message)
-        raise NotImplementedError
+      def framework_theatre
+        defined?(@@framework_theatre) ? @@framework_theatre : reinitialize_theatre!
       end
       
-      def remove_callback(callback)
-        with_lock { callbacks.delete callback }
+      def trigger(*args)
+        framework_theatre.trigger(*args)
       end
       
-      protected
-      
-      def with_lock(&block)
-        @mutex.synchronize(&block)
+      def trigger_immediately(*args)
+        framework_theatre.trigger_immediately(*args)
       end
       
-      def threadsafe_callback_collection
-        with_lock { callbacks.clone }
-      end
-            
-    end
-    
-    class SynchronousEventCallbackRegistrar < EventCallbackRegistrar
-      def <<(event)
-        threadsafe_callback_collection.each do |callback|
-          callback.run_with_event event
+      def reinitialize_theatre!
+        @@framework_theatre.gracefully_stop! if defined? @@framework_theatre
+      rescue
+        # Recover and reinitalize
+      ensure
+        # TODO: Extract number of threads to use from AHN_CONFIG
+        @@framework_theatre = Theatre::Theatre.new
+        DEFAULT_FRAMEWORK_EVENT_NAMESPACES.each do |namespace|
+          register_namespace_name namespace
         end
+        return @@framework_theatre
       end
-    end
-    
-    class AsynchronousEventCallbackRegistrar < EventCallbackRegistrar
       
-      attr_reader :thread
-      def initialize(namespace, &notified_on_new_callback)
-        super
-        @thread = AsynchronousEventCallbackRegistrar.new
+      def register_namespace_name(name)
+        framework_theatre.register_namespace_name name
       end
       
-      def <<(event)
-        threadsafe_callback_collection.each do |callback|
-          
-        end
+      def stop!
+        Events.trigger :shutdown
+        framework_theatre.graceful_stop!
+        framework_theatre.join
       end
       
-      protected
-      
-      attr_reader :queue
-      
-      class AsynchronousEventHandlerThread < Thread
-        
-        def initialize(&block)
-          @queue = Queue.new
-          super do
-            loop { block.call @queue.pop }
-          end
-        end
-        
-        def <<(event)
-          @queue << event
-        end
+      def register_callback(namespace, block_arg=nil, &method_block)
+        raise ArgumentError, "Cannot supply two blocks!" if block_arg && block_given?
+        block = method_block || block_arg
+        raise ArgumentError, "Must supply a callback!" unless block
         
-      end
-      
-    end
-    
-    # A RegisteredEventCallback is stored away each time you call each() on an event namespace.
-    # It keeps a copy of the namespace 
-    class RegisteredEventCallback
-      
-      attr_reader :registrar, :args, :block
-      def initialize(registrar, *args, &block)
-        raise ArgumentError, "Must supply a callback in the form of a block!" unless block_given?
-        @registrar, @args, @block = registrar, args, block
-      end
-      
-      def run_with_event(event)
-        begin
-          block.call event
-        rescue => e
-          indenter = "\n" + (" " * 5)
-          ahn_log.events.error e.message + indenter + e.backtrace.join(indenter)
-        end
-      end
-      
-      def namespace
-        registrar.namespace
+        framework_theatre.register_callback_at_namespace(namespace, block)
       end
       
     end

data/lib/adhearsion/foundation/event_socket.rb

@@ -0,0 +1,203 @@
+##
+# EventSocket is a small abstraction of TCPSocket which causes it to behave much like an EventMachine Connection object for
+# the sake of better testability. The EventMachine Connection paradigm (as well as other networking libraries such as the 
+# Objective-C HTTP library) uses callbacks to signal different stages of a socket's lifecycle. 
+#
+# A handler can be registered in one of two ways: through registrations on an object yielded by the constructor or 
+# pre-defined on the object given as a constructor parameter. Below is an example definition which uses the block way:
+#
+#   EventSocket.new do |handler|
+#     def handler.receive_data(data)
+#       # Do something here
+#     end
+#     def handler.disconnected
+#       # Do something here
+#     end
+#     def handler.connected
+#       # Do something here
+#     end
+#   end
+#
+# Note: this is also a valid way of defining block callbacks:
+#
+#   EventSocket.new do |handler|
+#     handler.receive_data { |data| do_something }
+#     handler.disconnected { do_something }
+#     handler.connected    { do_something }
+#   end
+#
+# and here is an example of using a handler object:
+#
+#   class MyCallbackHandler
+#     def receive_data(data) end
+#     def connected() end
+#     def disconnected() end
+#   end
+#   EventSocket.new(MyCallbackHandler.new)
+#
+# If you wish to ask the EventSocket what state it is in, you can call the Thread-safe EventSocket#state method. The 
+# supported states are:
+#
+#  - :new
+#  - :connected
+#  - :stopped
+#  - :connection_dropped
+#
+# Note: the EventSocket's state will be changed before these callbacks are executed. For example, if your "connected" 
+# callback queried its own EventSocket for its state, it will have already transitioned to the connected() state.
+#
+# Warning: If an exception occurs in your EventSocket callbacks, they will be "eaten" and never bubbled up the call stack. 
+# You should always wrap your callbacks in a begin/rescue clause and handle exceptions explicitly.
+#
+require "thread"
+require "socket"
+
+class EventSocket
+
+  class << self
+    
+    ##
+    # Creates and returns a connected EventSocket instance.
+    #
+    def connect(*args, &block)
+      instance = new(*args, &block)
+      instance.connect!
+      instance
+    end
+  end
+
+  MAX_CHUNK_SIZE = 256 * 1024
+  
+  def initialize(host, port, handler=nil, &block)
+    raise ArgumentError, "Cannot supply both a handler object and a block" if handler && block_given?
+    raise ArgumentError, "Must supply either a handler object or a block" if !handler && !block_given?
+    
+    @state_lock = Mutex.new
+    @host  = host
+    @port  = port
+    
+    @state = :new
+    @handler = handler || new_handler_from_block(&block)
+  end
+  
+  def state
+    @state_lock.synchronize { @state }
+  end
+  
+  def connect!
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        raise ConnectionError, "Already connected!"
+      else
+        @socket = TCPSocket.new(@host, @port)
+        @state  = :connected
+      end
+    end
+    @handler.connected rescue nil
+    @reader_thread = spawn_reader_thread
+    self
+  rescue => error
+    @state = :failed
+    raise error
+  end
+  
+  ##
+  # Thread-safe implementation of write.
+  #
+  # @param [String] data Data to write
+  #
+  def send_data(data)
+    # Note: TCPSocket#write is intrinsically Thread-safe
+    @socket.write data
+  rescue
+    connection_dropped!
+  end
+    ##
+  # Disconnects this EventSocket and sets the state to :stopped
+  #
+  def disconnect!
+    @state_lock.synchronize do
+      @socket.close rescue nil
+      @state = :stopped
+    end
+  end
+  
+  ##
+  # Joins the Thread which reads data off the socket.
+  #
+  def join
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        @reader_thread.join
+      else
+        nil
+      end
+    end
+  end
+  
+  def receive_data(data)
+    @handler.receive_data(data)
+  end
+  
+  protected
+  
+  def connection_dropped!
+    @state_lock.synchronize do
+      unless @state.equal? :connection_dropped
+        @state = :connection_dropped
+        @handler.disconnected
+      end
+    end
+  end
+  
+  def spawn_reader_thread
+    Thread.new(&method(:reader_loop))
+  end
+  
+  def reader_loop
+    until state.equal? :stopped
+      data = @socket.readpartial(MAX_CHUNK_SIZE)
+      @handler.receive_data data
+    end
+  rescue EOFError
+    connection_dropped!
+  end
+
+  def new_handler_from_block(&handler_block)
+    handler = Object.new
+    handler.metaclass.send :attr_accessor, :set_callbacks
+    handler.set_callbacks = {:receive_data => false, :disconnected => false, :connected => false }
+    
+    def handler.receive_data(&block)
+      self.metaclass.send(:remove_method, :receive_data)
+      self.metaclass.send(:define_method, :receive_data) { |data| block.call data }
+      set_callbacks[:receive_data] = true
+    end
+    def handler.connected(&block)
+      self.metaclass.send(:remove_method, :connected)
+      self.metaclass.send(:define_method, :connected) { block.call }
+      set_callbacks[:connected] = true
+    end
+    def handler.disconnected(&block)
+      self.metaclass.send(:remove_method, :disconnected)
+      self.metaclass.send(:define_method, :disconnected) { block.call }
+      set_callbacks[:disconnected] = true
+    end
+    
+    def handler.singleton_method_added(name)
+      set_callbacks[name.to_sym] = true
+    end
+    
+    yield handler
+    
+    handler.set_callbacks.each_pair do |callback_name,was_set|
+      handler.send(callback_name) {} unless was_set
+    end
+    
+    handler
+    
+  end
+
+  class ConnectionError < Exception; end
+  
+end

data/lib/adhearsion/foundation/future_resource.rb

@@ -0,0 +1,36 @@
+require "thread"
+
+class FutureResource
+  
+  def initialize
+    @resource_lock          = Monitor.new
+    @resource_value_blocker = @resource_lock.new_cond
+  end
+  
+  def set_yet?
+    @resource_lock.synchronize { defined? @resource }
+  end
+  
+  def resource
+    @resource_lock.synchronize do
+      @resource_value_blocker.wait unless defined? @resource
+      @resource
+    end
+  end
+  
+  def resource=(resource)
+    @resource_lock.synchronize do
+      raise ResourceAlreadySetException if defined? @resource
+      @resource = resource
+      @resource_value_blocker.broadcast
+      @resource_value_blocker = nil # Don't really need it anymore.
+    end
+  end
+  
+  class ResourceAlreadySetException < Exception
+    def initialize
+      super "Cannot set this resource twice!"
+    end
+  end
+  
+end

data/lib/adhearsion/foundation/numeric.rb

@@ -0,0 +1,13 @@
+class Numeric
+  
+  def digit()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+  def digits()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+end

data/lib/adhearsion/foundation/pseudo_guid.rb

@@ -0,0 +1,10 @@
+module PseudoGuidGenerator
+  ##
+  # Generates a new 128-bit Globally Unique Identifier. It is a "pseudo" in that it does not adhere to the RFC which mandates
+  # that a certain section be reserved for a fragment of the NIC MAC address.
+  def new_guid(separator="-")
+    [8,4,4,4,12].map { |segment_length| String.random(segment_length) }.join(separator)
+  end
+end
+
+include PseudoGuidGenerator

data/lib/adhearsion/{core_extensions → foundation}/relationship_properties.rb

@@ -1,5 +1,6 @@
 class Module
   
+  ##
   # In OOP, relationships between classes should be treated as *properties* of those classes. Often, in a complex OO 
   # architecture, you'll end up with many relationships that intermingle in monolithic ways, blunting the effectiveness of
   # subclassing.
@@ -31,6 +32,7 @@ class Module
   # class HybridAutomobile < Automobile
   #   relationship :battery => HybridBattery
   # end
+  #
   def relationships(relationship_mapping)
     relationship_mapping.each_pair do |class_name, class_object|
       define_method(class_name) { class_object } 

data/lib/adhearsion/foundation/string.rb

@@ -0,0 +1,26 @@
+class String
+  
+  def unindent
+    gsub(/^\s*/,'')
+  end
+  
+  def unindent!
+    gsub!(/^\s*/,'')
+  end
+  
+  def self.random_char
+    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 self.random(length_of_string=8)
+    Array.new(length_of_string) { random_char }.join
+  end
+  
+  def nameify() downcase.gsub(/[^\w]/, '') end
+  def nameify!() replace nameify end
+    
+end