contender 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4277ce364374a3fc397165e20f7775c84828225c
+  data.tar.gz: f8c915d431b9d64ae31a9a9470e78ee83ba8df7d
+SHA512:
+  metadata.gz: 6f252c5ef6200b03e51f3a35edddc150d03ddd01f20cf77f7a7b9d102114f499df03a07db0a5c8833fa3af55a0ad27e0a39ce9aa616ca0edc229853e7741f56c
+  data.tar.gz: 9c65d1d8d32808f2afcb0a66ffa41d995b7af142faeda839fd588d2c833582d63f3421c981bb759f46842e74987950d2f1aed48bb9e3bf892c961f43f26a0a25

data/lib/contender.rb

@@ -0,0 +1,10 @@
+require 'forwardable'
+require 'thread'
+
+require 'contender/version'
+
+require 'contender/errors'
+require 'contender/countdown_latch'
+require 'contender/executor'
+require 'contender/direct_executor'
+require 'contender/pool'

data/lib/contender/countdown_latch.rb

@@ -0,0 +1,45 @@
+module Contender
+  # Synchronization aid that allows one or more threads to wait until a set of operations being
+  # performed in other threads complete
+  class CountdownLatch
+    # @param [Integer] initial
+    # @return [undefined]
+    def initialize(initial)
+      @count = initial
+
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+    end
+
+    # Performs an ordered read of the count for this latch
+    # @return [Integer]
+    def count
+      @mutex.synchronize do
+        @count
+      end
+    end
+
+    # Performs an ordered decrement operation for this latch
+    #
+    # @api public
+    # @return [undefined]
+    def countdown
+      @mutex.synchronize do
+        @count = @count.pred if @count > 0
+        @condition.broadcast
+      end
+    end
+
+    # Waits until either the latch reaches zero or the timeout is reached
+    #
+    # @api public
+    # @param [Float] timeout
+    # @return [undefined]
+    def await(timeout = nil)
+      @mutex.synchronize do
+        return if @count == 0
+        @condition.wait @mutex, timeout
+      end
+    end
+  end # CountdownLatch
+end

data/lib/contender/direct_executor.rb

@@ -0,0 +1,8 @@
+module Contender
+  # Simple implementation of an executor that executes blocks in the calling thread
+  class DirectExecutor < Executor
+    def execute(*arguments, &block)
+      block.call *arguments
+    end
+  end
+end

data/lib/contender/errors.rb

@@ -0,0 +1,7 @@
+module Contender
+  # Raised when an operation times out
+  class OperationTimedOut < Exception; end
+
+  # Raised when an operation was interrupted
+  class OperationInterrupted < Exception; end
+end

data/lib/contender/executor.rb

@@ -0,0 +1,20 @@
+module Contender
+  # Represents a mechanism for executing submitted blocks
+  #
+  # This interface decouples task submission from the way that tasks will be run, including details
+  # of thread use, scheduling, etc.
+  #
+  # @abstract
+  class Executor
+    # Executes the given block at some time in the future
+    #
+    # The block may execute in a new thread, in a pooled thread, or in the calling thread, at the
+    # discretion of the implementation.
+    #
+    # @abstract
+    # @param [Object...] arguments
+    # @param [Proc] block
+    # @return [undefined]
+    def execute(*arguments, &block); end
+  end
+end

data/lib/contender/pool.rb

@@ -0,0 +1,4 @@
+require 'contender/pool/pool_worker'
+require 'contender/pool/task'
+require 'contender/pool/task_queue'
+require 'contender/pool/thread_pool_executor'

data/lib/contender/pool/pool_worker.rb

@@ -0,0 +1,79 @@
+module Contender
+  module Pool
+    # Encapsulates a single worker thread in a thread pool
+    class PoolWorker
+      # @param [ThreadPoolExecutor] pool
+      # @param [TaskQueue] queue
+      # @param [Boolean] non_block
+      # @return [undefined]
+      def initialize(pool, queue, non_block = false)
+        @pool = pool
+        @queue = queue
+        @non_block = non_block
+
+        # Only changed in the worker thread
+        @state = :inactive
+      end
+
+      # @return [undefined]
+      def start
+        return unless inactive?
+
+        @thread = Thread.new do
+          start_worker_loop
+        end
+      end
+
+      # @return [undefined]
+      def join
+        return unless @thread
+        @thread.join
+      end
+
+      # @return [undefined]
+      def interrupt
+        return unless @thread
+        @thread.raise OperationInterrupted
+      end
+
+      # Returns true if the pool worker is inactive
+      # @return [Boolean]
+      def inactive?
+        :inactive == @state
+      end
+
+      # Returns true if the pool worker is waiting for tasks
+      # @return [Boolean]
+      def waiting?
+        :waiting == @state
+      end
+
+      # Returns true if the pool worker is executing a task
+      # @return [Boolean]
+      def executing?
+        :executing == @state
+      end
+
+    protected
+
+      # Loop that is executed in another thread
+      # @return [undefined]
+      def start_worker_loop
+        @state = :waiting
+
+        loop do
+          break if @pool.shutdown_now?
+
+          task = @queue.dequeue @non_block
+          next unless task
+
+          @state = :executing
+          task.execute
+          @state = :waiting
+        end
+      ensure
+        @state = :inactive
+      end
+    end # PoolWorker
+  end # Pool
+end

data/lib/contender/pool/task.rb

@@ -0,0 +1,52 @@
+module Contender
+  module Pool
+    # Encapsulates a task that is either waiting for execution or has been executed
+    class Task
+      # @return [Array] The arguments that the block will be executed with
+      attr_reader :arguments
+
+      # @return [Proc] The block that will be executed by a pool worker
+      attr_reader :block
+
+      # @return [Exception] Exception that occured during task execution
+      attr_reader :exception
+
+      # @param [Proc] block
+      # @param [Array] arguments
+      # @return [undefined]
+      def initialize(block, arguments)
+        @block = block
+        @arguments = arguments
+        @executed = false
+      end
+
+      # Returns true if this task has been executed
+      #
+      # @api public
+      # @return [Boolean]
+      def executed?
+        @executed
+      end
+
+      # Returns true if the execution of this task resulted in an exception
+      #
+      # @api public
+      # @return [Boolean]
+      def failed?
+        !!@exception
+      end
+
+      # Executes the block with the provided arguments
+      # @return [undefined]
+      def execute
+        begin
+          @block.call *@arguments
+        rescue Exception => exception
+          @exception = exception
+        end
+
+        @executed = true
+      end
+    end # Task
+  end # Pool
+end

data/lib/contender/pool/task_queue.rb

@@ -0,0 +1,80 @@
+module Contender
+  module Pool
+    # Simple thread-safe queue that holds tasks waiting for execution
+    class TaskQueue
+      # @return [undefined]
+      def initialize
+        @condition = ConditionVariable.new
+        @mutex = Mutex.new
+        @tasks = Array.new
+      end
+
+      # Performs a volatile read of the size of the task queue
+      #
+      # @api public
+      # @return [Integer]
+      def backlog
+        @tasks.size
+      end
+
+      # Returns true if the task queue is empty
+      #
+      # @api public
+      # @return [Boolean]
+      def empty?
+        @tasks.empty?
+      end
+
+      # Removes any tasks that are queued for execution
+      #
+      # @api public
+      # @return [undefined]
+      def purge
+        @mutex.synchronize do
+          @tasks.clear
+        end
+      end
+
+      # Enqueues the given task for execution
+      #
+      # @api public
+      # @param [Task] task
+      # @return [undefined]
+      def enqueue(task)
+        @mutex.synchronize do
+          @tasks.push task
+          @condition.signal
+        end
+      end
+
+      # Dequeues the first task in line
+      #
+      # If this operation is performed as non-blocking and the queue is empty, then the result
+      # of the dequeue will be +nil+.
+      #
+      # If this operation is performed as blocking, then it will wait until a task is added to the
+      # queue. In the case that the thread pool is shutdown during while a worker is waiting for
+      # the operation to complete, +nil+ will be returned immediately.
+      #
+      # @api public
+      # @param [Boolean] non_block
+      # @return [Task]
+      def dequeue(non_block = false)
+        @mutex.synchronize do
+          if @tasks.empty?
+            return if non_block
+            @condition.wait @mutex
+          end
+
+          @tasks.shift
+        end
+      end
+
+      # Wakes up any threads waiting for tasks to be queued
+      # @return [undefined]
+      def wakeup
+        @condition.broadcast
+      end
+    end # TaskQueue
+  end # Pool
+end

data/lib/contender/pool/thread_pool_executor.rb

@@ -0,0 +1,162 @@
+module Contender
+  module Pool
+    # Executor that uses a cached thread pool to execute tasks in the background
+    class ThreadPoolExecutor < Executor
+      extend Forwardable
+
+      # @param [Hash] options
+      # @return [undefined]
+      def initialize(options = Hash.new)
+        @queue = TaskQueue.new
+
+        @options = {
+          size: 2,
+          non_block: false
+        }.merge options
+
+        @workers = Array.new
+        @mutex = Mutex.new
+
+        @state = :inactive
+      end
+
+      # Defers the execution of the given block until it can be processed by a worker in the
+      # thread pool
+      #
+      # @api public
+      # @param [Object...] arguments
+      # @param [Proc] block
+      # @return [undefined]
+      def execute(*arguments, &block)
+        unless active?
+          raise 'Thread pool has not been started or is shutting down'
+        end
+
+        @queue.enqueue(Task.new(block, arguments))
+      end
+
+      # Returns true if this thread pool is inactive
+      #
+      # @api public
+      # @return [Boolean]
+      def inactive?
+        :inactive == @state
+      end
+
+      # Returns true if this thread pool is active and accepting tasks
+      #
+      # @api public
+      # @return [Boolean]
+      def active?
+        :active == @state
+      end
+
+      # Returns true if this thread pool is waiting to shutdown
+      #
+      # @api public
+      # @return [Boolean]
+      def shutdown?
+        :shutdown == @state
+      end
+
+      # Returns true if this thread pool is shutting down now
+      #
+      # @api public
+      # @return [Boolean]
+      def shutdown_now?
+        :shutdown_now == @state
+      end
+
+      # Starts the thread pool
+      #
+      # @api public
+      # @return [undefined]
+      def start
+        return unless inactive?
+
+        start_workers @options.fetch(:size)
+        @state = :active
+      end
+
+      # Blocks until all queued tasks have been executed, then shuts down the thread pool
+      #
+      # @api public
+      # @return [undefined]
+      def shutdown
+        return unless active?
+
+        @state = :shutdown
+
+        # TODO This is not ideal
+        until @queue.empty?
+          # Wait until the task queue is empty
+          sleep 0.1
+        end
+
+        @state = :shutdown_now
+
+        @queue.wakeup
+        @workers.each do |worker|
+          worker.join
+        end
+
+        cleanup
+      end
+
+      # Shuts down the thread pool instantly, interrupting any executing tasks
+      #
+      # @api public
+      # @return [undefined]
+      def shutdown!
+        return unless active?
+
+        @state = :shutdown_now
+
+        @workers.each do |worker|
+          worker.interrupt
+        end
+
+        cleanup
+      end
+
+      # @!method backlog
+      #   Performs a volatile read on the number of tasks in the queue
+      #   @return [Integer]
+      # @!method empty?
+      #   Returns true if the task queue is empty
+      #   @return [Boolean]
+      # @!method purge
+      #   Removes any tasks that are queued for execution
+      #   @return [undefined]
+      def_delegators :@queue, :backlog, :empty?, :purge
+
+    protected
+
+      # Cleans up pool workers and changes the executor state to inactive
+      # @return [undefined]
+      def cleanup
+        @workers.clear
+        @state = :inactive
+      end
+
+      # Starts the given number of worker threads
+      # @return [undefined]
+      def start_workers(count)
+        @mutex.synchronize do
+          count.times do
+            start_worker
+          end
+        end
+      end
+
+      # Starts a new worker and adds it to pool
+      # @return [undefined]
+      def start_worker
+        worker = PoolWorker.new self, @queue, @options.fetch(:non_block)
+        @workers.push worker
+
+        worker.start
+      end
+    end # ThreadPoolExecutor
+  end # Pool
+end

data/lib/contender/version.rb

@@ -0,0 +1,3 @@
+module Contender
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: contender
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ian Unruh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-13 00:00:00.000000000 Z
+dependencies: []
+description: Simple framework for managing in-process execution
+email: ianunruh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/contender/countdown_latch.rb
+- lib/contender/direct_executor.rb
+- lib/contender/errors.rb
+- lib/contender/executor.rb
+- lib/contender/pool/pool_worker.rb
+- lib/contender/pool/task.rb
+- lib/contender/pool/task_queue.rb
+- lib/contender/pool/thread_pool_executor.rb
+- lib/contender/pool.rb
+- lib/contender/version.rb
+- lib/contender.rb
+homepage: https://github.com/ianunruh/contender
+licenses:
+- Apache 2.0
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Simple framework for managing in-process execution
+test_files: []
+has_rdoc: