vcap-concurrency 0.1.0

data/README.md

@@ -0,0 +1,3 @@
+```VCAP::Concurrency''' provides a small set of classes that ease common tasks
+associated with concurrent programming.
+

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "ci/reporter/rake/rspec"
+require "rspec/core/rake_task"
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new("spec") do |t|
+  t.rspec_opts = %w[--color --format documentation]
+end
+
+desc "Run all specs and provide output for ci"
+RSpec::Core::RakeTask.new("spec:ci" => "ci:setup:rspec") do |t|
+  t.rspec_opts = %w[--no-color --format documentation]
+end
+

data/lib/vcap/concurrency.rb

@@ -0,0 +1,4 @@
+require "vcap/concurrency/atomic_var"
+require "vcap/concurrency/proxy"
+require "vcap/concurrency/thread_pool"
+require "vcap/concurrency/version"

data/lib/vcap/concurrency/atomic_var.rb

@@ -0,0 +1,68 @@
+require "thread"
+
+module VCAP
+  module Concurrency
+  end
+end
+
+# A variable that can be queried and updated atomically.
+class VCAP::Concurrency::AtomicVar
+  def initialize(initial_value = nil)
+    @value = initial_value
+    @lock  = Mutex.new
+    @cond  = ConditionVariable.new
+  end
+
+  # @return [Object]  The value bound to this variable.
+  def value
+    @lock.synchronize { @value }
+  end
+
+  # Blocks the calling thread until the current value is different from the
+  # supplied value.
+  #
+  # @param  [Object]  last_value  This method will return once the current
+  #                               value no longer equals last_value.
+  #
+  # @return [Object]  The new value
+  def wait_value_changed(last_value)
+    done = false
+    result = nil
+
+    while !done
+      @lock.synchronize do
+        if last_value == @value
+          @cond.wait(@lock)
+        else
+          done = true
+          result = @value
+        end
+      end
+    end
+
+    result
+  end
+
+  def value=(new_value)
+    mutate { |v| new_value }
+  end
+
+  # Allows the caller to atomically mutate the current value. The new value
+  # will be whatever the supplied block evalutes to.
+  #
+  # @param [Block]  blk  The block to execute while the lock is held. The
+  #                      current value will be passed as the only argument to
+  #                      the block.
+  #
+  # @return [Object]     The result of the block (also the new value bound to
+  #                      the var).
+  def mutate(&blk)
+    @lock.synchronize do
+      @value = blk.call(@value)
+
+      @cond.broadcast
+
+      @value
+    end
+  end
+end

data/lib/vcap/concurrency/errors.rb

@@ -0,0 +1,7 @@
+module VCAP
+  module Concurrency
+    class Error        < StandardError; end
+    class TimeoutError < Error; end
+  end
+end
+

data/lib/vcap/concurrency/promise.rb

@@ -0,0 +1,97 @@
+require "thread"
+
+require "vcap/concurrency/errors"
+
+module VCAP
+  module Concurrency
+  end
+end
+
+# A promise represents the intent to complete a unit of work at some point
+# in the future.
+class VCAP::Concurrency::Promise
+  def initialize
+    @lock   = Mutex.new
+    @cond   = ConditionVariable.new
+    @done   = false
+    @result = nil
+    @error  = nil
+  end
+
+  # Fulfills the promise successfully. Anyone blocking on the result will be
+  # notified immediately.
+  #
+  # @param  [Object]  result   The result of the associated computation.
+  #
+  # @return [nil]
+  def deliver(result = nil)
+    @lock.synchronize do
+      assert_not_done
+
+      @result = result
+      @done = true
+
+      @cond.broadcast
+    end
+
+    nil
+  end
+
+  # Fulfills the promise unsuccessfully. Anyone blocking on the result will
+  # be notified immediately.
+  #
+  # NB: The supplied exception will be re raised in the caller of #resolve().
+  #
+  # @param  [Exception]  The error that occurred while fulfilling the promise.
+  #
+  # @return [nil]
+  def fail(exception)
+    @lock.synchronize do
+      assert_not_done
+
+      @error = exception
+      @done = true
+
+      @cond.broadcast
+    end
+
+    nil
+  end
+
+  # Waits for the promise to be fulfilled. Blocks the calling thread if the
+  # promise has not been fulfilled, otherwise it returns immediately.
+  #
+  # NB: If the promise failed to be fulfilled, the error that occurred while
+  #     fulfilling it will be raised here.
+  #
+  # @param [Integer] timeout_secs  If supplied, wait for no longer than this
+  # value before proceeding. An exception will be raised if the promise hasn't
+  # been fulfilled when the timeout occurs.
+  #
+  # @raise [VCAP::Concurrency::TimeoutError]  Raised if the promise hasn't been
+  # fulfilled after +timeout_secs+ seconds since calling resolve().
+  #
+  # @return [Object]  The result of the associated computation.
+  def resolve(timeout_secs = nil)
+    @lock.synchronize do
+      @cond.wait(@lock, timeout_secs) unless @done
+
+      if !@done
+        emsg = "Timed out waiting on result after #{timeout_secs}s."
+        raise VCAP::Concurrency::TimeoutError.new(emsg)
+      end
+
+      if @error
+        raise @error
+      else
+        @result
+      end
+    end
+  end
+
+  private
+
+  def assert_not_done
+    raise "A promise may only be completed once." if @done
+  end
+end

data/lib/vcap/concurrency/proxy.rb

@@ -0,0 +1,18 @@
+require "thread"
+
+module VCAP
+  module Concurrency
+  end
+end
+
+# A coarse grained thread-safe proxy object
+class VCAP::Concurrency::Proxy
+  def initialize(orig)
+    @orig = orig
+    @lock = Mutex.new
+  end
+
+  def method_missing(meth, *args, &blk)
+    @lock.synchronize { @orig.send(meth, *args, &blk) }
+  end
+end

data/lib/vcap/concurrency/thread_pool.rb

@@ -0,0 +1,152 @@
+require "thread"
+
+require "vcap/concurrency/atomic_var"
+require "vcap/concurrency/promise"
+
+module VCAP
+  module Concurrency
+  end
+end
+
+class VCAP::Concurrency::ThreadPool
+  STOP_SENTINEL = :stop
+
+  STATE_CREATED = 0
+  STATE_STARTED = 1
+  STATE_STOPPED = 2
+
+  def initialize(num_threads)
+    @num_threads = num_threads
+    @threads     = []
+    @work_queue  = Queue.new
+    @state       = STATE_CREATED
+    @pool_lock   = Mutex.new
+    @num_active_tasks = VCAP::Concurrency::AtomicVar.new(0)
+  end
+
+  # Creates all threads in the pool and starts them. Tasks that were enqueued
+  # prior to starting the pool will be processed immediately.
+  def start
+    @pool_lock.synchronize do
+
+      assert_state_in(STATE_CREATED)
+
+      @num_threads.times do
+        @threads << create_worker_thread
+      end
+
+      @state = STATE_STARTED
+    end
+
+    nil
+  end
+
+  # Adds a block that will be executed by a worker thread.
+  #
+  # @param [Block]  blk  The block to be executed by a worker thread.
+  #
+  # @return [VCAP::Concurrent::Promise]  The caller of enqueue() may wait for
+  #                                      the result of blk by calling resolve()
+  def enqueue(&blk)
+    @pool_lock.synchronize do
+      assert_state_in(STATE_CREATED, STATE_STARTED)
+
+      promise = VCAP::Concurrency::Promise.new
+
+      @work_queue.enq([blk, promise])
+
+      promise
+    end
+  end
+
+  # Stops the thread pool politely, allowing existing work to be completed.
+  def stop
+    @pool_lock.synchronize do
+      @num_threads.times { @work_queue.enq(STOP_SENTINEL) }
+
+      @state = STATE_STOPPED
+    end
+
+    nil
+  end
+
+  # Waits for all worker threads to finish executing.
+  def join
+    @pool_lock.synchronize do
+      assert_state_in(STATE_STARTED, STATE_STOPPED)
+    end
+
+    @threads.each { |t| t.join }
+
+    nil
+  end
+
+  # Queues up sentinel values to notify workers to stop, then waits for them
+  # to finish.
+  def shutdown
+    stop
+    join
+
+    nil
+  end
+
+  # Returns the number of tasks that are currently running. This is equivalent
+  # to the number of active threads.
+  #
+  # @return [Integer]
+  def num_active_tasks
+    @num_active_tasks.value
+  end
+
+  # Returns the number of tasks waiting to be processed
+  #
+  # NB: While technically correct, this will include the number of unprocessed
+  #     sentinel tasks after stop() is called.
+  #
+  # @return [Integer]
+  def num_queued_tasks
+    @work_queue.length
+  end
+
+  private
+
+  def do_work # son!
+    while (item = @work_queue.deq) != STOP_SENTINEL
+      blk, promise = item
+
+      @num_active_tasks.mutate { |v| v + 1 }
+
+      result, error, success = nil, nil, true
+      begin
+        result = blk.call
+      rescue => e
+        success = false
+        error = e
+      end
+
+      # This is intentionally outside of the begin/rescue block above. Errors
+      # here are bugs in our code, and shouldn't be propagated back to
+      # whomever enqueued the task.
+      if success
+        promise.deliver(result)
+      else
+        promise.fail(error)
+      end
+
+      @num_active_tasks.mutate { |v| v - 1 }
+    end
+
+    nil
+  end
+
+  def create_worker_thread
+    t = Thread.new { do_work }
+    t.abort_on_exception = true
+
+    t
+  end
+
+  def assert_state_in(*states)
+    raise "Invalid state" unless states.include?(@state)
+  end
+end

data/lib/vcap/concurrency/version.rb

@@ -0,0 +1,5 @@
+module VCAP
+  module Concurrency
+    VERSION = "0.1.0"
+  end
+end

data/spec/atomic_var_spec.rb

@@ -0,0 +1,56 @@
+require "spec_helper"
+
+describe VCAP::Concurrency::AtomicVar do
+  describe "#value" do
+    it "should return the current value" do
+      iv = 5
+      av = VCAP::Concurrency::AtomicVar.new(iv)
+      av.value.should == iv
+    end
+  end
+
+  describe "#value=" do
+    it "should allow the current value to be changed" do
+      av = VCAP::Concurrency::AtomicVar.new(1)
+      nv = 2
+      av.value = nv
+      av.value.should == nv
+    end
+  end
+
+  describe "#mutate" do
+    it "should update the value to the result of the supplied block" do
+      iv = 2
+      av = VCAP::Concurrency::AtomicVar.new(iv)
+      av.mutate { |v| v * v }
+      av.value.should == (iv * iv)
+    end
+  end
+
+  describe "#wait_value_changed" do
+    it "should return immediately if the current value differs from the supplied value" do
+      iv = 1
+      av = VCAP::Concurrency::AtomicVar.new(iv)
+      av.wait_value_changed(2).should == iv
+    end
+
+    it "should block if the current value is the same" do
+      barrier = VCAP::Concurrency::AtomicVar.new(0)
+
+      # We're using the atomic var as a form of synchronization here.
+      t = Thread.new do
+        barrier.wait_value_changed(0)
+
+        barrier.mutate { |v| v + 1 }
+      end
+
+      cur_val = barrier.mutate { |v| v + 1 }
+
+      barrier.wait_value_changed(cur_val)
+
+      t.join
+
+      barrier.value.should == 2
+    end
+  end
+end

data/spec/promise_spec.rb

@@ -0,0 +1,83 @@
+require "spec_helper"
+
+describe VCAP::Concurrency::Promise do
+  let(:promise) { VCAP::Concurrency::Promise.new }
+
+  describe "#deliver " do
+    it "should deliver the supplied result to callers of resolve" do
+      promise.deliver(:done)
+      promise.resolve.should == :done
+    end
+
+    it "should raise an error if called more than once" do
+      promise.deliver
+      expect do
+        promise.deliver
+      end.to raise_error(/completed once/)
+    end
+
+    it "should wake up all threads that are resolving it" do
+      lock = Mutex.new
+      cond = ConditionVariable.new
+      waiting = 0
+      threads = []
+      5.times do |ii|
+        threads << Thread.new do
+          lock.synchronize do
+            waiting += 1
+            cond.signal
+          end
+          promise.resolve
+        end
+      end
+
+      done = false
+      while !done
+        lock.synchronize do
+          if waiting == threads.length
+            done = true
+          else
+            cond.wait(lock)
+          end
+        end
+      end
+
+      promise.deliver
+
+      # join returns nil if timeout occurred and the thread hadn't finished
+      threads.each { |t| t.join(1).should == t }
+    end
+  end
+
+  describe "#fail" do
+    it "should deliver the supplied exception to callers of resolve" do
+      error_text = "test error"
+      promise.fail(RuntimeError.new(error_text))
+      expect do
+        promise.resolve
+      end.to raise_error(/#{error_text}/)
+    end
+
+    it "should raise an error if called more than once" do
+      e = RuntimeError.new("test")
+      promise.fail(e)
+      expect do
+        promise.fail(e)
+      end.to raise_error(/completed once/)
+    end
+  end
+
+  describe "#resolve" do
+    it "should raise an error when a timeout occurs" do
+      start = Time.now
+
+      expect do
+        promise.resolve(0.5)
+      end.to raise_error(VCAP::Concurrency::TimeoutError)
+
+      elapsed = Time.now - start
+
+      elapsed.should be_within(1).of(0.5)
+    end
+  end
+end