performer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2b01b56f2d0d88ec08d5176a59a2de1dfe8b025e
+  data.tar.gz: 78df656923eac0cad6786f66711c96bf7418b006
+SHA512:
+  metadata.gz: 86dd766848014e7b269fe8cb8e913a3ce8dfd413c38495303938631dfe5f1aa99036e40540704199eea6eacfef25720cd2b1d3646fccd22de54c3ba84729f99e
+  data.tar.gz: b2e0f32c4e36c6f762585873137415aa059c80bebee8467759f56c1cab83bd7be9ef16d0042e5a65ac0bd7df677349ee0f24d88ff5dff0a5d70aa26f6e316d9b

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--require ./spec/spec_helper

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - rbx-2
+  - jruby-19mode
+notifications:
+  email:
+    recipients:
+      - kim@burgestrand.se
+    on_success: change
+    on_failure: change

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 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,33 @@
+# Performer
+
+[![Build Status](https://travis-ci.org/Burgestrand/performer.svg?branch=master)](https://travis-ci.org/Burgestrand/performer)
+[![Code Climate](https://codeclimate.com/github/Burgestrand/performer.png)](https://codeclimate.com/github/Burgestrand/performer)
+[![Gem Version](https://badge.fury.io/rb/performer.png)](http://badge.fury.io/rb/performer)
+
+```
+gem install performer
+```
+
+Performer is a tiny gem for scheduling blocks in a background thread,
+and optionally waiting for the return value.
+
+## Usage
+
+``` ruby
+performer = Performer.new
+
+result = performer.sync { 2 + 1 }
+result # => 3
+
+future = performer.async { 2 + 1 }
+future.value # => 3
+
+future = performer.shutdown do
+  puts "Performer has been properly shutdown."
+end
+
+future.value # wait for shutdown
+```
+
+See documentation for [Performer](http://rdoc.info/github/Burgestrand/performer/master/Performer)
+and [Performer::Task](http://rdoc.info/github/Burgestrand/performer/master/Performer/Task).

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new
+
+desc "Start a console with the code loaded."
+task :console do
+  exec "irb", "-Ilib", "-rperformer"
+end
+
+task default: :spec

data/lib/performer.rb

@@ -0,0 +1,111 @@
+require "performer/version"
+
+# Performer is the main entry point and namespace of the Performer gem.
+# It provides methods for synchronously and asynchronously scheduling
+# blocks for execution in the performer thread, and a way to shut down
+# the performer cleanly.
+#
+# @note The Performer is thread-safe.
+#
+# @example usage
+#   performer = Performer.new
+#   performer.sync { 1 + 1 } # => 2
+#   performer.async { 1 + 1 } # => Performer::Task
+class Performer
+  # All internal errors inherit from Performer::Error.
+  class Error < StandardError; end
+
+  # Raised by {Performer#shutdown}.
+  class ShutdownError < Error; end
+
+  def initialize
+    @queue = Performer::Queue.new
+    @running = true
+    @thread = Thread.new(&method(:run_loop))
+    @shutdown_task = Task.new(lambda do
+      @running = false
+      nil
+    end)
+  end
+
+  # If you ever need to forcefully kill the Performer (don't do that),
+  # here's the thread you'll need to attack.
+  #
+  # @return [Thread]
+  attr_reader :thread
+
+  # Synchronously schedule a block for execution.
+  #
+  # If run from inside a task in the same performer, the block is executed
+  # immediately. You can avoid this behavior by using {#async} instead.
+  #
+  # @param [Integer, nil] timeout (see Task#value)
+  # @yield block to be executed
+  # @return whatever the block returned
+  # @raise [TimeoutError] if waiting for the task to finish timed out
+  # @raise [ShutdownError] if shutdown has been requested
+  def sync(timeout = nil, &block)
+    if Thread.current == @thread
+      yield
+    else
+      async(&block).value(timeout)
+    end
+  end
+
+  # Asynchronously schedule a block for execution.
+  #
+  # @yield block to be executed
+  # @return [Performer::Task]
+  # @raise [ShutdownError] if shutdown has been requested
+  def async(&block)
+    task = Task.new(block)
+    @queue.enq(task) { raise ShutdownError, "performer is shut down" }
+  end
+
+  # Asynchronously schedule a shutdown, allowing all previously queued tasks to finish.
+  #
+  # @note No additional tasks will be accepted after shutdown.
+  #
+  # @return [Performer::Task]
+  # @raise [ShutdownError] if performer is already shutdown
+  def shutdown
+    @queue.close(@shutdown_task) do
+      raise ShutdownError, "performer is shut down"
+    end
+
+    @shutdown_task
+  end
+
+  private
+
+  def run_loop
+    while @running
+      open = @queue.deq do |task|
+        begin
+          task.call
+        rescue Performer::Task::Error
+          # No op. Allows cancelling scheduled tasks.
+        end
+      end
+
+      if not open and @queue.empty?
+        @running = false
+      end
+    end
+  ensure
+    @queue.close
+    until @queue.empty?
+      @queue.deq do |task|
+        begin
+          task.cancel
+        rescue Performer::Task::Error
+          # Shutting down. Don't care.
+        end
+      end
+    end
+  end
+end
+
+require "performer/condition_variable"
+require "performer/queue"
+require "performer/task"

data/lib/performer/condition_variable.rb

@@ -0,0 +1,52 @@
+require "forwardable"
+
+class Performer
+  # A custom ConditionVariable.
+  #
+  # It delegates to ConditionVariable for #wait, #signal and #broadcast,
+  # but also provides a reliable {#wait_until}.
+  #
+  # @api private
+  class ConditionVariable
+    extend Forwardable
+
+    def initialize
+      @condvar = ::ConditionVariable.new
+    end
+
+    def_delegators :@condvar, :wait, :signal, :broadcast
+
+    # Wait until a given condition is true, determined by
+    # calling the given block.
+    #
+    # @note This method will honor the timeout, even in the case
+    #       of spurious wakeups.
+    #
+    # @example usage
+    #   mutex.synchronize do
+    #     condvar.wait_until(mutex, 1) { done? }
+    #   end
+    #
+    # @param [Mutex] mutex
+    # @param [Integer, nil] timeout
+    # @yield for condition
+    def wait_until(mutex, timeout = nil)
+      unless block_given?
+        raise ArgumentError, "no block given"
+      end
+
+      if timeout
+        finished = Time.now + timeout
+        until yield
+          timeout = finished - Time.now
+          break unless timeout > 0
+          wait(mutex, timeout)
+        end
+      else
+        wait(mutex) until yield
+      end
+
+      return self
+    end
+  end
+end

data/lib/performer/queue.rb

@@ -0,0 +1,137 @@
+class Performer
+  # Similar to the stdlib Queue, but with a thread-safe way of closing it down.
+  class Queue
+    def initialize
+      @queue = []
+      @queue_mutex = Mutex.new
+      @queue_cond = Performer::ConditionVariable.new
+      @undefined = {}
+      @open = true
+    end
+
+    # Push an object into the queue, or yield if not possible.
+    #
+    # @example pushing an item onto the queue
+    #   queue.enq(obj) do
+    #     raise "Unable to push #{obj} into queue!"
+    #   end
+    #
+    # @yield if obj could not be pushed onto the queue
+    # @param obj
+    # @return obj
+    # @raise [ArgumentError] if no block given
+    def enq(obj)
+      unless block_given?
+        raise ArgumentError, "no block given"
+      end
+
+      pushed = false
+      @queue_mutex.synchronize do
+        pushed = try_push(obj)
+        @queue_cond.signal
+      end
+      yield if not pushed
+
+      obj
+    end
+
+    # Retrieve an object from the queue, or block until one is available.
+    #
+    # The behaviour is as follows:
+    # - empty, open: block until queue is either not empty, or open
+    # - not empty, open: yield an item off the queue, return true
+    # - not empty, not open: yield an item off the queue, return false
+    # - empty, not open: return false
+    #
+    # @example
+    #   open = queue.deq do |obj|
+    #     # do something with obj
+    #   end
+    #
+    # @yield [obj] an item retrieved from the queue, if available
+    # @return [Boolean] true if queue is open, false if open
+    # @raise [ArgumentError] if no block given
+    def deq
+      unless block_given?
+        raise ArgumentError, "no block given"
+      end
+
+      obj, was_open = @queue_mutex.synchronize do
+        while empty? and open?
+          @queue_cond.wait(@queue_mutex)
+        end
+
+        obj = if empty?
+          undefined
+        else
+          queue.shift
+        end
+
+        [obj, open?]
+      end
+
+      yield obj unless undefined.equal?(obj)
+      was_open
+    end
+
+    # Close the queue, optionally pushing an item onto the queue right before close.
+    #
+    # @example close and enqueue
+    #   queue.close(object) do
+    #     raise "Queue is was already closed!"
+    #   end
+    #
+    # @example close without enqueue
+    #   queue.close # => no need for block, since no argument
+    #
+    # @yield if obj could not be pushed onto the queue
+    # @param [Object, nil] obj
+    # @return [Object, nil] obj
+    # @raise [ArgumentError] if obj given, but no block given
+    def close(obj = undefined)
+      if undefined.equal?(obj)
+        @queue_mutex.synchronize do
+          @open = false
+          @queue_cond.broadcast
+        end
+
+        nil
+      elsif not block_given?
+        raise ArgumentError, "no block given"
+      else
+        pushed = false
+        @queue_mutex.synchronize do
+          pushed = try_push(obj)
+          @open = false
+          @queue_cond.broadcast
+        end
+        yield if not pushed
+
+        obj
+      end
+    end
+
+    # @return [Boolean] true if queue is empty
+    def empty?
+      queue.empty?
+    end
+
+    private
+
+    attr_reader :undefined
+    attr_reader :queue
+
+    def try_push(obj)
+      if open?
+        queue.push(obj)
+        true
+      else
+        false
+      end
+    end
+
+    def open?
+      @open
+    end
+  end
+end

data/lib/performer/task.rb

@@ -0,0 +1,143 @@
+require "timeout"
+
+class Performer
+  # A task is constructed with a callable object (like a proc), and provides ways to:
+  #
+  # - call the contained object, once and only once
+  # - retrieve the value from the execution of the callable, and wait if execution is not finished
+  # - cancel a task, and as such wake up all waiting for the task value
+  #
+  # Furthermore, the Task public API is thread-safe, and a resolved task will never change value.
+  #
+  # @example constructing a task
+  #   task = Task.new(lambda { 1 + 1 })
+  #   worker = Thread.new(task, &:call)
+  #   task.value # => 2
+  class Task
+    # Used for the internal task state machine.
+    #
+    # @api private
+    Transitions = {
+      idle: { executing: true, cancelled: true },
+      executing: { error: true, value: true },
+    }
+
+    # Allows easy capturing of all task-specific errors.
+    class Error < Performer::Error; end
+
+    # Raised in {Task#value} if the task was cancelled.
+    class CancelledError < Error; end
+
+    # Raised from {Task#call} or {Task#cancel} on invariant errors.
+    class InvariantError < Error; end
+
+    # Create a new Task from a callable object.
+    #
+    # @param [#call] callable
+    def initialize(callable)
+      @callable = callable
+
+      @value_mutex = Mutex.new
+      @value_cond = Performer::ConditionVariable.new
+
+      @value = nil
+      @value_type = :idle
+    end
+
+    # Execute the task. Arguments and block are passed on to the callable.
+    #
+    # @note A task can only be called once.
+    # @note A task can not be called after it has been cancelled.
+    # @note A task swallows standard errors during execution, but all other errors are propagated.
+    #
+    # When execution finishes, all waiting for {#value} will be woken up with the result.
+    #
+    # @return [Task] self
+    def call(*args, &block)
+      set(:executing) { nil }
+
+      begin
+        value = @callable.call(*args, &block)
+      rescue => ex
+        set(:error) { ex }
+      rescue Exception => ex
+        set(:error) { ex }
+        raise ex
+      else
+        set(:value) { value }
+      end
+
+      self
+    end
+
+    # Cancel the task. All waiting for {#value} will be woken up with a {CancelledError}.
+    #
+    # @note This cannot be done while the task is executing.
+    # @note This cannot be done if the task has finished executing.
+    #
+    # @param [String] message for the cancellation error
+    def cancel(message = "task was cancelled")
+      set(:cancelled) { CancelledError.new(message) }
+    end
+
+    # Retrieve the value of the task. If the task is not finished, this will block.
+    #
+    # @example waiting with a timeout and a block
+    #   task.value(1) { raise MyOwnError, "Timed out after 1s" }
+    #
+    # @param [Integer, nil] timeout how long to wait for value before timing out, nil if wait forever
+    # @yield if block given, yields instead of raising an error on timeout
+    # @raise [TimeoutError] if waiting timeout was reached, and no block was given
+    def value(timeout = nil)
+      unless done?
+        @value_mutex.synchronize do
+          @value_cond.wait_until(@value_mutex, timeout) { done? }
+        end
+      end
+
+      if value?
+        return @value
+      elsif error? or cancelled?
+        raise @value
+      elsif block_given?
+        yield
+      else
+        raise TimeoutError, "retrieving value timed out after #{timeout}s"
+      end
+    end
+
+    private
+
+    def error?
+      @value_type == :error
+    end
+
+    def value?
+      @value_type == :value
+    end
+
+    def cancelled?
+      @value_type == :cancelled
+    end
+
+    def done?
+      value? or error? or cancelled?
+    end
+
+    # @param [Symbol] type
+    # @yield to set the value
+    def set(type)
+      @value_mutex.synchronize do
+        unless Transitions.fetch(@value_type, {}).has_key?(type)
+          raise InvariantError, "transition from #{@value_type} to #{type} is not allowed"
+        end
+
+        @value_type = type
+        @value = yield
+        @value_cond.broadcast if done?
+
+        @value
+      end
+    end
+  end
+end

data/lib/performer/version.rb

@@ -0,0 +1,4 @@
+class Performer
+  # Current version of Performer.
+  VERSION = "1.0.0"
+end

data/performer.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'performer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "performer"
+  spec.version       = Performer::VERSION
+  spec.authors       = ["Kim Burgestrand"]
+  spec.email         = ["kim@burgestrand.se"]
+  spec.summary       = %q{Schedule blocks in a background thread.}
+  spec.description   = %q{Performer is a tiny gem for scheduling blocks in a background thread,
+and optionally waiting for the return value.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", [">= 3.0.0.rc1", "< 4.0"]
+  spec.add_development_dependency "yard", "~> 0.8"
+end

data/spec/puddle/queue_spec.rb

@@ -0,0 +1,135 @@
+describe Performer::Queue do
+  let(:queue) { Performer::Queue.new }
+  let(:failer) { lambda { raise "This should not happen" } }
+
+  def dequeue(q)
+    yielded = false
+    yielded_value = nil
+
+    open = q.deq do |value|
+      yielded_value = value
+      yielded = true
+    end
+
+    if yielded
+      [open, yielded_value]
+    else
+      [open]
+    end
+  end
+
+  it "maintains FIFO order" do
+    queue.enq(1, &failer)
+    queue.enq(2, &failer)
+
+    dequeue(queue).should eq([true, 1])
+    dequeue(queue).should eq([true, 2])
+  end
+
+  describe "#enq" do
+    it "raises an error if not given an error handling block" do
+      lambda { queue.enq(1) }.should raise_error(ArgumentError, "no block given")
+    end
+
+    it "enqueues an object" do
+      queue.should be_empty
+      queue.enq(1) { raise "enq failed" }
+      queue.should_not be_empty
+    end
+
+    it "yields if equeueing failed" do
+      queue.close
+
+      error = RuntimeError.new("Enqueue failed!")
+      lambda { queue.enq(1) { raise error } }.should raise_error(error)
+      queue.should be_empty
+    end
+  end
+
+  describe "#deq" do
+    it "raises an error if not given an error handling block" do
+      lambda { queue.deq }.should raise_error(ArgumentError, "no block given")
+    end
+
+    context "empty, open" do
+      let(:waiter) do
+        Thread.new(queue) { |q| dequeue(q) }
+      end
+
+      before { wait_until_sleep(waiter) }
+
+      specify "is awoken when an object is added" do
+        queue.enq(1) { raise "enq failed" }
+
+        waiter.value.should eq([true, 1])
+        queue.should be_empty
+      end
+
+      specify "is awoken when closed without an object" do
+        queue.close
+
+        waiter.value.should eq([false])
+        queue.should be_empty
+      end
+
+      specify "is awoken when closed with an object" do
+        queue.close(:thingy) { raise "close failed" }
+
+        waiter.value.should eq([false, :thingy])
+        queue.should be_empty
+      end
+    end
+
+    specify "not empty, open" do
+      queue.enq(1) { raise "enq failed" }
+
+      dequeue(queue).should eq([true, 1])
+      queue.should be_empty
+    end
+
+    context "not empty, not open" do
+      before do
+        queue.enq(1) { raise "enq failed" }
+      end
+
+      specify "when closed without an object" do
+        queue.close
+
+        dequeue(queue).should eq([false, 1])
+        queue.should be_empty
+      end
+
+      specify "when closed with an object" do
+        queue.close(:thingy) { raise "close failed" }
+
+        dequeue(queue).should eq([false, 1])
+        queue.should_not be_empty
+      end
+    end
+
+    specify "empty, not open" do
+      queue.close
+      dequeue(queue).should eq([false])
+    end
+  end
+
+  describe "#close" do
+    it "can be closed multiple times without argument" do
+      queue.close # no errors
+      queue.close # no errors
+    end
+
+    it "yields if closed with an argument that cannot be pushed" do
+      lambda { |b| queue.close(:thingy, &b) }.should_not yield_control
+      lambda { |b| queue.close(:thingy, &b) }.should yield_control
+    end
+
+    it "returns the object queued" do
+      queue.close(:thingy) { raise "close failed" }.should eq(:thingy)
+    end
+
+    it "returns nil if not closed with an object" do
+      queue.close.should eq(nil)
+    end
+  end
+end

data/spec/puddle/task_spec.rb

@@ -0,0 +1,123 @@
+describe Performer::Task do
+  let(:task) { Performer::Task.new(noop) }
+  let(:noop) { lambda { :ok } }
+
+  describe "#call" do
+    it "raises an error if called after a result is available" do
+      task.call
+
+      lambda { task.call }.should raise_error(Performer::Task::InvariantError)
+    end
+
+    it "raises an error when called during execution" do
+      task = Performer::Task.new(lambda { sleep })
+      thread = Thread.new(task, &:call)
+      wait_until_sleep(thread)
+
+      lambda { task.call }.should raise_error(Performer::Task::InvariantError)
+    end
+
+    it "raises an error if called after task was cancelled" do
+      task.cancel
+
+      lambda { task.call }.should raise_error(Performer::Task::InvariantError)
+    end
+
+    it "swallows standard errors" do
+      error = StandardError.new("Hello!")
+      noop.should_receive(:call).and_raise(error)
+
+      task.call.should eql(task)
+      lambda { task.value }.should raise_error(error)
+    end
+
+    it "re-raises non-standard errors" do
+      error = SyntaxError.new("Hello!")
+      noop.should_receive(:call).and_raise(error)
+
+      lambda { task.call }.should raise_error(error)
+      lambda { task.value }.should raise_error(error)
+    end
+  end
+
+  describe "#cancel" do
+    it "raises an error if called after a result is available" do
+      task.call
+
+      lambda { task.cancel }.should raise_error(Performer::Task::InvariantError)
+    end
+
+    it "raises an error when called during execution" do
+      task = Performer::Task.new(lambda { sleep; :ok })
+      thread = Thread.new(task, &:call)
+      wait_until_sleep(thread)
+
+      lambda { task.cancel }.should raise_error(Performer::Task::InvariantError)
+
+      thread.wakeup
+      task.value.should eq(:ok)
+    end
+
+    it "raises an error if called after task was cancelled" do
+      task.cancel
+
+      lambda { task.cancel }.should raise_error(Performer::Task::InvariantError)
+    end
+  end
+
+  describe "#value" do
+    context "task has a result available" do
+      it "returns the value" do
+        task.call
+
+        task.value.should eq(:ok)
+      end
+
+      it "raises the error if the task is an error" do
+        error = RuntimeError.new("Some error")
+        noop.should_receive(:call).and_raise(error)
+        task.call rescue nil
+
+        lambda { task.value }.should raise_error(error)
+      end
+
+      it "raises the error if the task is cancelled" do
+        task.cancel
+
+        lambda { task.value }.should raise_error(Performer::Task::CancelledError)
+      end
+    end
+
+    context "task receives a result later on" do
+      let(:waiter) { Thread.new(task, &:value) }
+      before(:each) { wait_until_sleep(waiter) }
+
+      it "is woken up once a value is available" do
+        task.call
+        waiter.value.should eq(:ok)
+      end
+
+      it "is woken up once an error is available" do
+        error = RuntimeError.new("Some error")
+        noop.should_receive(:call).and_raise(error)
+        task.call rescue nil
+
+        lambda { waiter.value }.should raise_error(error)
+      end
+
+      it "is woken up once task is cancelled" do
+        task.cancel
+
+        lambda { waiter.value }.should raise_error(Performer::Task::CancelledError)
+      end
+    end
+
+    it "yields to the given block on timeout" do
+      task.value(0) { :what }.should eq(:what)
+    end
+
+    it "raises an error on timeout" do
+      lambda { task.value(0) }.should raise_error(TimeoutError)
+    end
+  end
+end

data/spec/puddle_spec.rb

@@ -0,0 +1,98 @@
+describe Performer do
+  let(:performer) { Performer.new }
+
+  specify "VERSION" do
+    Performer::VERSION.should_not be_nil
+  end
+
+  describe "errors" do
+    specify "standard errors in tasks do not crash the performer" do
+      lambda { performer.sync { raise "Hell" } }.should raise_error(/Hell/)
+      performer.sync { 1 + 1 }.should eq(2)
+    end
+
+    specify "cancelled tasks do not crash the performer" do
+      stopgap = Queue.new
+
+      performer.async { stopgap.pop }
+      task = performer.async { 1 + 1 }
+      task.cancel
+      stopgap.push :go
+
+      performer.sync { 1 + 1 }.should eq(2)
+    end
+
+    specify "if the performer crashes, it brings all queued tasks with it" do
+      stopgap = Queue.new
+
+      performer.async { stopgap.pop }
+      performer.async { raise Exception, "Hell" }
+      task = performer.async { :not_ok }
+
+      stopgap.push :go
+
+      lambda { task.value }.should raise_error(Performer::Task::CancelledError)
+    end
+
+    specify "if the performer crashes, it no longer accepts tasks" do
+      lambda { performer.sync { raise Exception, "Hell" } }.should raise_error
+
+      lambda { performer.sync { 1 + 1 } }.should raise_error(Performer::ShutdownError)
+      lambda { performer.shutdown }.should raise_error(Performer::ShutdownError)
+    end
+  end
+
+  describe "#sync" do
+    specify "with timeout" do
+      lambda { performer.sync(0) { sleep } }.should raise_error(TimeoutError)
+    end
+
+    it "yields directly to the task when executed from within the performer" do
+      value = performer.sync do
+        performer.sync { 1 + 2 }
+      end
+
+      value.should eq(3)
+    end
+
+    it "executes a task synchronously in another thread" do
+      thread = performer.sync { Thread.current }
+      thread.should_not eq(Thread.current)
+    end
+  end
+
+  describe "#async" do
+    it "executes a task asynchronously in another thread" do
+      task = performer.async { Thread.current }
+      thread = task.value
+      thread.should_not eq(Thread.current)
+    end
+  end
+
+  describe "#shutdown" do
+    it "performs a clean shutdown, allowing scheduled tasks to finish" do
+      stopgap = Queue.new
+      waiter = Thread.new(Thread.current) do |thread|
+        wait_until_sleep(thread)
+        stopgap.push :go
+      end
+
+      performer.async { stopgap.pop }
+      task = performer.async { :done }
+      term = performer.shutdown
+
+      task.value.should eq(:done)
+      term.value.should eq(nil)
+    end
+
+    it "prevents scheduling additional tasks" do
+      performer.shutdown
+      lambda { performer.sync { 1 + 1 } }.should raise_error(Performer::ShutdownError)
+    end
+
+    it "raises an error if shutdown is already underway" do
+      performer.shutdown
+      lambda { performer.shutdown }.should raise_error(Performer::ShutdownError)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require "performer"
+require "timeout"
+
+module ConcurrencyUtilities
+  def wait_until_sleep(thread)
+    Thread.pass until thread.status == "sleep"
+  end
+end
+
+RSpec.configure do |config|
+  config.include(ConcurrencyUtilities)
+
+  config.expect_with :rspec do |c|
+    c.syntax = :should
+  end
+
+  config.mock_with :rspec do |c|
+    c.syntax = :should
+  end
+
+  config.around(:each) do |example|
+    Timeout.timeout(1, &example)
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: performer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0.rc1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0.rc1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: |-
+  Performer is a tiny gem for scheduling blocks in a background thread,
+  and optionally waiting for the return value.
+email:
+- kim@burgestrand.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/performer.rb
+- lib/performer/condition_variable.rb
+- lib/performer/queue.rb
+- lib/performer/task.rb
+- lib/performer/version.rb
+- performer.gemspec
+- spec/puddle/queue_spec.rb
+- spec/puddle/task_spec.rb
+- spec/puddle_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: Schedule blocks in a background thread.
+test_files:
+- spec/puddle/queue_spec.rb
+- spec/puddle/task_spec.rb
+- spec/puddle_spec.rb
+- spec/spec_helper.rb
+has_rdoc: