cosell 0.0.2

data/lib/cosell.rb

@@ -0,0 +1,48 @@
+module Cosell 
+
+  # :stopdoc:
+  VERSION = '0.0.2'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+  # :startdoc:
+
+end  # module Cosell
+
+Cosell.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/cosell/announcer.rb

@@ -0,0 +1,236 @@
+require 'logger'
+
+module Cosell
+
+    def initialize *args
+      initialize_cosell!
+      super
+    end
+
+    #
+    #
+    #           ANNOUNCEMENTS QUEUE
+    #
+    #
+
+    # Place all announcments in a queue, and make announcements in a background thread.
+    #
+    # Arguments:
+    #    :logger => a logger. Where to log exceptions and warnings.
+    #               This argument is mandatory -- it is too hard to debug exceptions in announcement 
+    #               handler code without a logger. If you _really_ want your code to fail silently, 
+    #               you will have to create a logger on /dev/null.
+    #    :sleep_time => how long to sleep (in seconds) after making a batch of announchements 
+    #                   optional arg, default: 0.01
+    #    :announcements_per_cycle => how many announcements to make before sleeping for sleep_time
+    #                   optional arg, default: 25
+    #
+    # WARNING: If you do not pass in a logger, announcement code will fail silently (the queue
+    # is in a background thread).
+    #
+    # Note: at the moment, this method may only be called once, and cannot be undone. There is
+    # no way to interrupt the thread.
+    
+    def queue_announcements!(opts = {})
+
+      self.initialize_cosell_if_needed
+
+      # The logger in mandatory
+      if opts[:logger]
+        self.queue_logger = opts[:logger]
+      else
+        raise "Cosell error: You have to provide a logger, otherwise failures in announcement handler code are to hard to debug"
+      end
+
+      # kill off the last queue first
+      if self.announcements_thread
+        kill_queue!
+        sleep 0.01
+        queue_announcements! opts
+      end
+
+      self.should_queue_announcements = true
+      @__announcements_queue ||= Queue.new
+
+      how_many_per_cycle = opts[:announcements_per_cycle] || 25
+      cycle_duration = opts[:sleep_time] || 0.01
+      count = 0
+
+      self.announcements_thread = Thread.new do 
+        loop do
+          if queue_killed?
+            self.kill_announcement_queue = false
+            self.announcements_thread = nil
+            log "Announcement queue killed with #{self.announcements_queue.size} announcements still queued", :info
+            break
+          else
+            begin
+              self.announce_now! self.announcements_queue.pop
+              count += 1
+              if (count%how_many_per_cycle).eql?(0)
+                log "Announcement queue finished batch of #{how_many_per_cycle}, sleeping for #{cycle_duration} sec", :debug
+                count = 0
+                sleep cycle_duration
+              end
+            rescue Exception => x
+              log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error
+            end
+          end
+        end
+      end
+
+    end
+
+    #
+    #
+    #           SUBSCRIBE/MAKE ANNOUNCEMENTS 
+    #
+    #
+
+    # Pass in an anouncement class (or array of announcement classes), along with a block defining the 
+    # action to be taken when an announcment of one of the specified classes is announced by this announcer.
+    # (see Cossell::Announcer for full explanation)
+    def subscribe *announce_classes, &block
+
+      self.initialize_cosell_if_needed
+
+      Array(announce_classes).each do |announce_class|
+        raise "Can only subscribe to classes. Not a class: #{announce_class}" unless announce_class.is_a?(Class)
+        self.subscriptions[announce_class] ||= []
+        self.subscriptions[announce_class] << lambda(&block)
+      end
+    end
+    alias_method :when_announcing, :subscribe
+
+    # Stop announcing for a given announcement class (or array of classes)
+    def unsubscribe *announce_classes
+      Array(announce_classes).each do |announce_class|
+        self.subscriptions.delete announce_class
+      end
+    end
+
+    # If queue_announcements? true, puts announcement in a Queue.
+    # Otherwise, calls announce_now!
+    # Queued announcements are announced in a background thread in batches 
+    # (see the #initialize method doc for details).
+    def announce announcement
+      if self.queue_announcements?
+        self.announcements_queue << announcement
+      else
+        self.announce_now! announcement
+      end
+    end
+
+    #
+    # First, an announcement is made by calling 'as_announcement' on an_announcement_or_announcement_factory,
+    # and subscribers to the announcement's class are then notified
+    #
+    # subscribers to this announcer will be filtered to those that match to the announcement's class,
+    # and those subscriptions will be 'fired'. Subscribers should use the 'subscribe' method (also
+    # called 'when_announcing') to configure actions to take when a given announcement is made.
+    #
+    # Typically, an announcement is passed in for an_announcement_factory, in
+    # which case as_announcement does nothing but return the announcement. But any class can override
+    # as_announcement to adapt into an anouncement as they see fit.
+    #
+    # (see Cossell::Announcer for full explanation)
+    #
+    def announce_now! an_announcement_or_announcement_factory
+      announcement = an_announcement_or_announcement_factory.as_announcement
+
+      self.subscriptions.each do |subscription_type, subscriptions_for_type |
+        if announcement.is_a?(subscription_type)
+          subscriptions_for_type.each{|subscription| subscription.call(announcement) }
+        end
+      end
+
+      return announcement 
+    end
+
+    #
+    #
+    #           DEBUG
+    #
+    #
+
+    # 
+    # Log a message every time this announcer makes an announcement
+    #
+    # Options:
+    #    :on => Which class of announcements to spy on. Default is Object (ie. all announcements)
+    #    :logger => The log to log to. Default is a logger on STDOUT
+    #    :level => The log level to log with. Default is :info
+    #    :preface_with => A message to prepend to all log messages. Default is "Announcement Spy: "
+    def spy!(opts = {})
+      on = opts[:on] || Object
+      logger = opts[:logger] || Logger.new(STDOUT)
+      level = opts[:level] || :info
+      preface = opts[:preface_with] || "Announcement Spy: "
+      self.subscribe(on){|ann| logger.send(level, "#{preface} #{ann.as_announcement_trace}")}
+    end
+
+    # lazy initialization of cosell.
+    # Optional -- calling this will get rid of any subsequent warnings about uninitialized ivs
+    # In most cases not necessary, and should never have an effect except to get rid of some warnings.
+    def initialize_cosell_if_needed
+      self.initialize_cosell! if @__subscriptions.nil? 
+    end
+
+    # Will blow away any queue, and reset all state.
+    # Should not be necessary to call this, but left public for testing.
+    def initialize_cosell!
+      # Using pseudo-scoped var names. 
+      # Unfortunately cant lazily init these w/out ruby warnings going berzerk in verbose mode,
+      # So explicitly declaring them here.
+      @__queue_announcements ||= false
+      @__announcements_queue ||= nil
+      @__kill_announcement_queue ||= false
+      @__announcements_thread ||= nil
+      @__subscriptions ||= {}
+      @__queue_logger ||= {}
+    end
+
+    # Kill the announcments queue.
+    # This is called automatically if you call queue_announcements!, before starting the next
+    # announcments thread, so it's optional. A way of stopping announcments.
+    def kill_queue!
+      @__kill_announcement_queue = true
+    end
+
+    # return whether annoucements are queued or sent out immediately when the #announce method is called.
+    def queue_announcements?
+      return @__queue_announcements.eql?(true)
+    end
+
+    def subscriptions= x; @__subscriptions = x; end
+    def subscriptions; @__subscriptions ||= []; end
+
+    protected
+      
+      #:stopdoc: 
+    
+      def log(msg, level = :info)
+        self.queue_logger.send(level, msg) if self.queue_logger
+      end
+
+      # return whether the queue was killed by kill_queue!
+      def queue_killed? 
+        @__kill_announcement_queue.eql?(true)
+      end
+
+      def queue_logger; @__queue_logger; end
+      def queue_logger= x; @__queue_logger = x; end
+      def announcements_queue; @__announcements_queue; end
+      def announcements_queue= x; @__announcements_queue = x; end
+      def announcements_thread; @__announcements_thread; end
+      def announcements_thread= x; @__announcements_thread = x; end
+      def kill_announcement_queue= x; @__kill_announcement_queue = x; end
+      def should_queue_announcements= x; @__queue_announcements = x; end
+
+      #:startdoc: 
+    public
+
+
+end
+
+

data/lib/cosell/monkey.rb

@@ -0,0 +1,32 @@
+#
+# Cosell is intended to be way for objects to 
+# communicate throughout the Object graph. It is _supposed_ to be
+# pervasive. As such, it has a few top-level methods that all objects inherit.
+#
+class Object
+
+  # When an object (or class) is announced, :as_announcement is called, the result of which
+  # becomes the announcement. By default just returns self, but can be overridden if appropriate.
+  # By default, simply return self.
+  def as_announcement
+    return self
+  end
+
+  # When cosell is configured to "spy!", the result of announement.as_announcement_trace is what
+  # is sent to the spy log. By default just calls 'to_s'.
+  def as_announcement_trace
+    self.to_s rescue "(Warning: could not create announcement trace)"
+  end
+
+  # When a class is used as an announcment, an empty new instance is created using #allocate.
+  # Will raise an exception for those rare classes that cannot #allocate a new instance.
+  def self.as_announcement
+    new_inst = self.allocate rescue nil
+    raise "Cannot create an announcement out of #{self}. Please implement 'as_announcement' as a class method of #{self}." if new_inst.nil?
+    new_inst
+  end
+
+end
+
+
+

data/spec/cosell_spec.rb

@@ -0,0 +1,179 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+#
+# A few announcments
+#
+class AWordFromOurSponsor
+  attr_accessor :word
+end
+class KnockOut; end
+class TKO < KnockOut; end
+
+#
+# A class whose objects can act as announcers
+#
+class AnyOldClass; include Cosell; end
+
+#
+# The tests
+#
+describe Cosell do
+
+  before(:each) do
+    @announcer = AnyOldClass.new
+  end
+
+  it "should instantiate announcement instance from class if needed" do
+    @announcer.announce(AWordFromOurSponsor).class.should be_eql(AWordFromOurSponsor)
+    @announcer.announce(AWordFromOurSponsor.new).class.should be_eql(AWordFromOurSponsor)
+  end
+
+  it "should execute block specified by subscription" do
+    
+    #@announcer.spy!
+
+    # After subscribing to KnockOut, make sure it fires whenever
+    # KnockOut or it's subclass TKO are announced.
+    
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+
+    what_was_announced = nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql KnockOut
+   
+    what_was_announced = nil
+    @announcer.announce TKO
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql TKO
+
+    
+    # Do the same thing as above, but announce instances (test above used the class as the announcement)
+    # make sure if an announcement instance is announced, that the exact instance is what is announced
+   
+    what_was_announced = nil
+    announcement = AWordFromOurSponsor.new
+    announcement.word = 'the'
+    @announcer.announce announcement
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql AWordFromOurSponsor
+    what_was_announced.word.should be_eql('the')
+   
+    what_was_announced = nil
+    @announcer.announce TKO.new
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql TKO
+
+  end
+
+  it "should take actions only on announcements of events for which there is a subscription" do
+    # Make sure the subscription block fires when an AWordFromOurSponsor is 
+    # announced, setting what_was_announced to the announcement)
+    what_was_announced = nil
+    @announcer.when_announcing(KnockOut) { |ann| what_was_announced = ann }
+
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should be_nil
+
+    @announcer.announce AWordFromOurSponsor.new # also test announcement instances
+    what_was_announced.should be_nil
+
+    @announcer.announce TKO # subclass of Knockout, should be announced
+    what_was_announced.should_not be_nil
+  end
+
+  it "should be able to subscribe to set of announcements types" do
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+
+    what_was_announced = nil
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should_not be_nil
+
+    what_was_announced = nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+  end
+
+  it "should not take actions after unsubscribing" do
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should_not be_nil
+
+    @announcer.unsubscribe(AWordFromOurSponsor)
+    what_was_announced = nil
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should be_nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+  end
+
+  it "should be able to queue announcements" do
+    what_was_announced = nil
+    count = 0
+    sleep_time = 0.1
+    how_many_each_cycle = 77
+    @announcer.queue_announcements!(:sleep_time => sleep_time, 
+                                    :logger => Logger.new(STDOUT),
+                                    :announcements_per_cycle => how_many_each_cycle)
+    @announcer.when_announcing(AWordFromOurSponsor) { |ann| count += 1 }
+
+    little_bench("time to queue 10_000 announcements"){10_000.times {@announcer.announce AWordFromOurSponsor}}
+
+    # @announcer.spy! #dbg
+
+    # Allow announcer thread to do a few batches of announcements, checking the 
+    # count after each batch. Since we may get to this part of the thread after
+    # the announcer has already made a few announcements, use the count at
+    # this moment as the starting_count
+    start_count = count
+    #puts "-------start count: #{count}" # dbg
+
+    sleep sleep_time + 0.01
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 1*how_many_each_cycle)
+
+    sleep sleep_time
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 2*how_many_each_cycle)
+
+    sleep sleep_time
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 3*how_many_each_cycle)
+
+    # See if killing the queue stops announcments that where queued
+    @announcer.kill_queue!
+    count_after_queue_stopped = count
+    #puts "-------count after stopping: #{count}" # dbg
+    sleep sleep_time * 2
+    count.should be_eql(count_after_queue_stopped)
+
+  end
+
+#  it "should suppress announcements during suppress_announcements block" do
+#    # TODO: support for this idiom:
+#    notifier.suppress_announcements_during {
+#    }
+#       and
+#    notifier.suppress_announcements(EventType,
+#                                    :during => lambda { "some operation" },
+#                                    :send_unique_events_when_done => true)
+#       and
+#    notifier.suppress_announcements(EventType,
+#                                    :during => lambda { "some operation" },
+#                                    :send_all_events_when_done => true)
+#  end
+
+  protected
+
+    def little_bench(msg, &block)
+      start = Time.now
+      result = block.call
+      puts "#{msg}: #{Time.now - start} sec"
+      return result
+    end
+end
+
+# EOF