weak_observable 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,5 @@
+--color
+-fp
+-Ilib
+-Ispec
+--require spec_helper

data/CHANGELOG

@@ -0,0 +1,5 @@
+# [v1.0.0][]
+
+Initial release. WeakObservable and Hub!
+
+[v1.0.0]: https://github.com/Burgestrand/weak_observable/tree/v1.0.0

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+gemspec
+gem 'yard'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Kim Burgestrand
+
+MIT License
+
+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.md

@@ -0,0 +1,67 @@
+# WeakObservable
+
+WeakObservable is very similar to Observable from ruby’ standard library, but
+with the very important difference in that it allows it’s subscribers to be
+garbage collected.
+
+## Usage
+
+First, install the gems with rubygems.
+
+```shell
+gem install weak_observable
+```
+
+Now include it onto any object, set up your subscribers and play away!
+
+```ruby
+require 'weak_observable'
+
+class Observer
+  def update(event, *args, &block)
+    puts "[#{event}]: #{args.inspect}"
+  end
+end
+
+class Playlist
+  include WeakObservable::Mixin
+end
+
+# Create an observer to wait for notifications.
+observer = Observer.new
+
+playlist = Playlist.new
+playlist.observers << observer
+playlist.observers.count # => 1
+
+# Notify all observers. Any arguments and given block goes out to them all.
+playlist.observers.notify(:ping)
+# ^ the above ends up calling observer.update(:ping)
+
+# Unassign the variable, allowing the observer to be garbage collected.
+observer = nil
+
+# Some time passes, ruby garbage collection eventually kicks in, and now…
+playlist.observers.count # => 0
+playlist.observers.notify(:ping) # nothing happens, we have no observers.
+```
+
+## Contributing
+
+Please fork the repository and clone it. To get started with development you’ll
+need to install the development dependencies and make sure you can run the
+tests. You can easily install all development dependencies using bundler.
+
+```shell
+$> gem install bundler
+$> bundle install # => installs development dependencies
+```
+
+Once you have the dependencies installed you should be able to run the tests.
+
+```shell
+$> rake
+```
+
+They should be green. Now go ahead and add your tests, add your changes, and push
+it back up to GitHub. Once you feel you’re done create a pull request. Thank you!

data/Rakefile

@@ -0,0 +1,15 @@
+begin
+  require "bundler/gem_tasks"
+rescue LoadError
+end
+
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+  YARD::Rake::YardocTask.new
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/lib/weak_observable.rb

@@ -0,0 +1,89 @@
+require "ref"
+require "weak_observable/version"
+require "weak_observable/mixin"
+require "weak_observable/hub"
+
+# WeakObservable is like the Observable from standard library,
+# with a slightly different API and one important difference:
+# it does not keep any strong references to it’s observers.
+#
+# This is useful in case you want observers, but don’t really
+# care if they are garbage collected or not. Mostly useful for
+# asynchronous callbacks in C extensions or FFI bindings.
+#
+# @example
+#   observable = WeakObservable.new
+#   observer   = Object.new
+#
+#   observable.add(observer)
+#   observable.notify # notifies observable
+#
+#   observer = nil
+#   GC.start # this might garbage collect observer
+#   observable.notify # if observer is garbage collected, this does nothing now
+class WeakObservable
+  def initialize
+    @monitor = Ref::SafeMonitor.new
+    @observers = Ref::WeakValueMap.new
+    @observers.extend(Enumerable)
+    @callbacks = Ref::WeakKeyMap.new
+  end
+
+  # Add an observer.
+  #
+  # @note You cannot add the same observer multiple times. The
+  #       most recent call overrides any earlier calls; because
+  #       of this you can change the method for an observer by
+  #       calling add with a new method.
+  #
+  # @param [#hash] observer
+  # @param [String, Symbol] method
+  # @return observer, as passed in.
+  # @raise ArgumentError if observer does not respodn to method.
+  def add(observer, method = :update)
+    unless observer.respond_to?(method)
+      raise ArgumentError, "#{observer} does not respond to #{method}"
+    end
+
+    synchronize do
+      @callbacks[observer] = method
+      @observers[key(observer)] = observer
+    end
+  end
+
+  # Remove an observer.
+  #
+  # @param [#hash] observer
+  # @return [Object, nil] the observer, or nil if it was not an observer.
+  def delete(observer)
+    synchronize do
+      @callbacks.delete(observer)
+      @observers.delete(key(observer))
+    end
+  end
+
+  # Notify all observers, passing along all arguments and given block.
+  #
+  # @return [Array] all return values.
+  def notify(*args, &block)
+    synchronize do
+      @observers.map do |_, object|
+        callback = @callbacks[object]
+        # rare, but could happen if @callbacks is touched by finalizer
+        # before the @observers
+        next if callback.nil?
+        object.send(callback, *args, &block)
+      end
+    end
+  end
+
+  protected
+
+  def key(observer)
+    observer.hash
+  end
+
+  def synchronize
+    @monitor.synchronize { return yield }
+  end
+end

data/lib/weak_observable/hub.rb

@@ -0,0 +1,98 @@
+require 'set'
+
+class WeakObservable
+  # The Hub is like a hash, mapping a key to an observable.
+  #
+  # Hub holds no strong references. Objects added as observers
+  # for a given key can be garbage collected. When all observers
+  # for a given key has been garbage collected, the observable
+  # for that key is also (eventually) garbage collected.
+  #
+  # This class is useful for having observers for a given key
+  # without necessarily protecting them from being collected by
+  # the garbage collector. Say, if you were mapping a pointer
+  # address to a bunch of ruby objects for FFI callbacks.
+  #
+  # @example
+  #   $hub = WeakObservable::Hub.new
+  #
+  #   def some_callback(address, some_arg)
+  #     $hub[address].notify(some_arg)
+  #   end
+  #
+  #   object = Object.new
+  #   $hub[pointer.address] = object
+  #   SomeFFIBinding.register_callback(object.pointer, :some_callback)
+  class Hub
+    def initialize
+      @mapping = Ref::WeakValueMap.new
+      @monitor = Ref::SafeMonitor.new
+    end
+
+    # Add an object as an observer for updates related to the given key.
+    #
+    # @param [#hash, #eql?] key
+    # @param object
+    # @param [Symbol, String] method
+    # @return object
+    def add(key, object, method = :update)
+      synchronize do
+        observable = (@mapping[key] ||= WeakObservable.new)
+        backrefs_of(object) << observable
+        observable.add(object, method)
+      end
+    end
+
+    # Remove an object as an observer from updates related to the given key.
+    #
+    # @param [#hash, #eql?] key
+    # @param object
+    # @return [Object, nil] object, or nil if it was not an observer for that key
+    def delete(key, object)
+      synchronize do
+        if observable = @mapping[key]
+          backrefs_of(object).delete(observable)
+          observable.delete(object)
+        end
+      end
+    end
+
+    # Notify all observers listening to events on the given key.
+    # All arguments are passed, as well as the given block.
+    #
+    # @param [#hash, #eql?] key
+    # @param args
+    # @return [Array] all return values
+    def notify(key, *args, &block)
+      synchronize do
+        if observable = @mapping[key]
+          observable.notify(*args, &block)
+        end
+      end
+    end
+
+    protected
+
+    def synchronize
+      @monitor.synchronize { return yield }
+    end
+
+    # The observers retain their observable, but the hub does not.
+    # This way we don’t need to garbage collect our mapping, since
+    # when all observers are gone, the observables for the address
+    # they are registered to is also eligible for garbage collection.
+    def backrefs_of(object)
+      # The object may be attached to several hubs, so make sure
+      # we don’t fuck up by mapping our own object_id first.
+      ivar = '@__observable__hubs__'
+      back_hash = object.instance_variable_get(ivar)
+      back_hash ||= Hash.new
+      object.instance_variable_set(ivar, back_hash)
+
+      # An object may also be attached to several addresses within
+      # this hub. We want to allow this, but we don’t care about
+      # the addresses so we just keep a list of observables.
+      back_hash[object_id] ||= Set.new
+    end
+  end
+end

data/lib/weak_observable/mixin.rb

@@ -0,0 +1,7 @@
+class WeakObservable
+  module Mixin
+    def observers
+      @__weak_observable_observers__ ||= WeakObservable.new
+    end
+  end
+end

data/lib/weak_observable/version.rb

@@ -0,0 +1,3 @@
+class WeakObservable
+  VERSION = "1.0.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'weak_observable'

data/spec/weak_observable/hub_spec.rb

@@ -0,0 +1,177 @@
+describe WeakObservable::Hub do
+  let(:observable) { WeakObservable::Hub.new }
+  let(:observer) { stub(:update => 1) }
+  let(:key) { 1337 }
+  let(:other_key) { 0xDEADBEEF }
+
+  describe "#add and #notify" do
+    it "adds an observer for given key" do
+      observer.should_receive(:update)
+
+      observable.add(key, observer)
+      observable.notify(key)
+    end
+
+    it "allows us to specify callback method" do
+      observer.should_receive(:trigger)
+
+      observable.add(key, observer, :trigger)
+      observable.notify(key)
+    end
+
+    it "allows the same observer for multiple keys" do
+      observer.should_receive(:update).twice
+
+      observable.add(key, observer)
+      observable.add(other_key, observer)
+
+      observable.notify(key)
+      observable.notify(other_key)
+    end
+
+    it "allows different methods for different keys" do
+      observer.should_receive(:update).once
+      observer.should_receive(:trigger).once
+
+      observable.add(key, observer)
+      observable.add(other_key, observer, :trigger)
+
+      observable.notify(key)
+      observable.notify(other_key)
+    end
+
+    it "does not allow duplicates for the same key" do
+      observer.should_receive(:update).once
+
+      observable.add(key, observer)
+      observable.notify(key)
+    end
+
+    it "raises an error if observer does not respond to method" do
+      expect { observable.add(key, stub) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#notify" do
+    it "notifies observers only with the same key" do
+      observer.should_not_receive(:update)
+
+      observable.add(key, observer)
+      observable.notify(other_key)
+    end
+
+    it "passes along any args and given block" do
+      observer.should_receive(:update).with(1, 2).and_return do |x, y, &block|
+        block.call(x, y)
+      end
+
+      observable.add(key, observer)
+      observable.notify(key, 1, 2) { |x, y| x + y }.should eq [3]
+    end
+
+    it "returns all return values" do
+      observer1 = stub(:update => 1)
+      observer2 = stub(:update => 2)
+
+      observable.add(key, observer1)
+      observable.add(key, observer2)
+
+      observable.notify(key).should eq [1, 2]
+    end
+  end
+
+  describe "#delete" do
+    it "deletes the observer with the given key" do
+      observer.should_not_receive(:update)
+
+      observable.add(key, observer)
+      observable.delete(key, observer)
+      observable.notify(key).should eq []
+    end
+
+    it "does not crash trying to remove a non-existing observer" do
+      observable.add(key, observer)
+      expect { observable.delete(key, stub) }.to_not raise_error
+    end
+
+    it "does not crash trying to remove an observer with a non-existing key" do
+      expect { observable.delete(key, observer) }.to_not raise_error
+    end
+
+    it "keeps the observer for other keys" do
+      observer1 = stub(:update => 1)
+      observer2 = stub(:update => 2)
+
+      observer2.should_not_receive(:update)
+
+      observable.add(key, observer1)
+      observable.add(other_key, observer2)
+      observable.delete(other_key, observer2)
+
+      observable.notify(key).should eq [1]
+      observable.notify(other_key).should eq []
+    end
+
+    it "does not remove any other observer for a given key" do
+      observer1 = stub(:update => 1)
+      observer2 = stub(:update => 2)
+
+      observer2.should_not_receive(:update)
+
+      observable.add(key, observer1)
+      observable.add(key, observer2)
+      observable.delete(key, observer2)
+
+      observable.notify(key).should eq [1]
+    end
+  end
+
+  specify "observers can be garbage collected" do
+    counter   = 0
+    finalizer = lambda { |_| counter += 1 }
+
+    threshold = 5
+    stretches = 5
+
+    threshold.times do
+      # stub with return value for method cannot be garbage collected.
+      observer = OpenStruct.new(:update => nil)
+      observable.add(key, observer)
+      ObjectSpace.define_finalizer(observer, finalizer)
+    end
+
+    (threshold * stretches).times do
+      GC.start
+      sleep 0.001
+    end
+
+    # if one is garbage collected, we can expect all to eventually be
+    # as well
+    counter.should be > 1
+  end
+
+  specify "entire keys can be garbage collected" do
+    counter   = 0
+    finalizer = lambda { |_| counter += 1 }
+
+    threshold = 5
+    stretches = 5
+
+    threshold.times do |i|
+      # stub with return value for method cannot be garbage collected.
+      observer = OpenStruct.new(:update => nil)
+      observable.add(key + i, observer)
+      ObjectSpace.define_finalizer(observer, finalizer)
+    end
+
+    (threshold * stretches).times do
+      GC.start
+      sleep 0.001
+    end
+
+    # some very intimate introspection here
+    observable.instance_eval do
+      @mapping.to_a.length.should < threshold
+    end
+  end
+end

data/spec/weak_observable/mixin_spec.rb

@@ -0,0 +1,14 @@
+describe WeakObservable::Mixin do
+  let(:klass) { Class.new { include WeakObservable::Mixin } }
+  let(:observable) { klass.new }
+
+  describe "#observers" do
+    it "is a weak observable" do
+      observable.observers.should be_a WeakObservable
+    end
+
+    it "is memoized" do
+      observable.observers.should eql observable.observers
+    end
+  end
+end

data/spec/weak_observable/weak_observable_spec.rb

@@ -0,0 +1,110 @@
+require 'ostruct'
+
+describe WeakObservable do
+  let(:observable) { WeakObservable.new }
+  let(:observer)   { stub(:update => nil) }
+
+  it "has a version" do
+    WeakObservable::VERSION.should be_a String
+  end
+
+  describe "#add and #notify" do
+    it "adds an observer" do
+      observer.should_receive(:update)
+
+      observable.add(observer)
+      observable.notify
+    end
+
+    it "allows us to specify callback method" do
+      observer.should_receive(:trigger)
+
+      observable.add(observer, :trigger)
+      observable.notify
+    end
+
+    it "does not allow duplicates" do
+      observer.should_receive(:update).once
+
+      observable.add(observer)
+      observable.add(observer)
+      observable.notify
+    end
+
+    it "raises an error if observer does not respond to method" do
+      expect { observable.add(stub) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#notify" do
+    it "passes along any args given block" do
+      observer.should_receive(:update).with(1, 2).and_return do |&block|
+        block.call(2)
+      end
+
+      observable.add(observer)
+      observable.notify(1, 2) { |x| x * 2 }.should eq [4]
+    end
+
+    it "returns all return values" do
+      observer1 = stub(:update => 1)
+      observer2 = stub(:update => 2)
+
+      observable.add(observer1)
+      observable.add(observer2)
+
+      observable.notify.should eq [1, 2]
+    end
+  end
+
+  describe "#delete" do
+    it "removes the observer" do
+      observer.should_not_receive(:update)
+
+      observable.add(observer)
+      observable.delete(observer)
+      observable.notify.should eq []
+    end
+
+    it "does not remove any other observer" do
+      observer1 = stub(:update => 1)
+      observer2 = stub(:update => 2)
+
+      observer2.should_not_receive(:update)
+
+      observable.add(observer1)
+      observable.add(observer2)
+      observable.delete(observer2)
+
+      observable.notify.should eq [1]
+    end
+
+    it "does not crash removing a non-existing observer" do
+      expect { observable.delete(observer) }.to_not raise_error
+    end
+  end
+
+  specify "observers can be garbage collected" do
+    counter   = 0
+    finalizer = lambda { |_| counter += 1 }
+
+    threshold = 5
+    stretches = 5
+
+    threshold.times do
+      # stub with return value for method cannot be garbage collected.
+      observer = OpenStruct.new(:update => nil)
+      observable.add(observer)
+      ObjectSpace.define_finalizer(observer, finalizer)
+    end
+
+    (threshold * stretches).times do
+      GC.start
+      sleep 0.001
+    end
+
+    # if one is garbage collected, we can expect all to eventually be
+    # as well
+    counter.should be > 1
+  end
+end

data/weak_observable.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'weak_observable/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "weak_observable"
+  gem.version       = WeakObservable::VERSION
+  gem.authors       = ["Kim Burgestrand"]
+  gem.email         = ["kim@burgestrand.se"]
+  gem.summary       = "Like Observer from the standard library, but allows the subscribers to be garbage collected."
+  gem.description   = <<-DESC.gsub(/ {2,}/, '')
+    Observable::Weak is very similar to Observable from ruby’ standard library, but
+    with the very important difference in that it allows it’s subscribers to be
+    garbage collected.
+  DESC
+  gem.homepage      = "http://github.com/Burgestrand/weak_observable"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'ref', '~> 1.0.0'
+  gem.add_development_dependency 'rspec', '~> 2.11.0'
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: weak_observable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ref
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+description: ! 'Observable::Weak is very similar to Observable from ruby’ standard
+  library, but
+
+  with the very important difference in that it allows it’s subscribers to be
+
+  garbage collected.
+
+'
+email:
+- kim@burgestrand.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- CHANGELOG
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/weak_observable.rb
+- lib/weak_observable/hub.rb
+- lib/weak_observable/mixin.rb
+- lib/weak_observable/version.rb
+- spec/spec_helper.rb
+- spec/weak_observable/hub_spec.rb
+- spec/weak_observable/mixin_spec.rb
+- spec/weak_observable/weak_observable_spec.rb
+- weak_observable.gemspec
+homepage: http://github.com/Burgestrand/weak_observable
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Like Observer from the standard library, but allows the subscribers to be
+  garbage collected.
+test_files:
+- spec/spec_helper.rb
+- spec/weak_observable/hub_spec.rb
+- spec/weak_observable/mixin_spec.rb
+- spec/weak_observable/weak_observable_spec.rb
+has_rdoc: