cross-talk 0.0.1 → 0.1.0

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode

data/Gemfile

@@ -1,4 +1,14 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in cross-talk.gemspec
+gem 'rake'
+
+gem 'rspec'
+gem 'rspec-spies'
+gem 'coveralls', require: false
+gem 'flay'
+gem 'flog'
+gem 'mutant'
+
+gem 'pry'
+
 gemspec

data/NOTES.md

@@ -0,0 +1,58 @@
+# Cross::Talk -- Event Pub/Sub for PORC
+
+## Design Notes
+
+At require-time, create a `Cross::Talk::Manager` instance (a singleton). This
+serves as the clearinghouse for all events. It is a celluloid actor.
+
+NB. Though cross-talk is perfectly happy to run on MRI, you'll probably have
+performance issues unless you run on RBX/JRuby, because we are likely sending
+_lots_ of messages at any given point in time, and that means we're probably
+eating a lot of CPU cycles.
+
+Every public method call triggers and asynchronous notification to the
+`Cross::Talk::Manager` (henceforth, `CTM`). Containing the method invoked, the
+object that invoked it, and `:before` or `:after` (depending on which side of
+the method you're on).
+
+Another class can subscribe to any event by simply using the class macro
+`#listen`, a la:
+
+
+    class Foo
+      include Celluloid::Actor
+      include Celluloid::Logger
+      include Cross::Talk
+
+      def bar
+        info "baz"
+      end
+    end
+
+    class Listener
+      include Celluloid::Actor
+      include Celluloid::Logger
+      include Cross::Talk
+
+      listen Foo, :bar, :before do
+        info "before Foo#bar"
+      end
+
+      listen "Foo#bar:after" do |obj|
+        info "Calling terminate! on Foo instance"
+        obj.terminate!
+      end
+    end
+
+
+    Listener.new
+    Foo.new.bar
+
+    #=> before Foo#bar
+    #=> baz
+    #=> Calling terminate! on Foo instance
+    #=> <Celluloid::Actor Foo Terminated>
+
+(mod output formatting).
+
+

data/README.md

@@ -1,9 +1,19 @@
-# Cross::Talk
+# Cross::Talk [![Gem Version](https://badge.fury.io/rb/cross-talk.png)](http://badge.fury.io/rb/cross-talk) [![Build Status](https://travis-ci.org/jfredett/cross-talk.png?branch=master)](http://travis-ci.org/jfredett/cross-talk) [![Code Climate](https://codeclimate.com/github/jfredett/cross-talk.png)](https://codeclimate.com/github/jfredett/cross-talk) [![Coverage Status](https://coveralls.io/repos/jfredett/cross-talk/badge.png?branch=master)](https://coveralls.io/r/jfredett/cross-talk)
 
 NOTA BENE:
 
-This is primarily lies. This is not production ready, this isn't even really
-worthy of being read. But it'll be cool when it's done.
+This is not production ready, the basic functionality is there, but use in
+critical code is at your own risk.
+
+Also, this thing is almost certainly going to give you performance problems of
+the most severe variety.
+
+## Support
+
+Check CI for edge support, but ideally we support MRI > 1.9, (including 2.0),
+Reasonably recent RBX, and JRuby.
+
+JRuby is broken right now though for unknown reasons.
 
 ## Installation
 
@@ -21,7 +31,52 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+For any object (not just Celluloid Actors, though they'll work the best) simply
+include `Cross::Talk` and enjoy the following features for that class:
+
+1. Any public method will automatically send out two events -- one at the
+   beginning of execution, the other at the end. These are identified by the
+   schema: `<class>#<method>:<time>`. Eg. for a class `Foo`, and a method `bar`,
+   calling `Foo.new.bar` would send an event `Foo#bar:before`, and then a
+   `Foo#bar:after`. Note that the event is the same for any instance of the
+   class, then read the "Plans" section, item 2.
+
+2. Any Cross::Talk class can bind to an event by using the `listen` macro at
+   define-time
+
+3. Any instance of a Cross::Talk class can bind to an event later, without
+   forcing every other instance to also bind to that event. Think of the
+   difference between `define_method` and `define_singleton_method` (in fact
+   they are implemented precisely that way)
+
+4. Celluloid Actors which include `Cross::Talk` will have the events sent to
+   them asynchronously, so the event handler won't block while trying to
+   dispatch those events
+
+
+## Plans
+
+1. Improve the `listen` macro so you don't always need to supply an argument --
+   it should just be ignored if it's not there.
+
+2. Allow `listen` to bind to a specific _instance_ of an event, rather than just
+   the whole class of events.
+
+3. Refactor the codebase, it's a bit sprawling right now
+
+4. Optimize for dispatch speed -- basically make it as lightweight as possible
+
+5. Make the Event Dispatcher maybe use some thread primitives during dispatch
+   around non-actors, so that we can join at the end and still send them
+   asynchronous events?
+
+### Pipe dreams
+
+1. Optionally back the event manager with a message queue, because why the hell
+   not? It's worth a try, maybe it'll do something neat.
+
+2. Experiment with making this usable efficiently over DCell. Including making
+   the Event Manager run as a cluster of actors, notifying remote actors, etc.
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,35 @@
-require "bundler/gem_tasks"
+#!/usr/bin/env rake
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'run specs'
+RSpec::Core::RakeTask.new do |task|
+  task.rspec_opts = ["-c", "-f progress"]
+end
+
+task :default => :spec
+
+
+task :flog do
+  puts "#### FLOG ####"
+  system 'flog lib/*'
+  puts "##############"
+end
+
+task :flay do
+  puts "#### FLAY ####"
+  system 'flay lib/*'
+  puts "##############"
+end
+
+task :mutant, [:klass] do |_, args|
+  puts "#### MUTANT TESTING ####"
+  system "mutant -I lib -r cross-talk --rspec-full #{args[:name] || '::Katuv'}"
+  puts "########################"
+end
+
+task :metrics => [:flog, :flay]
+
+
+task :all => [:spec, :mutant, :metrics]

data/cross-talk.gemspec

@@ -16,4 +16,6 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
+
+  gem.add_dependency 'celluloid'
 end

data/lib/cross-talk.rb

@@ -1,7 +1,20 @@
+require 'celluloid'
+
 require "cross-talk/version"
+require 'cross-talk/manager'
+require 'cross-talk/listener'
 
 module Cross
   module Talk
-    # Your code goes here...
+    # Access the Event Manager
+    def self.manager
+      Celluloid::Actor[:manager] ||= Cross::Talk::Manager.new
+    end
+
+    def self.included(base)
+      base.send(:include, Listener)
+    end
   end
 end
+
+

data/lib/cross-talk/listener.rb

@@ -0,0 +1,123 @@
+module Cross
+  module Talk
+    module Listener
+      def self.included(base)
+        base.send(:include, InstanceMethods)
+        base.send(:extend, ClassMethods)
+        base.send(:include, Celluloid::Logger)
+        base.send(:extend, Celluloid::Logger)
+
+        # This makes sure that when we add a new hook at runtime, we rebuild all
+        # of our hooks so that they're up-to-date.
+        base.instance_eval do
+          listen base, :__new_hook, :before do
+            register_hooks!
+          end
+        end
+      end
+
+      module InstanceMethods
+        def register_hooks!
+          self.class.registration_hooks.each { |hook| hook.call(__get_receiver) }
+        end
+
+        def initialize(*_)
+          register_hooks!
+          super
+        end
+
+        def silenced?
+          @__silenced
+        end
+
+        def silence!
+          @__silenced = true
+        end
+
+        def unsilence!
+          @__silenced = false
+        end
+
+        def silently(&block)
+          silence!
+          block.call
+          unsilence!
+        end
+
+        def listen(klass, event, timing, &block)
+          event_name = "#{klass}##{event}:#{timing}"
+          Cross::Talk.manager.notify('__new_hook:before', event_name)
+          define_singleton_method event_name, &block
+          Cross::Talk.manager.register(event_name, __get_receiver)
+          Cross::Talk.manager.notify('__new_hook:after', event_name)
+        end
+
+        private
+
+        def __notify_event(method, timing)
+          return if Object.methods.include?(method)
+          return unless public_methods(false).include?(method)
+          return if silenced?
+
+          receiver = __get_receiver
+          event_name = "#{receiver.class}##{method}:#{timing}"
+
+          Cross::Talk.manager.notify(event_name, receiver)
+        end
+
+        def __get_receiver
+          return Celluloid::Actor.current if is_a?(Celluloid)
+          return self
+        end
+      end
+
+      module ClassMethods
+        def registration_hooks
+          @registration_hooks ||= []
+        end
+
+        def listen(klass, event, timing, &block)
+          event_name = "#{klass}##{event}:#{timing}"
+          Cross::Talk.manager.notify('__new_hook:before', event_name)
+          define_hook! event_name, &block
+          registration_hooks << proc { |actor| Cross::Talk.manager.register(event_name, actor) }
+          Cross::Talk.manager.notify('__new_hook:after', event_name)
+        end
+
+        def notify(method_name)
+          class_eval %{
+            alias __old_#{method_name} #{method_name}
+
+            def #{method_name}(*args, &block)
+              __notify_event(#{method_name.inspect}, :before)
+              result = __old_#{method_name}(*args, &block)
+              __notify_event(#{method_name.inspect}, :after)
+              result
+            end
+          }
+
+          send(:private, method_name) if private_instance_methods.include?("__old_#{method_name}".to_sym)
+          send(:protected, method_name) if protected_instance_methods.include?("__old_#{method_name}".to_sym)
+
+          nil
+        end
+
+        def method_added(method)
+          # if we're redefining a method, the lock is set to true, so bug out.
+          return if @lock
+          #don't notify hook methods
+          return if method =~ /^.*#.*:.*$/
+          # don't notify pseudoprivate methods
+          return if method =~ /^__/
+          @lock = true
+          notify(method)
+          @lock = false
+        end
+
+        def define_hook!(method, &block)
+          define_method(method, &block)
+        end
+      end
+    end
+  end
+end

data/lib/cross-talk/manager.rb

@@ -0,0 +1,38 @@
+module Cross
+  module Talk
+    class Manager
+      include Celluloid
+      include Celluloid::Logger
+
+      def initialize
+        @event_table = {}
+      end
+
+      def notify(event, sender)
+        receivers_for(event).each do |receiver|
+          next unless receiver.respond_to?(event)
+          if receiver.respond_to?(:async)
+            receiver.async
+          else
+            receiver
+          end.send(event, sender)
+        end
+      end
+
+      def register(event, receiver)
+        receivers_for(event) << receiver
+        nil
+      end
+
+      private
+
+      attr_reader :event_table
+
+      def receivers_for(event)
+        # We need to ||= here to avoid a weird behavior with Hash.new { [] } --
+        # you can't destructively update the first element to it.
+        event_table[event] ||= Set.new
+      end
+    end
+  end
+end

data/lib/cross-talk/version.rb

@@ -1,5 +1,5 @@
 module Cross
   module Talk
-    VERSION = "0.0.1"
+    VERSION = "0.1.0"
   end
 end

data/spec/helpers/the.rb

@@ -0,0 +1,17 @@
+module RSpec
+  module Cross
+    module Talk
+      module DSL
+        module Macros
+          def the(sym, &block)
+            context sym do
+              subject { if sym.is_a? Class then sym else send sym end }
+              it &block
+            end
+          end
+          alias the_class the
+        end
+      end
+    end
+  end
+end

data/spec/listener_spec.rb

@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+
+describe Cross::Talk::Listener do
+  before :all do
+    class Sender
+      include Celluloid
+      include Cross::Talk
+
+      def test
+      end
+
+      def late
+      end
+
+      protected
+
+      def protected_method
+      end
+
+      private
+
+      def private_method
+      end
+    end
+
+    class Receiver
+      include Celluloid
+      include Cross::Talk
+
+      listen Sender, :test, :after do |sender|
+        @notified = true
+      end
+
+      listen Sender, :private_method, :after do |sender|
+        debug "Should never occur"
+        @notified = true
+      end
+
+      listen Sender, :protected_method, :after do |sender|
+        debug "Should never occur"
+        @notified = true
+      end
+
+      def has_been_notified?
+        @notified
+      end
+    end
+  end
+  after :all do
+    Object.send(:remove_const, :Receiver)
+    Object.send(:remove_const, :Sender)
+  end
+
+  let!(:receiver) { Receiver.new }
+  let!(:other_receiver) { Receiver.new }
+  let!(:sender) { Sender.new }
+
+  subject { receiver }
+
+  context 'late-bound listen' do
+
+    before do
+      receiver.listen(Sender, :late, :after) do |*_|
+        @notified = true
+      end
+    end
+
+    the(:receiver) { should_not have_been_notified }
+    the(:other_receiver) { should_not have_been_notified }
+
+    describe 'when the message is sent' do
+      before { sender.late }
+
+      the(:receiver) { should have_been_notified }
+      the(:other_receiver) { should_not have_been_notified }
+    end
+  end
+
+  describe 'define-time bound listen' do
+    it { should respond_to :"Sender#test:after" }
+    it { should_not have_been_notified }
+
+    describe 'calling the method' do
+      before { sender.test }
+
+      it { should have_been_notified }
+    end
+
+    describe 'calling a private method on the sender' do
+      before { sender.send(:private_method) }
+
+      it { should_not have_been_notified }
+    end
+
+    describe 'calling a protected method on the sender' do
+      before { sender.send(:protected_method) }
+
+      it { should_not have_been_notified }
+    end
+  end
+end

data/spec/manager_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+
+describe Cross::Talk::Manager do
+  subject(:manager) { Cross::Talk.manager }
+
+  before :all do
+    class Receiver
+      include Celluloid
+      include Celluloid::Logger
+
+      def initialize
+        Cross::Talk.manager.register('an_event', Actor.current)
+      end
+
+      def an_event(*_)
+        @notification = true
+      end
+
+      def has_received_notification?
+        @notification
+      end
+    end
+
+    class StupidReceiver
+      include Celluloid
+
+      def initialize
+        Cross::Talk.manager.register('an_event', Actor.current)
+      end
+
+      # I'm dumb because I didn't implement the event method!
+    end
+
+    class NonReceiver
+      include Celluloid
+
+      def initialize
+        Cross::Talk.manager.register('another_event', Actor.current)
+      end
+
+      def another_event(*_)
+      end
+    end
+  end
+
+  after :all do
+    Object.send(:remove_const, :Receiver)
+    Object.send(:remove_const, :NonReceiver)
+    Object.send(:remove_const, :StupidReceiver)
+  end
+
+
+  describe 'api' do
+    it { should respond_to :notify }
+    it { should respond_to :register }
+  end
+
+  let!(:receiver) { Receiver.new }
+  let!(:non_receiver) { NonReceiver.new }
+  let!(:stupid_receiver) { StupidReceiver.new }
+
+  before { manager.notify('an_event', nil) }
+
+  it 'notifies registered receivers when an event occurs' do
+    receiver.should have_received_notification
+  end
+
+  it 'only notifies registered receivers which actually define the event method' do
+    stupid_receiver.should_not have_received :an_event
+  end
+
+  it 'does not notify receivers of other messages of that message' do
+    non_receiver.should_not have_received :an_event
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,32 @@
+require 'bundler/setup'
+
+require 'pry'
+
+require 'cross-talk'
+
+require 'rspec-spies'
+
+require 'coveralls'
+Coveralls.wear!
+
+#include helpers
+Dir["./spec/helpers/*.rb"].each { |file| require file }
+
+#include shared examples
+Dir["./spec/shared/*_examples.rb"].each { |file| require file }
+
+RSpec.configure do |config|
+  config.before do
+    allow_message_expectations_on_nil
+  end
+
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+
+  config.extend(RSpec::Cross::Talk::DSL::Macros)
+end
+
+class RSpec::Mocks::Mock
+  def inspect
+    "double(#{@name.inspect})"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cross-talk
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-11 00:00:00.000000000 Z
-dependencies: []
+date: 2013-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: celluloid
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Pub/Sub Event Management Service for Ruby Classes
 email:
 - jfredett@gmail.com
@@ -19,13 +35,21 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
+- NOTES.md
 - README.md
 - Rakefile
 - cross-talk.gemspec
 - lib/cross-talk.rb
+- lib/cross-talk/listener.rb
+- lib/cross-talk/manager.rb
 - lib/cross-talk/version.rb
+- spec/helpers/the.rb
+- spec/listener_spec.rb
+- spec/manager_spec.rb
+- spec/spec_helper.rb
 homepage: ''
 licenses: []
 post_install_message: 
@@ -38,16 +62,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 635870557992844421
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 635870557992844421
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A Pub/Sub Event Management Service for Ruby Classes
-test_files: []
+test_files:
+- spec/helpers/the.rb
+- spec/listener_spec.rb
+- spec/manager_spec.rb
+- spec/spec_helper.rb