observable_roles 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cb3f4e951c750d292221ff30110a7b1b444643bc
+  data.tar.gz: 2911b86876b569632a45d353af8b52d6cf167ae0
+SHA512:
+  metadata.gz: 7d42563121dd2e1ab84df31cc6401ff9d199daa755673ac7f5b0e7203d0117a93fa171a50f06df87dc065632bc074f8ca2c529eb39a9c49a3ed579a80709604c
+  data.tar.gz: 626fae1055853d4c904f04f647b0284681bb9c03f6762c9d20ca26c49168de5323f5cf95c94687158bfd4500df84d96039c805a31cd07070f41bf95fb231828c

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 2.0.1"
+end
+
+group :test do
+  gem 'rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,64 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.3.5)
+    builder (3.2.2)
+    descendants_tracker (0.0.3)
+    diff-lcs (1.2.5)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    git (1.2.6)
+    github_api (0.11.3)
+      addressable (~> 2.3)
+      descendants_tracker (~> 0.0.1)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 1.2)
+      multi_json (>= 1.7.5, < 2.0)
+      nokogiri (~> 1.6.0)
+      oauth2
+    hashie (2.0.5)
+    highline (1.6.21)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    json (1.8.1)
+    jwt (0.1.11)
+      multi_json (>= 1.5)
+    mini_portile (0.5.2)
+    multi_json (1.9.0)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.1)
+      mini_portile (~> 0.5.0)
+    oauth2 (0.9.3)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 0.1.8)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.5.2)
+    rake (10.1.1)
+    rdoc (4.1.1)
+      json (~> 1.4)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  jeweler (~> 2.0.1)
+  rspec

data/LICENSE.txt

@@ -0,0 +1 @@
+Use however you want, I don't care.

data/README.markdown

@@ -0,0 +1,111 @@
+Observable Roles
+===============================================================================
+Thread safe implementation of the Observable pattern which also supports roles.
+
+
+## Installation
+
+    gem install observable_roles
+
+
+## Usage
+
+Let's start with an example. First, create two classes:
+
+    class DummySubscriber
+      include ObservableRoles::Subscriber
+    end
+
+    class DummyPublisher
+      include ObservableRoles::Publisher
+    end
+
+And now create objects out of them and connect them:
+
+    subscriber     = DummySubscriber.new
+    publisher      = DummyPublisher.new
+    publisher.role = :kitty
+    publisher.subscribe(subscriber)
+
+Let's try triggering an event:
+
+    publisher.publish_event(:myau, "saying myau")
+
+And nothing is going to happen. Why? Because `subscriber` cannot yet handle kitty events.
+He knows nothing about kittens, so even though he is subscribed to that kitty, he ignores it.
+Let's help him learn:
+
+    class DummySubscriber
+      set_observed_publisher_callbacks(
+        kitty: { myau: -> (me, data) { puts data }}
+      )
+    end
+
+`me` in this case is a reference to the object which you might or might not need and `data`
+holds some arbitrary data that an event passes (in this case, a String). Now let's see if it works:
+
+    publisher.publish_event(:myau, "saying myau") # => saying myau 
+
+You can also control which subscriber are getting notified from the publisher itself. Of course,
+the publisher doesn't need to who the subscribers are, but may simply rely on some characteristics,
+essentially using polymorphism. Suppose we only want women to be notified when a kitten myaus, because
+men are too busy hunting. We'll then do this:
+
+
+    class DummyPublisher
+      include ObservableRoles::Publisher
+    end
+
+    class DummySubscriber
+      attr_accessor :gender
+      include ObservableRoles::Subscriber
+      set_observed_publisher_callbacks(
+        kitty: { myau: -> (me, data) { puts "I'm a #{me.gender}, I hear kitten said #{data}" }}
+      )
+    end
+
+    subscriber1        = DummySubscriber.new
+    subscriber2        = DummySubscriber.new
+    publisher          = DummyPublisher.new
+    publisher.role     = :kitty
+    subscriber1.gender = 'female'
+    subscriber2.gender = 'male'
+
+    publisher.subscribe(subscriber1)
+    publisher.subscribe(subscriber1)
+
+    publisher.publish_event(:myau, "saying myau") { |subscriber| subscriber.gender == 'female' }
+
+This will result in only output:
+
+    I'm a female, I hear kitten said myau
+
+
+Both of these examples can be found in `/examples`.
+
+## The following will be a short, but somewhat deeper explanation of the implementation
+
+You have two objects: one is a Subscriber, another one is a Publisher.
+You subscribe a Subscriber to the Publisher events with a Publisher#subscribe.
+However the Subscriber would still ignore anything that Publisher publishes.
+
+In order for it to be notified of the events, you must define callbacks with
+Subscriber.set_observed_publisher_callbacks. These callbacks have the following form:
+
+    role_name: { event_name: -> (me, data) { } }
+
+where `me` is a reference to the Subscriber object and `data` is a hash of some info
+that is passed from the Publisher.
+
+Now `role_name` is a role of the Pubslisher, which can be set as follows:
+
+    publisher.role = :good_cop
+
+Obviously, each role may have many different events and those events may come from various
+publishers who play the same role. This approach is more flexible than the standard Observer pattern,
+since it allows easy many-to-many relationship to be established.
+
+## Thread safety
+
+Each new event that has a callback doesn't execute this callback immediately after said event is caught.
+Instead, it is added into a queue of events, which are then executed one by one. This ensures that each event callback execution doesn't interfere with the other.

data/Rakefile

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "observable_roles"
+  gem.homepage = "http://github.com/snitko/observable_roles"
+  gem.license = "MIT"
+  gem.summary = %Q{Thread-safe Observable pattern implementation with a queue}
+  gem.description = %Q{Thread-safe Observable pattern implementation with a queue}
+  gem.email = "roman.snitko@gmail.com"
+  gem.authors = ["Roman Snitko"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/examples/example1.rb

@@ -0,0 +1,20 @@
+require_relative '../lib/observable_roles'
+
+class DummySubscriber
+  include ObservableRoles::Subscriber
+  set_observed_publisher_callbacks(
+    kitty: { myau: -> (me, data) { puts data }}
+  )
+end
+
+class DummyPublisher
+  include ObservableRoles::Publisher
+end
+
+subscriber     = DummySubscriber.new
+publisher      = DummyPublisher.new
+publisher.role = :kitty
+publisher.subscribe(subscriber)
+
+
+publisher.publish_event(:myau, "saying myau")

data/examples/example2.rb

@@ -0,0 +1,25 @@
+require_relative '../lib/observable_roles'
+
+class DummyPublisher
+  include ObservableRoles::Publisher
+end
+
+class DummySubscriber
+  attr_accessor :gender
+  include ObservableRoles::Subscriber
+  set_observed_publisher_callbacks(
+    kitty: { myau: -> (me, data) { puts "I'm a #{me.gender}, I hear kitten said #{data}" }}
+  )
+end
+
+subscriber1        = DummySubscriber.new
+subscriber2        = DummySubscriber.new
+publisher          = DummyPublisher.new
+publisher.role = :kitty
+subscriber1.gender = 'female'
+subscriber2.gender = 'male'
+
+publisher.subscribe(subscriber1)
+publisher.subscribe(subscriber2)
+
+publisher.publish_event(:myau, "saying myau") { |subscriber| subscriber.gender == 'female' }

data/lib/observable_roles.rb

@@ -0,0 +1,76 @@
+module ObservableRoles
+
+  module Subscriber
+
+    module ClassMethods
+      def set_observed_publisher_callbacks(callbacks)
+        @observed_publisher_callbacks = callbacks
+      end
+      def get_observed_publisher_callbacks
+        @observed_publisher_callbacks
+      end
+    end
+
+    def self.included(base)
+      attr_accessor :subscriber_lock
+      attr_reader   :captured_observable_events
+      base.extend(ClassMethods)
+    end
+
+    def capture_observable_event(role, event_name, data={})
+      return     if role.nil? || event_name.nil?
+      role       = role.to_sym
+      event_name = event_name.to_sym
+      if self.class.get_observed_publisher_callbacks.nil? || self.class.get_observed_publisher_callbacks[role].nil? || self.class.get_observed_publisher_callbacks[role][event_name].nil?
+        return
+      end
+
+      @captured_observable_events ||= []
+      @captured_observable_events.push({ callback: self.class.get_observed_publisher_callbacks[role][event_name], data: data })
+      release_captured_events unless @subscriber_lock
+    end
+
+
+    private
+
+      def release_captured_events
+        @subscriber_lock = true
+        while !@captured_observable_events.empty?
+          e = @captured_observable_events.shift
+          e[:callback].call(self, e[:data])
+        end
+        @subscriber_lock = false
+      end
+
+  end
+
+
+  module Publisher
+
+    def self.included(base)
+      attr_accessor :role
+    end
+
+    def subscribe(s)
+      @observing_subscriber = [] unless @observing_subscriber
+      @observing_subscriber << s
+    end
+
+    def unsubscribe(s)
+      unless @observing_subscriber.blank?
+        @observing_subscriber.delete(s)
+      end
+    end
+
+    def publish_event(event_name, data={})
+      return unless @observing_subscriber
+      @observing_subscriber.each do |s|
+        if !block_given? || yield(s)
+          s.capture_observable_event(role, event_name, data)
+        end
+      end
+    end
+
+  end
+
+end

data/observable_roles.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "observable_roles"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Roman Snitko"]
+  s.date = "2014-03-14"
+  s.description = "Thread-safe Observable pattern implementation with a queue"
+  s.email = "roman.snitko@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "examples/example1.rb",
+    "examples/example2.rb",
+    "lib/observable_roles.rb",
+    "observable_roles.gemspec",
+    "spec/observable_roles_spec.rb"
+  ]
+  s.homepage = "http://github.com/snitko/observable_roles"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "2.0.3"
+  s.summary = "Thread-safe Observable pattern implementation with a queue"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+    else
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    end
+  else
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+  end
+end
+

data/spec/observable_roles_spec.rb

@@ -0,0 +1,56 @@
+require File.dirname(__FILE__) + '/../lib/observable_roles'
+
+class DummySubscriber
+
+  attr_accessor :dumbness_level
+
+  include ObservableRoles::Subscriber
+
+  set_observed_publisher_callbacks(
+    kitty: { myau: -> (me, data) { data.myau }}
+  )
+
+end
+
+class DummyPublisher
+  include ObservableRoles::Publisher
+end
+
+describe ObservableRoles do
+
+  before(:each) do
+    @subscriber     = DummySubscriber.new
+    @publisher      = DummyPublisher.new
+    @publisher.role = :kitty
+    @publisher.subscribe(@subscriber)
+  end
+
+  it "executes a callback when an event is published" do
+    kitty_mock = double()
+    kitty_mock.should_receive(:myau).once
+    @publisher.publish_event(:myau, kitty_mock)
+  end
+
+  it "puts callbacks in a queue and executes them one by one until the queue is empty" do
+    kitty_mock = double()
+    kitty_mock.should_receive(:myau).exactly(3).times
+    @subscriber.subscriber_lock = true
+    3.times { @publisher.publish_event(:myau, kitty_mock) }
+    @subscriber.subscriber_lock = false
+    @subscriber.captured_observable_events.should have(3).items
+    @subscriber.send(:release_captured_events)
+    @subscriber.captured_observable_events.should have(0).items
+  end
+
+  it "published event only to certain filtered subscribers" do
+    subscriber2 = DummySubscriber.new
+    @publisher.subscribe(subscriber2)
+    subscriber2.dumbness_level = 7
+    @subscriber.dumbness_level = 3
+
+    kitty_mock = double()
+    kitty_mock.should_receive(:myau).once
+    @publisher.publish_event(:myau, kitty_mock) { |subscriber| subscriber.dumbness_level < 5 }
+  end
+
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: observable_roles
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roman Snitko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+description: Thread-safe Observable pattern implementation with a queue
+email: roman.snitko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.markdown
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- examples/example1.rb
+- examples/example2.rb
+- lib/observable_roles.rb
+- observable_roles.gemspec
+- spec/observable_roles_spec.rb
+homepage: http://github.com/snitko/observable_roles
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Thread-safe Observable pattern implementation with a queue
+test_files: []