amqp-events 0.0.2

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+log
+.idea
+.bundle
+
+## PROJECT::SPECIFIC

data/HISTORY

@@ -0,0 +1,11 @@
+== 0.0.0 / 2010-10-22
+
+* Birthday!
+
+== 0.0.1 / 2010-10-22
+
+* Initial setup with C# specs
+
+== 0.0.2 / 2010-10-22
+
+* C# example extended

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Arvicco
+
+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,115 @@
+= amqp-events
+by: Arvicco
+url: http://github.com/arvicco/amqp-events
+
+== SUMMARY:
+
+Distributed Events/RPC system using AMQP as a transport.
+
+This is still work in progress, consider this library a deep deep pre-alpha at this point...
+
+== DESCRIPTION:
+
+What is an event, anyway? The way I understand it, it's kind of a method in reverse: instead of you calling
+it when you please with arguments and waiting for result, you humbly ask in to call YOU when it feels like.
+And indeed, when something happens and event "fires", you (your subscriber) get(s) called with arguments.
+This way, you can be sure that you'll be notified about external happenings, without the need to constantly
+(and inefficiently) poll your objects of interest.
+
+In order to coordinate activity of several daemons working on multiple hosts, I would like to use distributed events.
+Events here are understood as one-way messages emitted by daemons "to whom it may concern", with specific routing
+(categorization) and payload (event details, data). Other daemons may subscribe to events of specified category(ies)
+and/or sent by specified emitter. Such subscribers will receive only requested events, and nothing else.
+
+So, for example, you can make your daemon 'WorkerDaemon#1' emit 'LogEntry' event with routing like
+'log.worker_daemon.1.log_entry.error'. Somewhere else, you may have 'LogServer' daemon that subscribes to
+ALL 'LogEntry' events from ALL other deamons - once received, they are processed and logged to safe place.
+You may also have another 'Monitoring' daemon that subscribes only to errors from all (or a specific set of)
+daemons, inspects the errors received from them and reacts as appropriate. Such approach is much more clean
+and efficient than parsing log files for errors.
+
+You can further build an asynchronous RPC on top of such distributed Event system without too much sweat.
+
+AMQP seems like a natural choice for propagating such Events, Events map to AMQP messages and routing maps to
+AMQP exchange/topics structure very well.
+
+== IMPLEMENTATION:
+
+This README will double as a Design Document for the project, so here goes implementation detail...
+
+I see following layers of abstraction for this model (by Participant I mean any daemon using Event capabilities):
+* Events - module adding Event capabilities to objects
+* EventManager - used by Participant to emit Events and subscribe to external Events
+* Transport - actual wire protocol to send/receive external Events, that is a library wrapping AMQP
+* Serializer - used to dump Event content before sending over Transport and load content received from Transport
+* ServiceManager - used by Participant to expose its services and consume services by other Participants
+
+*Events* vision:
+Internal Events. Any objects can declare Events of interest, and other objects can subscribe to them
+(with a callable subscriber object, such as block, proc or method). Object can then either fire its declared Event
+manually, or tie Event to a specific method invocation (fire on method).
+When an Event fires, any object that subscribed to it receives a call to its registered subscriber with arguments
+supplied to Event#fire (or to the invoked method that this Event was tied to). This is a bit similar to Ruby's
+Observable mixin, but the difference is that multiple events may be declared by any object, not just a single type
+of event fired by changed/notify.
+External Events. Event system is extended beyond a single Ruby process with a help of EventManager. EventManager
+represents a proxy to external Events (that are a fired by other daemons). Any object can subscribe to external Events
+declared by EventManager using, again, a callable subscriber. This subscriber will receive
+
+*EventManager* encapsulates interface to external Events. It is used by Participant to:
+* emit Events (for general use or for specific <groups of> other Participants)
+* subscribe to Events (both external and internal)
+
+EventManager manages Participant’s subscriptions to external Events, and sends Events emitted by Participant
+(with appropriate Routing) through Transport.
+
+Essentially, Event is no different from “AMQP message”. It is called “Event” to emphasize its role in driving
+behavior and changing internal state of Participants. Each Event has Routing and Payload.
+
+*Routing* is in form of (root.type.categories.[emitter].severity.event_details). Participant emits Events with
+specific Routing, anyone subscribing to this routing receives this message and has to process the payload.
+A portion of routing may be “fixed” in Exchange/Queue name (exchange ‘root.events.system’ or
+‘root.data.stocks.tick.received’), another portion present as a topic, such as ‘my_host.driver.8156.info.quik.started’
+or (with emitter omitted) ‘us.nyce.goog’. Emitter identification (if present), should come first in topic portion,
+in the form of: host.participant_type.participant_id(process?uuid?)
+
+*Payload* is serialized and its internal structure is specific to the type of Event.
+Possible Event types (with severities) include:
+* Notifications (debug, info, warning)
+* Exceptions (error, critical, fatal)
+* Data (ticks, orders, etc),
+* RPC (command, return)
+...
+
+*Transport* encapsulates external messaging middleware (AMQP library). Its role is to send data to external destination
+(as defined by Routing) and deliver data received from external destination as instructed. It is used by EventManager
+to send serialized Events and subscribe to external Events. It encapsulates knowledge about exchanges and queues, and
+converts Routing requested by EventManager into actual combination of ‘exchange/queue name’ + ‘topic routing’.
+Where exactly does it get knowledge of actual exchange names, formats, etc from? Interface should be something like
+send(routing, message), subscribe(routing)...
+
+*Serializer* (Message Formatter) encapsulates transformation of actual Event/message content to/from format used for
+transportation. Serializer is used by EventManager to dump Event content before sending it over Transport and
+load content received from transport. Serializer interface includes only dump and load methods.
+
+=== Questions:
+Should Event#fire be sync or async? That is, should we wait for all subscribers to return after calling #fire?
+If it is async, something like "event queue" should exist...
+Should Seriaizer be called by EventManager or Transport?
+Who should know what format is appropriate for a given Routing? Transport knows about physical routing
+(exchange names, types), but EventManager knows about Event types and what content goes into what message.
+
+== FEATURES/PROBLEMS:
+
+This library is not mature enough for anything but experimental use...
+
+== SYNOPSIS:
+
+== REQUIREMENTS:
+
+== INSTALL:
+
+  $ sudo gem install amqp-events
+
+== LICENSE:
+Copyright (c) 2010 Arvicco. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,24 @@
+require 'pathname'
+NAME = 'amqp-events'
+BASE_PATH = Pathname.new(__FILE__).dirname
+LIB_PATH =  BASE_PATH + 'lib'
+PKG_PATH =  BASE_PATH + 'pkg'
+DOC_PATH =  BASE_PATH + 'rdoc'
+
+$LOAD_PATH.unshift LIB_PATH.to_s
+require 'version'
+
+CLASS_NAME = AMQP::Events
+VERSION = CLASS_NAME::VERSION
+
+begin
+  require 'rake'
+rescue LoadError
+  require 'rubygems'
+  gem 'rake', '~> 0.8.3.1'
+  require 'rake'
+end
+
+# Load rakefile tasks
+Dir['tasks/*.rake'].sort.each { |file| load file }
+

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/bin/amqp-events

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require Pathname.new(__FILE__).dirname + '../lib/amqp-events'
+
+# Put your code here
+

data/features/amqp-events.feature

@@ -0,0 +1,9 @@
+Feature: something something
+  In order to something something
+  A user something something
+  something something something
+
+  Scenario: something something
+    Given inspiration
+    When I create a sweet new gem
+    Then everyone should see how awesome I am

data/features/support/env.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+
+require 'pathname'
+require 'bundler'
+Bundler.setup
+Bundler.require :cucumber
+
+require 'amqp-events'
+
+BASE_PATH = Pathname.new(__FILE__).dirname + '../..'

data/features/support/world.rb

@@ -0,0 +1,12 @@
+module SystemHelper
+
+  def windows?
+    RUBY_PLATFORM =~ /mswin|windows|mingw/ || cygwin?
+  end
+
+  def cygwin?
+    RUBY_PLATFORM =~ /cygwin/
+  end
+end
+
+World(WinGui, SystemHelper)

data/lib/amqp-events.rb

@@ -0,0 +1,26 @@
+require 'version'
+
+module AMQP
+  module Events
+    require "bundler/setup"
+#  Bundler.require :group
+
+    # Requires ruby source file(s). Accepts either single filename/glob or Array of filenames/globs.
+    # Accepts following options:
+    # :*file*:: Lib(s) required relative to this file - defaults to __FILE__
+    # :*dir*:: Required lib(s) located under this dir name - defaults to gem name
+    #
+    def self.require_libs(libs, opts={})
+      file = Pathname.new(opts[:file] || __FILE__)
+      [libs].flatten.each do |lib|
+        name = file.dirname + (opts[:dir] || file.basename('.*')) + lib.gsub(/(?<!.rb)$/, '.rb')
+        Pathname.glob(name.to_s).sort.each { |rb| require rb }
+      end
+    end
+  end
+end
+
+# Require all ruby source files located under directory lib/amqp-events
+# If you need files in specific order, you should specify it here before the glob
+AMQP::Events.require_libs %W[**/*]
+

data/lib/amqp-events/events.rb

@@ -0,0 +1,157 @@
+module AMQP
+  module Events
+    if RUBY_PLATFORM =~ /mingw|mswin|windows/ #Windows!
+      require 'uuid'
+      UUID = UUID
+    else
+      require 'em/pure_ruby'
+      UUID = EventMachine::UuidGenerator
+    end
+
+    class HandlerError < TypeError
+    end
+
+    # TODO: Mutexes to synchronize @subscribers update ?
+    # http://github.com/snuxoll/ruby-event/blob/master/lib/ruby-event/event.rb
+    # TODO: Meta-methods that allow Events to fire on method invocations:
+    # http://github.com/nathankleyn/ruby_events/blob/85f8e6027fea22e9d828c91960ce2e4099a9a52f/lib/ruby_events.rb
+    # TODO: Add exception handling and subscribe/unsubscribe notifications:
+    # http://github.com/matsadler/rb-event-emitter/blob/master/lib/events.rb
+    class Event
+
+      attr_reader :name, :subscribers
+      alias_method :listeners, :subscribers
+
+      def initialize(name)
+        @name = name
+        @subscribers = {}
+      end
+
+      # You can subscribe anything callable to the event, such as lambda/proc,
+      # method(:method_name), attached block or a custom Handler. The only requirements,
+      # it should respond to a #call and accept arguments given to Event#fire.
+      #
+      # You can give optional name to your subscriber. If you do, you can later
+      # unsubscribe it using this name. If you do not give subscriber a name, it will
+      # be auto-generated using its #name method and uuid.
+      #
+      # You can unsubscribe your subscriber later, provided you know its name.
+      #
+      # :call-seq:
+      #   event.subscribe("subscriber_name", proc{|*args| "Subscriber 1"})
+      #   event.subscribe("subscriber_name", method(:method_name))
+      #   event.subscribe(method(:method_name) # Implicit subscriber name == :method_name
+      #   event.subscribe("subscriber_name") {|*args| "Named subscriber block" }
+      #   event += method(:method_name)  # C# compatible syntax, just without useless "delegates"
+      #
+      def subscribe(*args, &block)
+        subscriber = block ? block : args.pop
+        name = args.empty? ? generate_subscriber_name(subscriber) : args.first
+
+        raise HandlerError.new "Handler #{subscriber.inspect} does not respond to #call" unless subscriber.respond_to? :call
+        raise HandlerError.new "Handler name #{name} already in use" if @subscribers.has_key? name
+        @subscribers[name] = subscriber
+
+        self # This allows C#-like syntax : my_event += subscriber
+      end
+
+      alias_method :listen, :subscribe
+      alias_method :+, :subscribe
+
+      # Unsubscribe existing subscriber by name
+      def unsubscribe(name)
+        raise HandlerError.new "Unable to unsubscribe handler #{name}" unless @subscribers.has_key? name
+        @subscribers.delete(name)
+
+        self # This allows C#-like syntax : my_event -= subscriber
+      end
+
+      alias_method :remove, :unsubscribe
+      alias_method :-, :unsubscribe
+
+      # TODO: make fire async: just fire and continue, instead of waiting for all subscribers to return,
+      # as it is right now. AMQP callbacks and EM:Deferrable?
+      def fire(*args)
+        @subscribers.each do |key, subscriber|
+          subscriber.call *args
+        end
+      end
+
+      alias_method :call, :fire
+
+      # Clears all the subscribers for a given Event
+      def clear
+        @subscribers.clear
+      end
+
+      def == (other)
+        case other
+          when Event
+            super
+          when nil
+            @subscribers.empty?
+          else
+            false
+        end
+      end
+
+      private
+      def generate_subscriber_name(subscriber)
+        "#{subscriber.respond_to?(:name) ? subscriber.name : 'subscriber'}-#{UUID.generate}".to_sym
+      end
+    end
+
+    def events
+      @events ||= self.class.instance_events.inject({}) { |hash, name| hash[name]=Event.new(name); hash }
+    end
+
+    def event(name)
+      sym_name = name.to_sym
+      self.class.event(sym_name)
+      events[sym_name] ||= Event.new(sym_name)
+    end
+
+# Once included into a class/module, gives this module .event macros for declaring events
+    def self.included(host)
+
+      host.instance_exec do
+        def instance_events
+          @instance_events ||= []
+        end
+
+        def event (name)
+
+          instance_events << name.to_sym
+          # Defines instance method that has the same name as the Event being declared.
+          # Calling it without arguments returns Event object itself
+          # Calling it with block adds unnamed subscriber for Event
+          # Calling it with arguments fires the Event
+          # Such a messy interface provides some compatibility with C# events behavior
+          define_method name do |*args, &block|
+            events[name] ||= Event.new(name)
+            if args.empty?
+              if block
+                events[name].subscribe &block
+              else
+                events[name]
+              end
+            else
+              events[name].fire(*args)
+            end
+          end
+
+          # Needed to support C#-like syntax : my_event -= subscriber
+          define_method "#{name}=" do |event|
+            if event.kind_of? Event
+              events[name] = event
+            else
+              raise Events::SubscriberTypeError.new "Attempted assignment #{event.inspect} is not an Event"
+            end
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/version.rb

@@ -0,0 +1,10 @@
+require 'pathname'
+
+module AMQP
+  module Events
+
+  VERSION_FILE = Pathname.new(__FILE__).dirname + '../VERSION'   # :nodoc:
+  VERSION = VERSION_FILE.exist? ? VERSION_FILE.read.strip : nil
+
+  end
+end

data/spec/amqp-events_spec.rb

@@ -0,0 +1,214 @@
+require 'spec_helper'
+
+class EmptyTestClass
+  include AMQP::Events
+end
+
+class TestClassWithEvents
+  include AMQP::Events
+
+  event :Bar
+  event :Baz
+end
+
+shared_examples_for 'evented class' do
+  specify { should respond_to :instance_events }
+  its(:instance_events) { should be_an Array }
+end
+
+shared_examples_for 'evented object' do
+  specify { should respond_to :events }
+  its(:events) { should be_a Hash }
+end
+
+def subscribers_to_be_called(num)
+  @counter = 0
+
+  subject.Bar.subscribers.should have(num).subscribers
+  subject.Bar.listeners.should have(num).listeners
+
+  subject.Bar.fire "data" # fire Event, sending "data" to subscribers
+  @counter.should == num
+end
+
+
+module EventsTest
+  describe EmptyTestClass, ' that includes AMQPEvents::Events and is just instantiated' do
+    subject { EmptyTestClass }
+
+    it_should_behave_like 'evented class'
+    its(:instance_events) { should be_empty }
+
+  end
+
+  describe EmptyTestClass, ' when instantiated' do
+    subject { EmptyTestClass.new }
+
+    it_should_behave_like 'evented object'
+    its(:events) { should be_empty }
+
+    context 'creating new (class-wide) Events' do
+      it 'should create events on instance' do
+        subject.event :Blah
+        subject.events.should include :Blah
+      end
+    end
+  end
+
+  describe TestClassWithEvents, ' (predefined) that includes AMQPEvents::Events' do
+    subject { TestClassWithEvents }
+
+    it_should_behave_like 'evented class'
+    its(:instance_events) { should include :Bar }
+    its(:instance_events) { should include :Baz }
+
+    it 'should create new events' do
+      subject.event :Foo
+      subject.instance_events.should include :Foo
+    end
+  end
+
+  describe TestClassWithEvents, ' when instantiated' do
+
+    it_should_behave_like 'evented object'
+    its(:events) { should have_key :Bar }
+    its(:events) { should have_key :Baz }
+
+    context 'creating new (class-wide) Events' do
+      it 'should create events on instance' do
+        subject.event :Blah
+        subject.events.should include :Blah
+        # object effectively defines new Event for all similar instances... Should it be allowed?
+        subject.class.instance_events.should include :Blah
+      end
+    end
+
+    context "#subscribe to object's Event" do
+
+      it 'allows anyone to add block subscribers/listeners (multiple syntax)' do
+        subject.events[:Bar].subscribe(:bar1) { |*args| args.should == ["data"]; @counter += 1 }
+        subject.Bar.subscribe(:bar2) { |*args| args.should == ["data"]; @counter += 1 }
+        subject.Bar.listen(:bar3) { |*args| args.should == ["data"]; @counter += 1 }
+
+        subscribers_to_be_called 3
+      end
+
+      it 'allows anyone to add method subscribers/listeners (multiple syntax)' do
+        def self.subscriber_method(*args)
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.events[:Bar].subscribe(:bar1, method(:subscriber_method))
+        subject.Bar.subscribe(:bar2, method(:subscriber_method))
+        subject.Bar.listen(:bar3, method(:subscriber_method))
+        subject.Bar.listen(method(:subscriber_method))
+        subject.Bar += method(:subscriber_method)
+
+        subscribers_to_be_called 5
+      end
+
+      it 'allows anyone to add proc subscribers/listeners (multiple syntax)' do
+        subscriber_proc = proc do |*args|
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.events[:Bar].subscribe(:bar1, subscriber_proc)
+        subject.Bar.subscribe(:bar2, subscriber_proc)
+        subject.Bar.subscribe(:bar3, &subscriber_proc)
+        subject.Bar.subscribe subscriber_proc
+        subject.Bar.subscribe &subscriber_proc
+        subject.Bar.listen subscriber_proc
+        subject.Bar += subscriber_proc
+
+        subscribers_to_be_called 7
+      end
+
+      it "allows you to mix subscriber types for one Event" do
+        def self.subscriber_method(*args)
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subscriber_proc = proc do |*args|
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.Bar.subscribe { |*args| args.should == ["data"]; @counter += 1 }
+        subject.Bar += method :subscriber_method
+        subject.Bar += subscriber_proc
+
+        subscribers_to_be_called 3
+      end
+
+      it "raises exception if the given handler is not callable" do
+
+        [:subscriber_symbol, 1, [1, 2, 3], {me: 2}].each do |args|
+          expect { subject.Bar.subscribe(args) }.
+                  to raise_error /Handler .* does not respond to #call/
+          expect { subject.Bar.subscribe(:good_name, args) }.
+                  to raise_error /Handler .* does not respond to #call/
+          subscribers_to_be_called 0
+        end
+      end
+
+      it "raises exception when adding handler with duplicate name" do
+        subscriber_proc = proc do |*args|
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.Bar.listen(:bar1) { |*args| args.should == ["data"]; @counter += 1 }
+
+        expect { subject.Bar.listen(:bar1) { |*args| args.should == ["data"]; @counter += 1 } }.
+                to raise_error /Handler name bar1 already in use/
+        expect { subject.Bar.listen(:bar1, subscriber_proc) }.
+                to raise_error /Handler name bar1 already in use/
+        subscribers_to_be_called 1
+      end
+    end #subscribe
+
+    context "#unsubscribe from object's Event" do
+      it "allows you to unsubscribe from Events by name" do
+        def self.subscriber_method(*args)
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subscriber_proc = proc do |*args|
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.Bar.subscribe(:bar1) { |*args| args.should == ["data"]; @counter += 1 }
+        subject.Bar.subscribe(:bar2, method(:subscriber_method))
+        subject.Bar.subscribe(:bar3, subscriber_proc)
+
+        subject.Bar.unsubscribe(:bar1)
+        subject.Bar.unsubscribe(:bar2)
+        subject.Bar.unsubscribe(:bar3)
+
+        subscribers_to_be_called 0
+      end
+
+      it "raises exception if the name is unknown or wrong" do
+        subscriber_proc = proc do |*args|
+          args.should == ["data"]
+          @counter += 1
+        end
+
+        subject.Bar.subscribe(subscriber_proc)
+
+        expect { subject.Bar.unsubscribe(subscriber_proc) }.
+                to raise_error /Unable to unsubscribe handler/
+        expect { subject.Bar.unsubscribe('I-dont-know') }.
+                to raise_error /Unable to unsubscribe handler I-dont-know/
+
+        subscribers_to_be_called 1
+      end
+    end #unsubscribe
+  end # TestClassWithEvents, ' when instantiated'
+end # module EventsTest
+

data/spec/cs_spec.rb

@@ -0,0 +1,97 @@
+#require 'spec_helper'
+require_relative '../lib/amqp-events/events'
+module EventsTest
+  describe AMQP::Events, ' when running Second Change Event Example' do
+    before { @clock = SecondChangeEvent::Clock.new }
+    let(:messages) { [] }
+
+    it 'should replicate results of C# example' do
+      @n = 0
+      $stdout.should_receive(:puts) { |msg| messages << msg; true }.at_least(10).times
+
+#        #// Create the display and tell it to subscribe to the clock just created
+      dc = SecondChangeEvent::DisplayClock.new
+      dc.Subscribe(@clock)
+
+      #// Create a Log object and tell it to subscribe to the clock
+      lc = SecondChangeEvent::LogClock.new
+      lc.Subscribe(@clock)
+
+      #// Get the clock started
+      @clock.Run(1)
+
+      messages.count { |msg| msg =~/Current Time:/ }.should be_between 10, 11
+      messages.count { |msg| msg =~/Logging to file:/ }.should be_between 10, 11
+      messages.count { |msg| msg =~/Wow! Second passed!:/ }.should be_between 1, 2
+    end
+
+  end
+end # module AMQPEventsTest
+
+# This is a reproduction of "The Second Change Event Example" from:
+# http://www.akadia.com/services/dotnet_delegates_and_events.html
+# Now I need to change it into a test suite somehow...
+module SecondChangeEvent
+#  /* ======================= Event Publisher =============================== */
+
+#  Our subject -- it is this class that other classes will observe. This class publishes one event:
+#  SecondChange. The observers subscribe to that event.
+  class Clock
+    include AMQP::Events
+
+    event :DeciSecondChange
+    event :SecondChange
+
+    # Set the clock running, it will raise an event for each new MILLI second!
+    # With timeout for testing
+    def Run(timeout=nil)
+      start = Time.now
+      while !timeout || timeout > Time.now - start do
+        time = Time.now
+
+        # If the (centi)second has changed, notify the subscribers
+        # MilliSecondChange(self, time) if time.usec/1000 != @millisec # Doesn't work, Windows timer is ~ 15 msec
+        DeciSecondChange(self, time) if time.usec/100_000 != @decisec
+        SecondChange(self, time) if time.sec != @sec
+
+        # Update the state
+        @decisec = time.usec/100_000
+        @sec = time.sec
+      end
+    end
+  end
+
+#  /* ======================= Event Subscribers =============================== */
+
+  # An observer. DisplayClock subscribes to the clock's events.
+  # The job of DisplayClock is to display the current time
+  class DisplayClock
+    # Given a clock, subscribe to its SecondChange event
+    def Subscribe(theClock)
+      # Calling SecondChange without parameters returns the Event object itself
+      theClock.DeciSecondChange += proc { |*args| TimeHasChanged(*args) } # subscribing with a proc
+      theClock.SecondChange.subscribe do |theClock, ti| # subscribing with block
+        puts "Wow! Second passed!: #{ti.hour}:#{ti.min}:#{ti.sec}"
+      end
+    end
+
+    #// The method that implements the delegated functionality
+    def TimeHasChanged(theClock, ti)
+      puts "Current Time: #{ti.hour}:#{ti.min}:#{ti.sec}"
+    end
+  end
+
+  # A second subscriber whose job is to write to a file
+  class LogClock
+
+    def Subscribe(theClock)
+      theClock.DeciSecondChange += method :WriteLogEntry # subscribing with a Method name
+    end
+
+    # This method should write to a file, but we just write to the console to see the effect
+    def WriteLogEntry(theClock, ti)
+      puts "Logging to file: #{ti.hour}:#{ti.min}:#{ti.sec}"
+      # Code that logs to file goes here...
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format nested

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+require 'bundler'
+Bundler.setup
+Bundler.require :test
+
+require 'amqp-events'
+require 'pathname'
+
+BASE_PATH = Pathname.new(__FILE__).dirname + '..'
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+module EventsTest
+
+end # module EventsTest

data/tasks/common.rake

@@ -0,0 +1,18 @@
+#task :default => 'test:run'
+#task 'gem:release' => 'test:run'
+
+task :notes do
+ puts 'Output annotations (TBD)'
+end
+
+#Bundler not ready for prime time just yet
+#desc 'Bundle dependencies'
+#task :bundle do
+#  output = `bundle check 2>&1`
+#
+#  unless $?.to_i == 0
+#    puts output
+#    system "bundle install"
+#    puts
+#  end
+#end

data/tasks/doc.rake

@@ -0,0 +1,14 @@
+desc 'Alias to doc:rdoc'
+task :doc => 'doc:rdoc'
+
+namespace :doc do
+  require 'rake/rdoctask'
+  Rake::RDocTask.new do |rdoc|
+#    Rake::RDocTask.new(:rdoc => "rdoc", :clobber_rdoc => "clobber", :rerdoc => "rerdoc") do |rdoc|
+    rdoc.rdoc_dir = DOC_PATH.basename.to_s
+    rdoc.title = "#{NAME} #{VERSION} Documentation"
+    rdoc.main = "README.doc"
+    rdoc.rdoc_files.include('README*')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  end
+end

data/tasks/gem.rake

@@ -0,0 +1,40 @@
+desc "Alias to gem:release"
+task :release => 'gem:release'
+
+desc "Alias to gem:install"
+task :install => 'gem:install'
+
+desc "Alias to gem:build"
+task :gem => 'gem:build'
+
+namespace :gem do
+  gem_file = "#{NAME}-#{VERSION}.gem"
+
+  desc "(Re-)Build gem"
+  task :build do
+    puts "Remove existing gem package"
+    rm_rf PKG_PATH
+    puts "Build new gem package"
+    system "gem build #{NAME}.gemspec"
+    puts "Move built gem to package dir"
+    mkdir_p PKG_PATH
+    mv gem_file, PKG_PATH
+  end
+
+  desc "Cleanup already installed gem(s)"
+  task :cleanup do
+    puts "Cleaning up installed gem(s)"
+    system "gem cleanup #{NAME}"
+  end
+
+  desc "Build and install gem"
+  task :install => :build do
+    system "gem install #{PKG_PATH}/#{gem_file}"
+  end
+
+  desc "Build and push gem to Gemcutter"
+  task :release => [:build, 'git:tag'] do
+    puts "Pushing gem to Gemcutter"
+    system "gem push #{PKG_PATH}/#{gem_file}"
+  end
+end

data/tasks/git.rake

@@ -0,0 +1,34 @@
+desc "Alias to git:commit"
+task :git => 'git:commit'
+
+namespace :git do
+
+  desc "Stage and commit your work [with message]"
+  task :commit, [:message] do |t, args|
+    puts "Staging new (unversioned) files"
+    system "git add --all"
+    if args.message
+      puts "Committing with message: #{args.message}"
+      system %Q[git commit -a -m "#{args.message}" --author arvicco]
+    else
+      puts "Committing"
+      system %Q[git commit -a -m "No message" --author arvicco]
+    end
+  end
+
+  desc "Push local changes to Github"
+  task :push => :commit do
+    puts "Pushing local changes to remote"
+    system "git push"
+  end
+
+  desc "Create (release) tag on Github"
+  task :tag => :push do
+    tag = VERSION
+    puts "Creating git tag: #{tag}"
+    system %Q{git tag -a -m "Release tag #{tag}" #{tag}}
+    puts "Pushing #{tag} to remote"
+    system "git push origin #{tag}"
+  end
+
+end

data/tasks/spec.rake

@@ -0,0 +1,19 @@
+desc 'Alias to spec:spec'
+task :spec => 'spec:spec'
+
+namespace :spec do
+  require 'spec/rake/spectask'
+
+  desc "Run all specs"
+  Spec::Rake::SpecTask.new(:spec) do |t|
+    t.spec_opts = ['--options', %Q{"#{BASE_PATH}/spec/spec.opts"}]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+  desc "Run specs with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+end

data/tasks/version.rake

@@ -0,0 +1,71 @@
+class Version
+  attr_accessor :major, :minor, :patch, :build
+
+  def initialize(version_string)
+    raise "Invalid version #{version_string}" unless version_string =~ /^(\d+)\.(\d+)\.(\d+)(?:\.(.*?))?$/
+    @major = $1.to_i
+    @minor = $2.to_i
+    @patch = $3.to_i
+    @build = $4
+  end
+
+  def bump_major(x)
+    @major += x.to_i
+    @minor = 0
+    @patch = 0
+    @build = nil
+  end
+
+  def bump_minor(x)
+    @minor += x.to_i
+    @patch = 0
+    @build = nil
+  end
+
+  def bump_patch(x)
+    @patch += x.to_i
+    @build = nil
+  end
+
+  def update(major, minor, patch, build=nil)
+    @major = major
+    @minor = minor
+    @patch = patch
+    @build = build
+  end
+
+  def write(desc = nil)
+    CLASS_NAME::VERSION_FILE.open('w') {|file| file.puts to_s }
+    (BASE_PATH + 'HISTORY').open('a') do |file|
+      file.puts "\n== #{to_s} / #{Time.now.strftime '%Y-%m-%d'}\n"
+      file.puts "\n* #{desc}\n" if desc
+    end
+  end
+
+  def to_s
+    [major, minor, patch, build].compact.join('.')
+  end
+end
+
+desc 'Set version: [x.y.z] - explicitly, [1/10/100] - bump major/minor/patch, [.build] - build'
+task :version, [:command, :desc] do |t, args|
+  version = Version.new(VERSION)
+  case args.command
+    when /^(\d+)\.(\d+)\.(\d+)(?:\.(.*?))?$/  # Set version explicitly
+      version.update($1, $2, $3, $4)
+    when /^\.(.*?)$/                        # Set build
+      version.build = $1
+    when /^(\d{1})$/                          # Bump patch
+      version.bump_patch $1
+    when /^(\d{1})0$/                         # Bump minor
+      version.bump_minor $1
+    when /^(\d{1})00$/                        # Bump major
+      version.bump_major $1
+    else                                      # Unknown command, just display VERSION
+      puts "#{NAME} #{version}"
+      next
+  end
+
+  puts "Writing version #{version} to VERSION file"
+  version.write args.desc
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification 
+name: amqp-events
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- arvicco
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-25 00:00:00 +04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :runtime
+  version_requirements: *id003
+description: Distributed Events/RPC system using AMQP as a transport (pre-alpha)
+email: arvitallian@gmail.com
+executables: 
+- amqp-events
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- HISTORY
+- README.rdoc
+files: 
+- bin/amqp-events
+- lib/amqp-events/events.rb
+- lib/amqp-events.rb
+- lib/version.rb
+- spec/amqp-events_spec.rb
+- spec/cs_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- features/amqp-events.feature
+- features/step_definitions/amqp-events_steps.rb
+- features/support/env.rb
+- features/support/world.rb
+- tasks/common.rake
+- tasks/doc.rake
+- tasks/gem.rake
+- tasks/git.rake
+- tasks/spec.rake
+- tasks/version.rake
+- Rakefile
+- README.rdoc
+- LICENSE
+- VERSION
+- HISTORY
+- .gitignore
+has_rdoc: true
+homepage: http://github.com/arvicco/amqp-events
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset
+- UTF-8
+- --main
+- README.rdoc
+- --title
+- amqp-events
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Distributed Events/RPC system using AMQP as a transport.
+test_files: 
+- spec/amqp-events_spec.rb
+- spec/cs_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb