contender 0.1.1 → 0.2.0

data/lib/contender.rb

@@ -1,10 +1,54 @@
+require 'atomic'
 require 'forwardable'
+require 'monitor'
+require 'set'
 require 'thread'
 
 require 'contender/version'
-
 require 'contender/errors'
+
+require 'contender/copy_on_write_structure'
+require 'contender/copy_on_write_array'
+require 'contender/copy_on_write_set'
 require 'contender/countdown_latch'
+require 'contender/counter'
 require 'contender/executor'
+require 'contender/executor_service'
 require 'contender/direct_executor'
+require 'contender/future'
+require 'contender/future_task'
 require 'contender/pool'
+require 'contender/thread_factory'
+
+require 'contender/queue'
+require 'contender/linked_queue'
+
+module Contender
+  # http://stackoverflow.com/questions/535721/ruby-max-integer
+  FIXNUM_MAX = (2**(0.size * 8 - 2) - 1)
+  FIXNUM_MIN = -(2**(0.size * 8 - 2))
+
+  # @param [Integer] size
+  # @param [Boolean] allow_timeout
+  # @return [PoolExecutor]
+  def self.fixed_pool(size, allow_timeout = false)
+    executor = Pool::PoolExecutor.new size, size, 0, LinkedQueue.new, simple_thread_factory
+
+    if allow_timeout
+      executor.work_timeout = 60
+      executor.allow_core_timeout = true
+    end
+
+    executor
+  end
+
+  # @return [PoolExecutor]
+  def self.single_pool
+    fixed_pool 1
+  end
+
+  def self.simple_thread_factory
+    SimpleThreadFactory.new
+  end
+end
+

data/lib/contender/copy_on_write_array.rb

@@ -0,0 +1,19 @@
+module Contender
+  # Array that uses copy-on-write to guarantee thread safety
+  #
+  # Use this when read throughput is the primary requirement; write operations will always be
+  # slow due to the need to create a shallow copy of the array to perform operations on.
+  class CopyOnWriteArray
+    include CopyOnWriteStructure
+    include Comparable
+    include Enumerable
+
+    delegate_to Array
+
+    mutators :<<, :[]=, :clear, :collect!, :compact!, :concat, :delete, :delete_at, :delete_if,
+      :fill, :flatten!, :insert, :keep_if, :map!, :pop, :push, :reject!, :replace, :reverse!,
+      :rotate!, :select!, :shift, :shuffle!, :slice!, :sort!, :sort_by!, :uniq!, :unshift
+
+    accessors!
+  end # CopyOnWriteArray
+end

data/lib/contender/copy_on_write_set.rb

@@ -0,0 +1,17 @@
+module Contender
+  # Set that uses copy-on-write to guarantee thread safety
+  #
+  # Use this when read throughput is the primary requirement; write operations will always be
+  # slow due to the need to create a shallow copy of the set to perform operations on.
+  class CopyOnWriteSet
+    include CopyOnWriteStructure
+    include Enumerable
+
+    delegate_to Set
+
+    mutators :<<, :add, :add?, :clear, :collect!, :delete, :delete?, :delete_if, :flatten!,
+      :keep_if, :map!, :merge, :reject!, :replace, :select!, :subtract
+
+    accessors!
+  end # CopyOnWriteSet
+end

data/lib/contender/copy_on_write_structure.rb

@@ -0,0 +1,91 @@
+module Contender
+  # @abstract
+  module CopyOnWriteStructure
+    extend Forwardable
+
+    def self.included(receiver)
+      receiver.send :extend, ClassMethods
+      receiver.send :extend, Forwardable
+    end
+
+    module ClassMethods
+      def accessors(*args)
+        @accessors ||= Set.new
+
+        args.each do |method|
+          @accessors.add method
+
+          def_delegator :current_reference, method
+        end
+      end
+
+      def accessors!
+        methods = Set.new(delegated_type.instance_methods(false))
+
+        methods = methods - @accessors if @accessors
+        methods = methods - @mutators if @mutators
+
+        methods.each do |method|
+          def_delegator :current_reference, method
+        end
+      end
+
+      def mutators(*args)
+        @mutators ||= Set.new
+
+        args.each do |method|
+          @mutators.add method
+
+          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+            def #{method}(*args, &block)
+              update_reference do |current|
+                current.#{method}(*args, &block)
+              end
+            end
+          RUBY_EVAL
+        end
+      end
+
+      alias_method :accessor, :accessors
+      alias_method :mutator, :mutators
+
+      def delegate_to(type)
+        @delegated_type = type
+      end
+
+      attr_reader :delegated_type
+    end
+
+    def initialize(*args, &block)
+      @reference = Atomic.new(self.class.delegated_type.new(*args, &block))
+    end
+
+    protected
+
+    # @return [Object]
+    def current_reference
+      @reference.value
+    end
+
+    # @yield [Object]
+    # @return [Object]
+    def update_reference
+      loop do
+        current = current_reference
+        update = current.clone
+
+        result = yield update
+
+        if result.equal? update
+          # Most write operations return a reference to self
+          # Don't let this reference leak to the caller
+          result = self
+        end
+
+        return result if @reference.compare_and_swap current, update
+
+        # Concurrent modification, retry operation
+      end
+    end
+  end # CopyOnWriteStructure
+end

data/lib/contender/countdown_latch.rb

@@ -2,30 +2,27 @@ 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
+    # @return [Integer]
+    attr_reader :count
+
     # @param [Integer] initial
     # @return [undefined]
     def initialize(initial)
+      raise ArgumentError if initial < 0
+
       @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
+        @count -= 1 if @count > 0
         @condition.broadcast if @count == 0
       end
     end
@@ -37,7 +34,7 @@ module Contender
     # @return [Boolean] True if the latch reached zero, false if the timeout was reached
     def await(timeout = nil)
       @mutex.synchronize do
-        return if @count == 0
+        return true if @count == 0
         @condition.wait @mutex, timeout
 
         @count == 0

data/lib/contender/counter.rb

@@ -0,0 +1,30 @@
+module Contender
+  # Simplified interface to an atomic reference that acts as a counter
+  class Counter < Atomic
+    # @return [undefined]
+    def initialize(initial = 0)
+      super initial
+    end
+
+    # Increments the value of this counter by 1
+    # @return [Integer] The new value of this counter
+    def increment
+      update do |count|
+        count = count + 1
+      end
+    end
+
+    # Decrements the value of this counter by 1
+    # @return [Integer] The new value of this counter
+    def decrement
+      update do |count|
+        count = count - 1
+      end
+    end
+
+    # @return [String]
+    def inspect
+      "#<Contender::Counter = #{value}>"
+    end
+  end # Counter
+end

data/lib/contender/direct_executor.rb

@@ -1,8 +1,11 @@
 module Contender
   # Simple implementation of an executor that executes blocks in the calling thread
   class DirectExecutor < Executor
-    def execute(*arguments, &block)
-      block.call *arguments
+    # @api public
+    # @param [Object] task
+    # @return [undefined]
+    def execute(task = nil, &block)
+      (task || block).call
     end
   end
 end

data/lib/contender/errors.rb

@@ -1,7 +1,26 @@
 module Contender
-  # Raised when an operation times out
-  class OperationTimedOut < Exception; end
+  # Raised when attempting to retrieve the result of a task that was cancelled
+  class CancellationError < RuntimeError; end
 
-  # Raised when an operation was interrupted
-  class OperationInterrupted < Exception; end
+  # Raised when a blocking operation times out
+  class TimeoutError < RuntimeError; end
+
+  # Raised when a thread is interrupted during the execution of a task
+  class InterruptError < ThreadError; end
+
+  # Raised when an operation can not be completed because the object is not in the correct state
+  class InvalidStateError < RuntimeError; end
+
+  # Raised when attempting to retrieve the result of a task that aborted by raising an exception
+  class ExecutionError < RuntimeError
+    # @return [Exception]
+    attr_reader :cause
+
+    # @param [Exception] cause
+    # @return [undefined]
+    def initialize(cause)
+      @cause = cause
+      set_backtrace cause.backtrace
+    end
+  end
 end

data/lib/contender/executor.rb

@@ -12,9 +12,10 @@ module Contender
     # discretion of the implementation.
     #
     # @abstract
-    # @param [Object...] arguments
-    # @param [Proc] block
+    # @param [Object] task
     # @return [undefined]
-    def execute(*arguments, &block); end
-  end
+    def execute(task = nil, &block)
+      raise NotImplementedError
+    end
+  end # Executor
 end

data/lib/contender/executor_service.rb

@@ -0,0 +1,94 @@
+module Contender
+  # @abstract
+  class ExecutorService < Executor
+    # @abstract
+    # @return [undefined]
+    def shutdown
+      raise NotImplementedError
+    end
+
+    # @abstract
+    # @return [Array]
+    def shutdown!
+      raise NotImplementedError
+    end
+
+    # @abstract
+    # @param [Float] timeout
+    # @return [Boolean]
+    def await_termination(timeout)
+      raise NotImplementedError
+    end
+
+    # @abstract
+    # @return [Boolean]
+    def shutdown?
+      raise NotImplementedError
+    end
+
+    # @abstract
+    # @return [Boolean]
+    def terminated?
+      raise NotImplementedError
+    end
+
+    # @api public
+    # @raise [ArgumentError] If neither a block nor callable were given
+    # @param [Object] callable
+    # @return [FutureTask]
+    def submit(callable = nil, &block)
+      callable ||= block
+
+      raise ArgumentError unless callable
+
+      future = future_for callable
+      execute future
+      future
+    end
+
+    # @api public
+    # @param [Array<Object>] tasks
+    # @return [Array<FutureTask>]
+    def invoke_all(tasks)
+      finished = false
+      futures = Array.new
+
+      begin
+        tasks.each do |task|
+          future = create_task_for task
+
+          futures.push future
+          execute future
+        end
+
+        futures.each do |future|
+          unless future.done?
+            begin
+              future.result
+            rescue CancellationError
+            rescue ExecutionError
+              # The caller can deal with these errors
+            end
+          end
+        end
+
+        finished = true
+        futures
+      ensure
+        unless finished
+          futures.each do |future|
+            future.cancel true
+          end
+        end
+      end
+    end
+
+    # @api public
+    # @param [Object] task
+    # @return [FutureTask]
+    def future_for(task)
+      FutureTask.new task
+    end
+  end
+end
+

data/lib/contender/future.rb

@@ -0,0 +1,37 @@
+module Contender
+  # @abstract
+  class Future
+    # @abstract
+    # @param [Boolean] should_interrupt
+    # @return [Boolean] True if this future was cancelled
+    def cancel(should_interrupt)
+      raise NotImplementedError
+    end
+
+    # Returns true if this future was cancelled before it could complete
+    #
+    # @abstract
+    # @return [Boolean]
+    def cancelled?
+      raise NotImplementedError
+    end
+
+    # Returns true if this future was either cancelled or completed
+    #
+    # @abstract
+    # @return [Boolean]
+    def done?
+      raise NotImplementedError
+    end
+
+    # @abstract
+    # @raise [ExecutionError] If the result of the operation was an exception
+    # @raise [TimeoutError] If the timeout was reached before the operation completed
+    # @raise [CancellationError] If the operation was cancelled
+    # @param [Integer] timeout Time to wait for the result
+    # @return [Object] The result of the future
+    def result(timeout = nil)
+      raise NotImplementedError
+    end
+  end
+end