group_delegator 0.1.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+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 "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 David Martin
+
+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,120 @@
+= group_delegator
+
+GroupDelegator provides a way to wrap a collection of objects and send method calls to the entire collection.
+* Simple case: Bind a collection of existing objects to a common wrapper that will proxy the method calls to each object
+  Example:
+    require 'group_delegator'
+
+    proxy_numbers = ["1", "2", "3"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_data = proxy_all.to_i
+      #=> {"1"=>1, "2"=>2, "3"=>3}
+
+    #or if you just wanted the integers
+    proxy_integers = proxy_all.to_i
+      #=> [1, 2, 3]
+    puts "proxied to_i: #{proxy_integers.values.inspect}"
+
+* Why not just use Array#map to do the same transformation? i.e.:
+    map_numbers =["1", "2", "3"]
+    mapped_integers = map_numbers.map{|t| t.to_i}
+    puts "mapped to_i: #{mapped_integers.inspect}"
+
+* Let's compare the two approaches in a bit of detail
+    #proxy by group_delegator
+    proxy_numbers = ["1", "2", "3"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_integers = proxy_all.to_i
+    #lets add the string "times" to each number
+    proxy_string = proxy_all<< " times"
+    #then make it uppercase
+    proxy_upcase = proxy_all.upcase
+
+    #tranform collection by Array#map
+    map_numbers =["1", "2", "3"]
+    map_integers = map_numbers.map{|t| t.to_i}
+    #lets add the string "times" to each number
+    map_string = map_numbers.map{|t| t << " times"}
+    #then make it uppercase
+    map_upcase = map_string.map{|t| t.upcase}
+
+    #proxy output
+    puts "Proxy: #{proxy_integers.values.inspect}"
+    puts "Proxy: #{proxy_string.values.inspect}"
+    puts "Proxy: #{proxy_upcase.values.inspect}"
+    #=> Proxy: [1, 2, 3]
+    #=> Proxy: ["1 times", "2 times", "3 times"]
+    #=> Proxy: ["1 TIMES", "2 TIMES", "3 TIMES"]
+
+    #map output
+    puts "Map: #{map_integers.inspect}"
+    puts "Map: #{map_string.inspect}"
+    puts "Map: #{map_upcase.inspect}"
+    #=> Map: [1, 2, 3]
+    #=> Map: ["1 times", "2 times", "3 times"]
+    #=> Map: ["1 TIMES", "2 TIMES", "3 TIMES"]
+ 
+* Although we get to the same point at the end, the route getting there is quite a bit different between the two approaches. Also, I use this example, not because it illustrates how GroupDelegator is useful, but to relate its behavior to something relatively common.
+
+  Things to notice:
+      proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+  This will have all methods called on proxy_all, to be forward to each object in the proxy_numbers array. Any method on <i>proxy_all</i> is applied to each object in <i>proxy_numbers</i>, however, each object does not have to respond to the method (as long as at least one does).
+
+      proxy_all.to_i
+  Apply the method #to_i to all members of proxy_numbers. Which brings us to a feature mentioned above. Say our original array was:
+      ["1", "2", "3", :a, "b", "cat"]
+  With SimpleDelegator, calling #to_i results in a hash, and the values of that hash would be:
+      [1, 2, 3, 0, 0]
+  On the other hand, with Array#map, the result is a NoMethodError.
+
+  What is the structure of the GroupDelegator hash then? It's the source object as the key, with the method result as the value, so #to_i on a SimpleDelegator object returns
+      {"1" => 1, "2" => 2, "3" => 3, "b" => 0, "cat" => 0}
+  Notice :a is not in the hash.  That's because it errored out. Errors are ignored by GroupDelegator (SimpleDelegator is a type of GroupDelegator).
+
+
+* If we are able to work around troublesome objects, it might be useful to identify them
+
+    #Group Delegator proxying
+    proxy_numbers = ["1", "2", "3", :a, "b", "cat"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_integers = proxy_all.to_i
+
+    #find trouble makers
+    trouble_makers = proxy_numbers - proxy_integers.keys
+    #=> [:a]
+
+== Beyond the basics
+So up to now I've made it look like GroupDelegator is just a slightly better alternative to Array#map.  But there's some more advanced things that GroupDelegator can do.  For example
+* Multiple Concurrenty models. The default model is to iterate over object in the collection that's being proxied, but also supported is to spawn a thread for each object, resulting in each method being called to each object concurrently. Especially useful for method calls that might take some time (like http requests). Additionally, it may be useful in certain cases that all is needed is a single response from any object. That too is supported. Finally, it's possible to pass your own block into a GroupDelegator if some other concurrency model is required. 
+* Class level delegation. The SimpleGroupDelegator class works on objects, but if you need to proxy an entire class, you can use the GroupDelegator class.  Calling #new on the proxy class instantiates an object from each of the proxied classes, and returns a proxy_object. That proxy object then works similarly to a SimpleGroupDelegator object.
+
+== Future Plans
+* add new Delegator -> GroupMetaDelegator that passes *all* methods through to sources (including methods from Object and Module). This requires remapping existing default methods to an alias (probably # __gd__method_name)
+* add a method that returns the underlying objects.
+  proxy_all.tap {|s| s}
+  #=> {obj1 => obj1, obj2 => obj2, etc}
+As shown above Object#tap can do this, but perhaps a better solution would be:
+  proxy_all.self  
+  #=> [obj1, obj2, etc]
+* Consider adding a helper method for finding objects that didn't respond to a method.  I'm not quite sure how to do this though (or even if its possible). Note, I don't want a #respond_to? clone, and re-doing the method isn't a good solution since the ojbect state may have changed (affecting its ability to respond to methods)
+
+== Examples on Use (until I can get a full fledged tutorial written up)
+Several examples (included those referenced here) are in the examples directory.
+There's also the specs. Some of the examples and specs have benchmarks showing the differences between the various concurrency models.
+
+
+== Contributing to group_delegator
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 David Martin See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,50 @@
+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://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "group_delegator"
+  gem.homepage = "http://github.com/forforf/group_delegator"
+  gem.license = "MIT"
+  gem.summary = %Q{Delegate to multiple objects concurrently}
+  gem.description = %Q{A wrapper that allows method calls to multiple objects with various concurrency models}
+  gem.email = "dmarti21@gmail.com"
+  gem.authors = ["Dave M"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "group_delegator #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/examples/compare_to_map.rb

@@ -0,0 +1,50 @@
+    require 'group_delegator'
+    proxy_numbers = ["1", "2", "3"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_data = proxy_all.to_i
+      #=> {"1"=>1, "2"=>2, "3"=>3}
+    #or if you just wanted the integers
+    proxy_integers = proxy_all.to_i
+      #=> [1, 2, 3]
+    puts "proxied to_i: #{proxy_integers.values.inspect}"
+
+    #Why not just use map? i.e.:
+    map_numbers =["1", "2", "3"]
+    mapped_integers = map_numbers.map{|t| t.to_i}
+    puts "mapped to_i: #{mapped_integers.inspect}"
+
+    #Let's compare
+    #Group Delegator proxying
+    proxy_numbers = ["1", "2", "3"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_integers = proxy_all.to_i
+    #lets add the string "times" to each number
+    proxy_string = proxy_all<< " times"
+    #then make it uppercase
+    proxy_upcase = proxy_all.upcase
+
+    #map
+    map_numbers =["1", "2", "3"]
+    map_integers = map_numbers.map{|t| t.to_i}
+    #lets add the string "times" to each number
+    map_string = map_numbers.map{|t| t << " times"}
+    #then make it uppercase
+    map_upcase = map_string.map{|t| t.upcase}
+
+
+    #proxy output
+    puts "Proxy: #{proxy_integers.values.inspect}"
+    puts "Proxy: #{proxy_string.values.inspect}"
+    puts "Proxy: #{proxy_upcase.values.inspect}"
+    #=> Proxy: [1, 2, 3]
+    #=> Proxy: ["1 times", "2 times", "3 times"]
+    #=> Proxy: ["1 TIMES", "2 TIMES", "3 TIMES"]
+
+    #map output
+    puts "Map: #{map_integers.inspect}"
+    puts "Map: #{map_string.inspect}"
+    puts "Map: #{map_upcase.inspect}"
+    #=> Map: [1, 2, 3]
+    #=> Map: ["1 times", "2 times", "3 times"]
+    #=> Map: ["1 TIMES", "2 TIMES", "3 TIMES"]
+ 

data/examples/diff_w_map.rb

@@ -0,0 +1,21 @@
+    require 'group_delegator'
+    #Note the last elements of the array
+    proxy_numbers = ["1", "2", "3", :a, "b", "cat"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_data = proxy_all.to_i
+      #=> {"1"=>1, "2"=>2, "3"=>3}
+    #or if you just wanted the integers
+    proxy_integers = proxy_all.to_i
+      #=> [1, 2, 3]
+    puts "proxied to_i: #{proxy_integers.values.inspect}"
+
+    #Why not just use map? i.e.:
+    map_numbers =["1", "2", "3", :a, "b", "cat"]
+    begin
+      mapped_integers = map_numbers.map{|t| t.to_i}
+    rescue NoMethodError
+      puts "We just rescued a NoMehodError in a #map method call"
+      #=> NoMethod Error
+    end
+    puts "mapped to_i: #{mapped_integers.inspect}"
+

data/examples/find_troublemakers.rb

@@ -0,0 +1,12 @@
+    require 'group_delegator'
+
+    #Group Delegator proxying
+    proxy_numbers = ["1", "2", "3", :a, "b", "cat"]
+    proxy_all = SimpleGroupDelegator.new(proxy_numbers)
+    proxy_integers = proxy_all.to_i
+    
+    #find trouble makers
+    trouble_makers = proxy_numbers - proxy_integers.keys
+    #=> [:a]
+
+ 

data/examples/remote_component_update_sim.rb

@@ -0,0 +1,47 @@
+require 'group_delegator'
+
+
+#Imagine we have many objects
+class MyRemoteComponent
+  attr_accessor :status, :version
+
+  def remote_update(version)
+    sleep 0.1  #they're slow to update
+    @version = version
+  end
+
+  def 
+end
+
+components = []
+100.times do
+  stat = [:ok, :minor, :major, :fail][rand(4)]
+  mycomp = MyRemoteComponent.new
+  mycomp.status = [:ok, :minor, :major, :fail][rand(4)]
+  components << mycomp
+end
+
+#let's get the status from each component
+
+#this proxyies all components' methods into a single wrapper
+all_as_one = SimpleGroupDelegator.new(components)
+
+#so we can check the status of all of them in a single line
+all_status = all_as_one.status
+
+#the return result is a hash of the {obj1 => result1, obj2 => result2, etc}
+#if we don't care about the obj we can just grab the values
+p all_status.values
+
+all_as_one.remote_update("v1.0.0")
+
+p all_as_one.version.values.uniq
+#=> ["v1.0.0"]   but that was kinda slow
+
+#lets do them all in parallel then
+all_as_one_v2 = SimpleGroupDelegator.new(components, :threaded)
+
+all_as_one_v2.remote_update("v2.0.0")
+
+p all_as_one_v2.version.values.uniq
+

data/examples/search_examples_with_benchmarks.rb

@@ -0,0 +1,40 @@
+require 'group_delegator'
+require 'open-uri'
+require 'benchmark'
+class Bing
+  QueryString = "http://www.bing.com/search?q="
+  def search(search_string)
+    url = QueryString + URI.escape(search_string)
+    open(url){|f| f.meta} 
+  end
+end
+
+class Google
+  QueryString = "http://www.google.com/search?q="
+  def search(search_string)
+    url = QueryString + URI.escape(search_string)
+    open(url){|f| f.meta}
+  end
+end
+
+class Yahoo
+  QueryString = "http://search.yahoo.com/search?p="
+  def search(search_string)
+    url = QueryString + URI.escape(search_string)
+    open(url){|f| f.meta}
+  end
+end
+
+#default is iterative searchclass IterativeSearch < SimpleDel
+searchers = [Bing.new, Google.new, Yahoo.new]
+search_iteratively = SimpleGroupDelegator.new(searchers)
+search_threaded = SimpleGroupDelegator.new(searchers, :threaded)
+search_first_response = SimpleGroupDelegator.new(searchers, :first_response)
+
+iterative = Benchmark.realtime { search_iteratively.search('stuff') }
+threaded = Benchmark.realtime { search_threaded.search('stuff') }
+first_resp = Benchmark.realtime { search_first_response.search('stuff') }
+
+puts "Iterative Search Time: #{iterative}"
+puts "Threaded Search Time : #{threaded}"
+puts "First Response Time  : #{first_resp}"

data/lib/group_delegator.rb

@@ -0,0 +1,23 @@
+#container for the proxied objects
+require 'group_delegator/source_group'
+
+#retrieves the method data from the source group
+require 'group_delegator/source_helper'
+
+#class to use if one is only interested in instance methods
+require 'group_delegator/group_delegator_instances'
+
+#class to use if one is interested in proxy a complete class
+#- including class methods and instantiation
+require 'group_delegator/group_delegator_klasses'
+
+#for the lazy (like me) set a group delegator class to a default
+#so people don't have to read docs
+class GroupDelegator < GroupDelegatorKlasses
+end
+
+#Also, here's the basic version with a simple name
+#This one only deals with instantiated objects (so
+#no class variables)
+class SimpleGroupDelegator < GroupDelegatorInstances
+end

data/lib/group_delegator/group_delegator_instances.rb

@@ -0,0 +1,32 @@
+#Takes a set of instantiated objects as arguments and will concurently delegate
+#method calls to each instance in the set. Built in concurrency models include:
+# - iterative (iterates the method calls on each object in the set)
+# - threaded (all method calls are done in parallel until all conclude
+# - first response (continues once any in the set complete the method)
+class GroupDelegatorInstances
+  include SourceHelper
+  #unload these methods so the proxy object will handle them
+  [:to_s,:inspect,:=~,:!~,:===].each do |m|
+    undef_method m
+  end
+  
+    #object methods, only
+  def initialize(proxied_objs, concurrency_model = :iterative)
+    @source_objects = [] #contains the delegated objects
+    @source_obj_methods = {} #map of all methods to the objects that use them
+    raise "No source instances set" unless proxied_objs.size > 0
+    sources_data = __set_sources_data(proxied_objs)
+    @source_obj_methods = sources_data[:source_methods]
+    @source_objects = sources_data[:source_objs]
+    @instance_source_group = SourceGroup.new(@source_objects, concurrency_model)
+    self
+  end
+  
+  def method_missing(m, *args, &block)
+    if @source_obj_methods.include? m
+      resp = @instance_source_group.forward(m, *args, &block)
+    else
+      raise NoMethodError, "GroupDelegatorKlasses object can't find the method #{m} in any of its sources"
+    end
+  end
+end