futurevalue 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm 1.9.2
+export rvm_pretty_print_flag=1

data/Gemfile

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

data/README.markdown

@@ -0,0 +1,93 @@
+Future
+======
+
+A little class to represent a promise of a value that will be provided at a later time. Useful to perform asynchronous operations without fouling the code up with event oriented cruft. A Future::Value can generally be used in place of the future value it represents.
+
+Without Future:
+
+    # Get a number of feed items and concatenate them without Future::Value
+    Benchmark.measure do
+      ['chewy', 'han solo', 'r2d2', 'yoda', 'c3po', 'at-at'].map do |name|
+        JSON.parse(Net::HTTP.get(URI.parse("http://api.twitter.com/search.json?q=rubygems")))['results']
+      end.flatten
+    end.real
+      => 4.5 # seconds
+    
+
+The same code with the requests and processing wrapped in a Future::Value
+
+    # Get a number of feed items and concatenate them *with* Future::Value
+    Benchmark.measure do
+      ['chewy', 'han solo', 'r2d2', 'yoda', 'c3po', 'at-at'].map do |name|
+        Future::Value.new { JSON.parse(Net::HTTP.get(URI.parse("http://api.twitter.com/search.json?q=rubygems")))['results'] }
+      end.flatten
+    end.real
+      => 0.8 # seconds
+
+Installation
+============
+
+Not yet published as a gem, so you'll have to
+
+    git clone git@github.com:simen/future.git
+    cd future
+    rake install
+
+Or if you use the awesomeness that is bundler, you stick this in your Gemfile:
+
+    gem "future", :git => git@github.com:simen/future.git
+
+Usage
+=====
+
+Basically a Future::Value wraps a thread in such a way that it looks like you get the result of a time consuming operation directly. Not until you try to access the result will the thread actually block. In this way you may write asynchronous code that looks like traditional straight down ruby. Especially useful for performing a number of http-requests and let them run in parallel while you perform other tasks.
+
+    # a, b and c are all "calculated" in parallel.
+    a = Future::Value.new { sleep(2); "Hello" }
+    b = Future::Value.new { sleep(3); "from the"}
+    c = Future::Value.new { sleep(1); "future!" }
+    # the moment the content of the values is needed, the main tread blocks until data is ready
+    "#{a} #{b} #{c}"
+      => Hello from the future
+    # total time taken: 3 seconds as opposed to 6 with the traditional way
+
+Future::Threadpool
+==================
+
+Future::Value use a nice and simple threadpool to process the values. By default a pool with seven workers is launched when you request your first Future::Value. If you need to adjust the number of workers you'll do this:
+
+    Future::Value.pool.workers = 12
+
+Remember that if you use Future::Value with ActiveRecord you should visit your database.yml-file and make sure your database connection pool match the number of workers you employ.
+
+If you need to wait for all jobs to finish and shut down the worker threads you do this:
+
+    Future::Value.pool.close
+
+The Future::Threadpool is a useful little class in itself and can be put to good use for purposes besides computing future values. Here's how you use it:
+
+    # Creates a pool with 12 active workers
+    pool = Future::Threadpool.new(12)
+
+    # Resizes the pool by killing or adding worker threads
+    pool.workers = 6
+
+    # Adds a job to the pool
+    pool << proc do
+      # Work you'd like to have done in parallel
+      # Probably involving IO seeing as ruby doesn't really utilize more than one 
+      # cpu core anyway.
+    end
+
+    # Waits for all pending jobs to finish then proceeds to kill the workers one by one
+    pool.close
+
+A word of warning: Future::Threadpool will never be garbage collected if you let it out of your scope without closing it first, because the sleeping workers will keep a reference to it:
+
+    # How to leak memory and threads:
+    pool = Future::Threadpool.new(12)
+    pool = nil
+    # Congrats: you have just leaked an instance of Future::Threadpool + 12 sleeping threads 
+
+So kids, remember this: Close your pools if you plan to lose track of them.
+    

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/TODO

@@ -0,0 +1 @@
+Improve logging and exception handling for workers

data/futurevalue.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "futurevalue/version"
+
+Gem::Specification.new do |s|
+  s.name        = "futurevalue"
+  s.version     = Future::VERSION
+  s.authors     = ["Simen Svale Skogsrud"]
+  s.email       = ["simen@bengler.no"]
+  s.homepage    = ""
+  s.summary     = %q{A promise of a value to be calculated in the future}
+  s.description = %q{A promise of a value to be calculated in the future}
+
+  s.rubyforge_project = "futurevalue"
+
+  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"]
+
+  s.add_development_dependency "rspec"
+end

data/lib/futurevalue.rb

@@ -0,0 +1,2 @@
+require 'future/threadpool'
+require 'future/value'

data/lib/futurevalue/threadpool.rb

@@ -0,0 +1,47 @@
+require 'thread'
+
+module Future
+  class Threadpool
+    def initialize(count)
+      @queue = Queue.new
+      @workers = []      
+      self.workers = count
+    end
+
+    def workers
+      @workers.size
+    end
+
+    def workers=(value)
+      if value > workers
+        (value-workers).times { @workers << new_worker }
+      else
+        (workers-value).times { @queue << proc { @workers.delete(Thread.current); Thread.current.exit } }
+      end
+    end
+
+    def << (job)
+      @queue << job
+    end
+
+    def close
+      self.workers = 0
+      @workers.each(&:join)
+    end
+
+    private
+
+    def new_worker
+      Thread.new do
+        loop do 
+          begin
+            @queue.pop.call 
+          rescue Exception => e
+            puts e
+            puts e.backtrace
+          end
+        end
+      end
+    end
+  end
+end

data/lib/futurevalue/value.rb

@@ -0,0 +1,61 @@
+module Future
+  class Value
+    
+    MINIMUM_WORKERS = 7
+    @pool = Future::Threadpool.new(0)
+
+    class << self
+      attr_reader :pool
+    end
+
+    def initialize(&block)
+      self.class.pool.workers = MINIMUM_WORKERS  if self.class.pool.workers < MINIMUM_WORKERS
+
+      @response_queue = Queue.new
+      self.class.pool << lambda do
+        begin
+          @response_queue << block.call
+        rescue Exception => @exception
+          @response_queue << nil 
+        end
+      end
+    end
+
+    def value            
+      if @response_queue
+        @value = @response_queue.pop
+        @response_queue = nil
+      end
+      raise @exception if @exception
+      @value
+    end
+
+    def ready?
+      @response_queue.nil? || !@response_queue.empty?
+    end
+
+    def method_missing(method, *args, &block)      
+      self.value.send(method, *args, &block) 
+    end
+
+    def to_s
+      self.value.to_s
+    end
+    
+    def to_str
+      self.value.to_str
+    end
+
+    def inspect 
+      if !ready?
+        "#<#{self.class.name} @value=[pending]>"
+      else
+        unless @exception
+          "#<#{self.class.name} @value=#{self.value.inspect}>"
+        else
+          "#<#{self.class.name} #{@exception.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/futurevalue/version.rb

@@ -0,0 +1,3 @@
+module Future
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__)+'/../lib/futurevalue.rb'

data/spec/threadpool_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe Future::Threadpool do
+  it "executes the jobs" do
+    p = Future::Threadpool.new(10)
+    sentinel = nil
+    p << -> { sentinel = "hello" }
+    sleep 0.1
+    sentinel.should eq "hello"
+    p.close
+  end
+
+  it "resizes gracefully" do
+    initial_threadcount = Thread.list.size
+    p = Future::Threadpool.new(10)
+    p.workers = 5
+    sleep 0.1
+    p.workers.should eq 5
+    Thread.list.size.should eq initial_threadcount+5
+    p.workers = 10
+    sleep 0.1
+    p.workers.should eq 10
+    Thread.list.size.should eq initial_threadcount+10
+    p.workers = 0
+    sleep 0.1
+    p.workers.should eq 0
+    Thread.list.size.should eq initial_threadcount
+    p.workers = -1
+    sleep 0.1
+    p.workers.should eq 0
+    Thread.list.size.should eq initial_threadcount
+    p.close
+  end
+
+  it "closes gracefully" do
+    former_threadcount = Thread.list.size
+    p = Future::Threadpool.new(10)
+    20.times { p << -> { 100.times { 1+1 } } }
+    p.close
+    Thread.list.size.should eq former_threadcount
+  end
+
+  it "runs a number of threads" do
+    p = Future::Threadpool.new(10)
+    p.workers.should eq 10
+    p.close
+  end
+
+  it "puts jobs on the queue" do
+    p = Future::Threadpool.new(0)
+    sentinel = nil
+    p << -> { sentinel = "hello" }
+    job = p.instance_variable_get('@queue').pop
+    job.call
+    sentinel.should eq "hello"
+    p.close
+  end
+
+  it "works a lot" do
+    p = Future::Threadpool.new(10)
+    sentinel = []
+    100.times{ p << -> { sentinel << "hepp" } }
+    sleep 0.5
+    sentinel.size.should == 100
+    p.close
+  end
+
+
+
+end

data/spec/value_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'benchmark'
+
+describe Future::Value do
+  it "makes sure a minimum amount of workers are created" do
+    Future::Value.new { 1+1 }
+    sleep 0.1
+    Future::Value.pool.workers == Future::Value::MINIMUM_WORKERS
+  end
+
+  it "forwards missing methods" do
+    v = Future::Value.new { [1,2,3] }
+    v.value
+    v[1].should eq(2)
+  end
+
+  it "should be pending until the data arrives" do
+    v = Future::Value.new { sleep(1); "hello" }
+    v.ready?.should eq(false)
+    v.value
+    v.ready?.should eq(true)
+    v.value.should eq("hello")
+  end
+
+  it "should block until the value is ready upon implicit conversion" do
+    v = Future::Value.new { sleep(0.5); "Hello" }
+    "#{v} World".should eq("Hello World")
+  end
+
+  it "several futures should run together" do
+    # Calculating the sum of several futures that each should take one second to appear should take less than three seconds
+    Future::Value.pool.workers = 50
+    Benchmark.measure { (1..50).map { |i| Future::Value.new { sleep(1); i} }.inject(0){ |r, e| r+e } }.real.should be < 3.0
+  end
+
+  it "reports errors" do 
+    f = Future::Value.new { sleep 1; raise Exception }
+    sleep 0.1
+    ->{f.value}.should raise_error(Exception)    
+    f.ready?.should eq true
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: futurevalue
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Simen Svale Skogsrud
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-29 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70149445959820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70149445959820
+description: A promise of a value to be calculated in the future
+email:
+- simen@bengler.no
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- README.markdown
+- Rakefile
+- TODO
+- futurevalue.gemspec
+- lib/futurevalue.rb
+- lib/futurevalue/threadpool.rb
+- lib/futurevalue/value.rb
+- lib/futurevalue/version.rb
+- spec/spec_helper.rb
+- spec/threadpool_spec.rb
+- spec/value_spec.rb
+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: futurevalue
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A promise of a value to be calculated in the future
+test_files:
+- spec/spec_helper.rb
+- spec/threadpool_spec.rb
+- spec/value_spec.rb