pmap 0.0.2

data/.gitignore

@@ -0,0 +1,6 @@
+*~
+*.gem
+.bundle
+.rvmrc
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in pmap.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011 Bruce Adams
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,51 @@
+pmap
+====
+
+This Ruby gem adds two methods to any Enumerable (notably including
+any Array). The two added methods are:
+
+* _pmap_ parallel map
+* _peach_ parallel each
+
+Threading in Ruby has limitations.
+----------------------------------
+
+Matz Ruby 1.8.* uses _green_ threads. All Ruby threads are run within
+a single thread in a single process. A single Ruby program will never
+use more than a single core of a mutli-core machine.
+
+Matz Ruby 1.9.* uses _native_ threads. Each Ruby thread maps directly
+to a thread in the underlying operating system. In theory, a single
+Ruby program can use multpile cores. Unfortunately, there is a global
+interpreter lock _GIL_ that causes single-threaded behavior.
+
+JRuby also uses _native_ threads. JRuby avoids the global interpreter
+lock, allowing a single Ruby program to really use multiple CPU cores.
+
+Threading useful for remote IO, such as HTTP
+--------------------------------------------
+
+Despite the Matz Ruby threading limitations, IO bound actions can
+greatly benefit from multi-threading. A very typical use is making
+multiple HTTP requests in parallel. Issuing those requests in separate
+Ruby threads means the requests will be issued very quickly, well
+before the responses start coming back. As responses come back, they
+will be processed as they arrive.
+
+Example
+-------
+
+Suppose that we have a function get_quote that calls out to a stock
+quote service to get a current stock price. The response time for
+get_quote ranges averages 0.5 seconds.
+
+    stock_symbols = [:ibm, :goog, :appl, :msft, :hp, :orcl]
+
+    # This will take about three seconds;
+    # an eternity if you want to render a web page.
+    stock_quotes = stock_symbols.map {|s| get_quote(s)}
+
+    # Replacing "map" with "pmap" speeds it up.
+    # This will take about half a second;
+    # however long the single slowest response took.
+    stock_quotes = stock_symbols.pmap {|s| get_quote(s)}

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/pmap.rb

@@ -0,0 +1,47 @@
+
+# I'd prefer to create this as a module named "Pmap" and then poke
+# "Pmap" into "Enumerable". I haven't figured out how to do it.
+# So, I directly reopen "Enumerable" and add "p" methods...
+
+require 'thread' unless defined?(Mutex)
+
+# Global variable for the default thread pool size.
+$pmap_default_thread_count ||= 64
+
+module Enumerable
+  # Parallel "map" for any Enumerable.
+  # Requires a block of code to run for each Enumerable item.
+  # [thread_count] is number of threads to create. Optional.
+  def pmap(thread_count=nil, &proc)
+    raise ArgumentError, "thread_count must be at least one." unless
+      thread_count.nil? or (thread_count.respond_to?(:>=) and thread_count >= 1)
+    # This seems overly fussy... (code smell)
+    in_array = self.to_a        # I'm not sure how expensive this is...
+    size = in_array.size
+    thread_count = [thread_count||$pmap_default_thread_count, size].min
+    out_array = Array.new(size)
+    semaphore = Mutex.new
+    index = -1                  # Our use of index is protected by semaphore
+    threads = (0...thread_count).map {
+      Thread.new {
+        i = nil
+        while (semaphore.synchronize {i = (index += 1)}; i < size)
+          out_array[i] = yield(in_array[i])
+        end
+      }
+    }
+    threads.each {|t| t.join}
+    out_array
+  end
+
+  # Parallel "each" for any Enumerable.
+  # Requires a block of code to run for each Enumerable item.
+  # [thread_count] is number of threads to create. Optional.
+  def peach(thread_count=nil, &proc)
+    # This is doing some extra work: building a return array that is
+    # thrown away. How can I share the core code of "pmap" here and omit
+    # the output array creation?
+    pmap(thread_count, &proc)
+    self
+  end
+end

data/lib/pmap/version.rb

@@ -0,0 +1,3 @@
+module Pmap
+  VERSION = "0.0.2"
+end

data/pmap.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'pmap/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'pmap'
+  s.version     = Pmap::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Bruce Adams']
+  s.email       = ['bruce.adams@acm.org']
+  s.homepage    = ''
+  s.summary     = %q{Add parallel methods into Enumerable: pmap and peach}
+  s.description = %q{Add parallel methods into Enumerable: pmap and peach}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+end

data/test/pmap_test.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'pmap'
+
+class Pmap_Test < Test::Unit::TestCase
+
+  def bad_test_noproc_range
+    range = (1..10)
+    assert_equal(range.map, range.pmap)
+  end
+
+  def test_basic_range
+    proc = Proc.new {|x| x*x}
+    range = (1..10)
+    assert_equal(range.map(&proc), range.pmap(&proc))
+  end
+
+  def bad_test_noproc_array
+    array = (1..10).to_a
+    assert_equal(array.map, array.pmap)
+  end
+
+  def test_basic_array
+    proc = Proc.new {|x| x*x*x}
+    array = (1..10).to_a
+    assert_equal(array.map(&proc), array.pmap(&proc))
+  end
+
+  def test_time_savings
+    start = Time.now
+    (1..10).pmap{ sleep 1 }
+    elapsed = Time.now-start
+    assert(elapsed < 2, 'Parallel sleeps too slow: %.1f seconds' % elapsed)
+  end
+
+  def test_bad_thread_limits
+    assert_raise(ArgumentError) {(1..10).pmap(-1){ sleep 1 }}
+    assert_raise(ArgumentError) {(1..10).peach(0){ sleep 1 }}
+    assert_raise(ArgumentError) {(1..10).peach(0.99){ sleep 1 }}
+    assert_raise(ArgumentError) {(1..10).pmap('a'){ sleep 1 }}
+    assert_raise(ArgumentError) {(1..10).peach([1,2,3]){ sleep 1 }}
+  end
+
+  def test_thread_limits
+    start = Time.now
+    (1..10).pmap(5){ sleep 1 }
+    elapsed = Time.now-start
+    assert(elapsed >= 2, 'Limited threads too fast: %.1f seconds' % elapsed)
+    assert(elapsed <  3, 'Parallel sleeps too slow: %.1f seconds' % elapsed)
+  end
+
+  def test_defaut_thread_limit
+    start = Time.now
+    (1..128).pmap{ sleep 1 }
+    elapsed = Time.now-start
+    assert(elapsed >= 2, 'Limited threads too fast: %.1f seconds' % elapsed)
+    assert(elapsed <  3, 'Parallel sleeps too slow: %.1f seconds' % elapsed)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: pmap
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Bruce Adams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-03 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: "Add parallel methods into Enumerable: pmap and peach"
+email: 
+- bruce.adams@acm.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/pmap.rb
+- lib/pmap/version.rb
+- pmap.gemspec
+- test/pmap_test.rb
+has_rdoc: true
+homepage: ""
+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.5.0
+signing_key: 
+specification_version: 3
+summary: "Add parallel methods into Enumerable: pmap and peach"
+test_files: []
+