josevalim-orchestra 0.0.1

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== First version
+
+Coming soon...

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Engine Yard
+
+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.rdoc

@@ -0,0 +1,5 @@
+== Instrumentation
+
+    Orchestra.instrument(:render, "template/path") do
+      render(...)
+    end

data/examples/bench.rb

@@ -0,0 +1,32 @@
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'orchestra'
+Thread.abort_on_exception = true
+
+require 'benchmark'
+
+LISTENERS = 3
+EVENTS = 10000
+
+Benchmark.bmbm(10) do |x|
+  x.report("publisher") do
+    publisher = Orchestra::Publisher.new
+
+    1.upto(LISTENERS) do |i|
+      subscriber = Orchestra::Subscriber.new(publisher)
+      subscriber.consume do |event|
+        if event.payload.first == "payload#{EVENTS}"
+          subscriber.disconnect!
+        end
+      end
+    end
+
+    1.upto(EVENTS) do |j|
+      publisher.push("hello", "payload#{j}")
+    end
+
+    loop do
+      break unless publisher.publishing?
+    end
+  end
+end

data/lib/orchestra.rb

@@ -0,0 +1,36 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'thread'
+require 'orchestra/event'
+require 'orchestra/publisher'
+require 'orchestra/subscriber'
+
+module Orchestra
+  @publisher = Orchestra::Publisher.new
+  @stacked_events = Hash.new { |h,k| h[k] = [] }
+
+  class << self
+    attr_accessor :publisher
+
+    def begin(name, *payload)
+      thread_id = Thread.current.object_id
+      event = Event.new(name, @stacked_events[thread_id].last, payload)
+      @stacked_events[thread_id] << event
+      event
+    end
+
+    def end
+      thread_id = Thread.current.object_id
+      event = @stacked_events[thread_id].pop
+      event.finish!
+      publisher.push(event)
+      event
+    end
+
+    def instrument(*args)
+      self.begin(*args)
+      yield
+      self.end
+    end
+  end
+end

data/lib/orchestra/event.rb

@@ -0,0 +1,29 @@
+module Orchestra
+  class Event
+    attr_reader :name, :time, :duration, :parent, :thread_id, :payload
+
+    def initialize(name, parent=nil, payload=nil)
+      @name      = name
+      @time      = Time.now.utc
+      @thread_id = Thread.current.object_id
+      @parent    = parent
+      @payload   = payload || []
+    end
+
+    def finish!
+      @duration = Time.now.utc - @time
+    end
+
+    def finished?
+      !!@duration
+    end
+
+    def parent?
+      !!@parent
+    end
+
+    def payload?
+      !@payload.empty?
+    end
+  end
+end

data/lib/orchestra/publisher.rb

@@ -0,0 +1,29 @@
+module Orchestra
+  class Publisher
+    attr_reader :mutex, :signaler
+
+    def initialize
+      @mutex, @signaler = Mutex.new, ConditionVariable.new
+      @subscribers = []
+    end
+
+    def push(event)
+      @mutex.synchronize do
+        @subscribers.each { |s| s.push(event) }
+        @signaler.broadcast
+      end
+    end
+
+    def register_subscriber(subscriber)
+      @subscribers << subscriber
+    end
+
+    def unregister_subscriber(subscriber)
+      @subscribers.delete(subscriber)
+    end
+
+    def publishing?
+      !@subscribers.empty?
+    end
+  end
+end

data/lib/orchestra/subscriber.rb

@@ -0,0 +1,34 @@
+module Orchestra
+  class Subscriber
+    def initialize(publisher)
+      @publisher, @stream = publisher, []
+      @publisher.register_subscriber(self)
+    end
+
+    def disconnect!
+      @publisher.unregister_subscriber(self)
+    end
+
+    def wait
+      @publisher.mutex.synchronize do
+        @publisher.signaler.wait(@publisher.mutex)
+      end
+    end
+
+    def push(event)
+      @stream.push(event)
+    end
+
+    def next
+      @stream.shift
+    end
+
+    def consume
+      Thread.new do
+        loop {
+          (event = self.next) ? (yield event) : wait
+        }
+      end
+    end
+  end
+end

data/lib/orchestra/version.rb

@@ -0,0 +1,3 @@
+module Orchestra
+  VERSION = "0.0.1"
+end

data/spec/event_spec.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Orchestra::Event do
+  before(:each) do
+    @parent = Orchestra::Event.new("parent")
+  end
+
+  it "is initialized with name, parent and payload" do
+    event = Orchestra::Event.new("awesome", @parent, ["orchestra"])
+    event.name.should    == "awesome"
+    event.parent.should  == @parent
+    event.payload.should == ["orchestra"]
+  end
+
+  it "sets the thread id on initialization" do
+    event = Orchestra::Event.new("awesome")
+    event.thread_id.should == Thread.current.object_id
+  end
+
+  it "sets the current time on initialization" do
+    mock(Time).now { Time.utc(2009) }
+    event = Orchestra::Event.new("awesome")
+    event.time.should == Time.utc(2009)
+  end
+
+  it "has a parent" do
+    event = Orchestra::Event.new("awesome", @parent)
+    event.parent?.should be_true
+
+    event = Orchestra::Event.new("awesome")
+    event.parent?.should be_false
+  end
+
+  it "has payload" do
+    event = Orchestra::Event.new("awesome", nil, ["orchestra"])
+    event.payload?.should be_true
+
+    event = Orchestra::Event.new("awesome")
+    event.payload?.should be_false
+  end
+
+  it "sets the duration when finishes" do
+    event = Orchestra::Event.new("awesome")
+    sleep(0.1)
+    event.should_not be_finished
+    event.finish!
+    event.should be_finished
+    (0.08..0.12).should include(event.duration)
+  end
+end

data/spec/orchestra_spec.rb

@@ -0,0 +1,41 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Orchestra do
+  before(:each) do
+    Orchestra.publisher = []
+  end
+
+  after(:each) do
+    Orchestra.publisher = Orchestra::Publisher.new
+  end
+
+  it "allows any action to be instrumented" do
+    Orchestra.instrument("awesome", "orchestra") do
+      sleep(0.1)
+    end
+    Orchestra.publisher.should have(1).event
+    Orchestra.publisher.last.should be_event(:name => "awesome", :payload => ["orchestra"], :between => 0.08..1.2)
+  end
+
+  it "allows any action to be instrumented with begin/end hooks" do
+    Orchestra.begin("awesome", "orchestra")
+    sleep(0.1)
+    Orchestra.end
+    Orchestra.publisher.should have(1).event
+    Orchestra.publisher.last.should be_event(:name => "awesome", :payload => ["orchestra"], :between => 0.08..1.2)
+  end
+
+  it "it allows nested action to be instrumented" do
+    Orchestra.instrument("awesome", "orchestra") do
+      Orchestra.begin("wot", "child")
+      sleep(0.1)
+      Orchestra.end
+
+      Orchestra.publisher.first.should be_event(:name => "wot", :payload => ["child"], :between => 0.08..1.2, :parent => "awesome")
+      Orchestra.publisher.first.parent.should_not be_finished
+    end
+
+    Orchestra.publisher.should have(2).events
+    Orchestra.publisher.last.should be_event(:name => "awesome", :payload => ["orchestra"], :between => 0.08..1.2)
+  end
+end

data/spec/publisher_spec.rb

@@ -0,0 +1,64 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Orchestra::Publisher do
+  before(:each) do
+    @subscriber = []
+    @publisher = Orchestra::Publisher.new
+
+    @awesome = Orchestra::Event.new("awesome", nil, ["orchestra"])
+    @wot = Orchestra::Event.new("wot", nil, ["orchestra"])
+  end
+
+  it "is not publishing initially" do
+    @publisher.should_not be_publishing
+  end
+
+  it "allows any subscriber to be added" do
+    @publisher.register_subscriber @subscriber
+    @publisher.should be_publishing
+  end
+
+  it "allows any subscriber to be removed" do
+    @publisher.register_subscriber @subscriber
+    @publisher.unregister_subscriber @subscriber
+    @publisher.should_not be_publishing
+  end
+
+  it "broadcasts to waiting locks on publishing" do
+    mock(@publisher.signaler).broadcast
+    @publisher.push @awesome
+  end
+
+  describe "with one subscriber" do
+    before(:each) do
+      @publisher.register_subscriber @subscriber
+    end
+
+    it "publishes to the subscriber" do
+      @publisher.push @awesome
+      @subscriber.first.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+
+    it "does not publish to removed subscriber" do
+      @publisher.push @awesome
+      @publisher.unregister_subscriber @subscriber
+
+      @publisher.push @wot
+      @subscriber.last.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+  end
+
+  describe "with several subscriber" do
+    before(:each) do
+      @another_subscriber = []
+      @publisher.register_subscriber @subscriber
+      @publisher.register_subscriber @another_subscriber
+    end
+
+    it "publishes to all subscribers" do
+      @publisher.push @awesome
+      @subscriber.first.should be_event(:payload => ["orchestra"], :name => "awesome")
+      @another_subscriber.first.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,45 @@
+$TESTING=true
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'orchestra'
+Thread.abort_on_exception = true
+
+Spec::Runner.configure do |config|
+  config.mock_with :rr
+
+  class BeEvent
+    def initialize(options)
+      options[:thread_id] ||= Thread.current.object_id
+      @options = options
+    end
+
+    def matches?(event)
+      if !event
+        @error = "Expected event to exist"
+      elsif event.name != @options[:name]
+        @error = "Expected event's name to be #{@options[:name].inspect}, but was #{event.name.inspect}"
+      elsif event.thread_id != @options[:thread_id]
+        @error = "Expected event's thread id to be #{@options[:thread_id]}, but was #{event.thread_id}"
+      elsif event.payload != @options[:payload]
+        @error = "Expected event's payload to be #{@options[:payload].inspect}, but was #{event.payload.inspect}"
+      elsif !event.time.kind_of?(Time)
+        @error = "Expected event's time to be a Time object, but was #{event.time.inspect}"
+      elsif @options.key?(:between) && !@options[:between].include?(event.duration)
+        @error = "Expected event's duration to be between #{@options[:between]}, but was #{event.duration}"
+      elsif @options.key?(:parent)
+        if event.parent.nil?
+          @error = "Expected event's parent to be #{@options[:parent]}, but was nil"
+        elsif event.parent.name != @options[:parent]
+          @error = "Expected event's parent to be #{@options[:parent]}, but was #{event.parent.name}"
+        end
+      end
+      !@error
+    end
+
+    def failure_message() @error end
+  end
+
+  def be_event(options)
+    BeEvent.new(options)
+  end
+end

data/spec/subscriber_spec.rb

@@ -0,0 +1,149 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "a subscriber with events on the queue", :shared => true do
+  it "is on the queue when Subscriber#next is called" do
+    event = @subscriber.next
+    event.should be_event(:name => (@name || "awesome"), :payload => ["orchestra"])
+  end
+end
+
+describe Orchestra::Subscriber do
+  before(:each) do
+    @publisher = Orchestra::Publisher.new
+    @subscriber = Orchestra::Subscriber.new(@publisher)
+
+    @awesome = Orchestra::Event.new("awesome", nil, ["orchestra"])
+    @wot = Orchestra::Event.new("wot", nil, ["orchestra"])
+  end
+
+  it "is instantiated with a publisher" do
+    Orchestra::Subscriber.new(@publisher)
+  end
+
+  it "returns nil from #next before anything has been pushed" do
+    @subscriber.next.should == nil
+  end
+
+  describe "when an event is added to the publisher" do
+    before(:each) do
+      @publisher.push @awesome
+    end
+
+    it_should_behave_like "a subscriber with events on the queue"
+  end
+
+  describe "when several events are added" do
+    before(:each) do
+      @publisher.push @awesome
+      @publisher.push @wot
+      @publisher.push @awesome
+    end
+
+    it_should_behave_like "a subscriber with events on the queue" 
+
+    it "consumes events in order" do
+      @subscriber.next
+      event = @subscriber.next
+      event.should be_event(:payload => ["orchestra"], :name => "wot")
+    end
+  end
+
+  describe "when blocking on an event" do
+    before(:each) do
+      @test = []
+      Thread.new { @subscriber.wait; @test << @subscriber.next }
+    end
+
+    it "initially blocks" do
+      @test.should be_empty
+    end
+
+    it "unblocks when an event is pushed on the queue" do
+      @publisher.push @awesome
+      sleep 0.1
+      @test.first.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+  end
+
+  describe "when consuming events" do
+    before(:each) do
+      @test = []
+      @subscriber.consume {|event| @test << event }
+    end
+
+    it "initially blocks" do
+      @test.should be_empty
+    end
+
+    it "unblocks when one event is pushed on the queue" do
+      @publisher.push @awesome
+      sleep 0.1
+      @test.first.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+
+    it "unblocks when several events are pushed on the queue" do
+      @publisher.push @wot
+      @publisher.push @awesome
+      sleep 0.1
+      @test.size.should == 2
+      @test.first.should be_event(:payload => ["orchestra"], :name => "wot")
+      @test.last.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+  end
+
+  describe "when several subscribers are consuming events" do
+    before(:each) do
+      @test1, @test2 = [], []
+      subscriber = Orchestra::Subscriber.new(@publisher)
+      subscriber.consume {|event| @test1 << event}
+
+      subscriber = Orchestra::Subscriber.new(@publisher)
+      subscriber.consume {|event| @test2 << event}
+    end
+
+    it "initially blocks" do
+      @test1.should be_empty
+      @test2.should be_empty
+    end
+
+    it "unblocks all queues when events are pushed on" do
+      @publisher.push @wot
+      @publisher.push @awesome
+      sleep 0.1
+
+      @test1.size.should == 2
+      @test1.first.should be_event(:payload => ["orchestra"], :name => "wot")
+      @test1.last.should be_event(:payload => ["orchestra"], :name => "awesome")
+
+      @test2.size.should == 2
+      @test2.first.should be_event(:payload => ["orchestra"], :name => "wot")
+      @test2.last.should be_event(:payload => ["orchestra"], :name => "awesome")
+    end
+  end
+
+  describe "with multiple subscribers and many events" do
+    before(:each) do
+      @publisher = Orchestra::Publisher.new
+
+      @subscribers = [
+        Orchestra::Subscriber.new(@publisher),
+        Orchestra::Subscriber.new(@publisher)
+      ]
+
+      1000.times do |i|
+        @publisher.push Orchestra::Event.new("wot", nil, ["payload#{i}"])
+      end
+    end
+
+    it "is safe when many events are added" do
+      @subscribers[0].next.should be_event(:name => "wot", :payload => ["payload0"])
+      @subscribers[1].next.should be_event(:name => "wot", :payload => ["payload0"])
+    end
+
+    it "is safe when only one subscriber reads through the queue" do
+      @subscribers[0].consume {}
+      sleep 0.1
+      @subscribers[1].next.should be_event(:name => "wot", :payload => ["payload0"])
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: josevalim-orchestra
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Yehuda Katz
+- "Jos\xC3\xA9 Valim"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-10 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Simple API to standardize instrumenting Ruby code
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG.rdoc
+- LICENSE
+- README.rdoc
+files: 
+- CHANGELOG.rdoc
+- LICENSE
+- README.rdoc
+- lib/orchestra.rb
+- lib/orchestra/event.rb
+- lib/orchestra/publisher.rb
+- lib/orchestra/subscriber.rb
+- lib/orchestra/version.rb
+has_rdoc: false
+homepage: 
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: orchestra
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Simple API to standardize instrumenting Ruby code
+test_files: 
+- spec/event_spec.rb
+- spec/spec_helper.rb
+- spec/publisher_spec.rb
+- spec/subscriber_spec.rb
+- spec/orchestra_spec.rb
+- examples/bench.rb