contender 0.1.1 → 0.2.0

data/lib/contender/future_task.rb

@@ -0,0 +1,99 @@
+module Contender
+  class FutureTask < Future
+    # @param [Object] callable
+    # @return [undefined]
+    def initialize(callable)
+      @callable = callable
+
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+
+      @state = :ready
+    end
+
+    # @api public
+    # @param [Boolean] should_interrupt
+    # @return [Boolean] True if this future was cancelled
+    def cancel(should_interrupt)
+      @mutex.synchronize do
+        return false if done?
+
+        if @state == :running
+          return false unless should_interrupt
+          @thread.raise InterruptError
+        end
+
+        @state = :cancelled
+        @condition.broadcast
+      end
+
+      return true
+    end
+
+    # @api public
+    # @return [Boolean]
+    def cancelled?
+      @state == :cancelled
+    end
+
+    # @api public
+    # @return [Boolean]
+    def done?
+      @state == :ran || @state == :cancelled
+    end
+
+    # @api public
+    # @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)
+      @mutex.synchronize do
+        unless done?
+          @condition.wait @mutex, timeout
+
+          unless done?
+            raise TimeoutError, 'The operation did not complete before the given timeout'
+          end
+        end
+
+        if @state == :cancelled
+          raise CancellationError, 'Task was cancelled before it could be completed'
+        end
+      end
+
+      if @exception
+        raise ExecutionError, @exception
+      end
+
+      @result
+    end
+
+    # @api public
+    # @return [undefined]
+    def call
+      @mutex.synchronize do
+        return unless @state == :ready
+
+        @state = :running
+        @thread = Thread.current
+      end
+
+      begin
+        @result = @callable.call
+      rescue => exception
+        @exception = exception
+      end
+
+      @mutex.synchronize do
+        return unless @state == :running
+
+        @state = :ran
+        @condition.broadcast
+      end
+    ensure
+      @thread = nil
+    end
+  end # FutureTask
+end

data/lib/contender/linked_queue.rb

@@ -0,0 +1,338 @@
+module Contender
+  class LinkedQueue < Queue
+    def initialize(capacity = FIXNUM_MAX)
+      raise ArgumentError if capacity <= 0
+
+      @capacity = capacity
+      # Invariant: head.item == nil
+      # Invariant: tail.next == nil
+      @head = @tail = Node.new
+      @count = Counter.new
+
+      @take_lock = Monitor.new
+      @not_empty = @take_lock.new_cond
+      @put_lock = Monitor.new
+      @not_full = @put_lock.new_cond
+    end
+
+    # @param [Object] element
+    # @param [Float] timeout
+    # @return [Boolean]
+    def offer(element, timeout = nil)
+      validate_element element
+
+      count = 0
+      node = Node.new element
+
+      @put_lock.synchronize do
+        if size == @capacity
+          return false unless timeout
+
+          @not_full.wait timeout
+          return false if size == @capacity
+        end
+
+        enqueue node
+        count = @count.increment
+        if count < @capacity
+          @not_full.signal
+        end
+      end
+
+      if count > 0
+        signal_not_empty
+      end
+
+      return true
+    end
+
+    # @param [Object] element
+    # @return [undefined]
+    def put(element)
+      validate_element element
+
+      count = 0
+      node = Node.new element
+
+      @put_lock.synchronize do
+        while size == @capacity
+          @not_full.wait
+        end
+
+        enqueue node
+        count = @count.increment
+        if count < @capacity
+          @not_full.signal
+        end
+      end
+
+      if count > 0
+        signal_not_empty
+      end
+    end
+
+    # @param [Float] timeout
+    # @return [Object]
+    def poll(timeout = nil)
+      count = 0
+      element = nil
+
+      @take_lock.synchronize do
+        if size == 0
+          return unless timeout
+
+          @not_empty.wait timeout
+          return if size == 0
+        end
+
+        element = dequeue
+        count = @count.decrement
+
+        if count > 0
+          @not_empty.signal
+        end
+      end
+
+      if count < @capacity
+        signal_not_full
+      end
+
+      return element
+    end
+
+    # @return [Object]
+    def take
+      count = 0
+      element = nil
+
+      @take_lock.synchronize do
+        while size == 0
+          @not_empty.wait
+        end
+
+        element = dequeue
+        count = @count.decrement
+
+        if count > 0
+          @not_empty.signal
+        end
+      end
+
+      if count < @capacity
+        signal_not_full
+      end
+
+      return element
+    end
+
+    # @return [Object]
+    def peek
+      return if size == 0
+
+      @take_lock.synchronize do
+        first = @head.next
+        return first.element if first
+      end
+    end
+
+    # @return [undefined]
+    def clear
+      raise NotImplementedError
+    end
+
+    # @yield [Object]
+    # @return [undefined]
+    def each(&block)
+      to_a.each &block
+    end
+
+    # @param [Object] element
+    # @return [Boolean]
+    def delete(element)
+      return false if element.nil?
+
+      full_synchronize do
+        trail = @head
+        interior = trail.next
+
+        while interior
+          if element == interior.element
+            unlink interior, trail
+            return true
+          end
+
+          trail = interior
+          interior = interior.next
+        end
+      end
+
+      return false
+    end
+
+    # @param [Array] target
+    # @param [Integer] max_elements
+    # @return [Integer]
+    def drain_to(target, max_elements = FIXNUM_MAX)
+      should_signal = false
+
+      @take_lock.synchronize do
+        n = [max_elements, size].min
+        i = 0
+
+        head = @head
+
+        begin
+          while i < n
+            interior = head.next
+            target.add interior.element!
+            head.next = head
+            head = interior
+
+            i += 1
+          end
+
+          return n
+        ensure
+          if i > 0
+            @head = head
+            should_signal = @count.get_and_add(-i) == capacity
+          end
+        end
+      end
+    ensure
+      signal_not_full if should_signal
+    end
+
+    def include?(element)
+      return false if element.nil?
+
+      full_synchronize do
+        current = @head.next
+        while current
+          return true if element == current.element
+          current = current.next
+        end
+      end
+
+      return false
+    end
+
+    # @return [Integer]
+    def capacity_remaining
+      @capacity - @count.get
+    end
+
+    # @return [Integer]
+    def size
+      @count.get
+    end
+
+    # @return [Array]
+    def to_a
+      full_synchronize do
+        result = Array.new size
+
+        current = @head.next
+        while current
+          result.push current.element
+          current = current.next
+        end
+
+        result
+      end
+    end
+
+  protected
+
+    # @yield
+    # @return [undefined]
+    def full_synchronize
+      @take_lock.mon_enter
+      @put_lock.mon_enter
+
+      begin
+        yield
+      ensure
+        @take_lock.mon_exit
+        @put_lock.mon_exit
+      end
+    end
+
+  private
+
+    def validate_element(element)
+      if element.nil?
+        raise ArgumentError, 'This queue does not support nil elements'
+      end
+    end
+
+    def signal_not_empty
+      @take_lock.synchronize do
+        @not_empty.signal
+      end
+    end
+
+    def signal_not_full
+      @put_lock.synchronize do
+        @not_full.signal
+      end
+    end
+
+    # Must have full lock
+    def unlink(interior, trail)
+      # Release the reference to the element
+      interior.clear_element
+      trail.next = interior.next
+
+      if @tail == interior
+        @tail = trail
+      end
+
+      if @count.decrement < @capacity
+        @not_full.signal
+      end
+    end
+
+    # Must have put lock
+    def enqueue(node)
+      @tail = @tail.next = node
+    end
+
+    # Must have take lock
+    def dequeue
+      head = @head
+      first = head.next
+      head.next = head # help GC
+
+      @head = first
+
+      first.element!
+    end
+
+    # Definition of a node in the linked list
+    class Node
+      # @return [Object]
+      attr_accessor :element
+      # @return [Node]
+      attr_accessor :next
+
+      def initialize(element = nil)
+        @element = element
+      end
+
+      def element!
+        @element.tap do
+          @element = nil
+        end
+      end
+
+      def clear_element
+        @element = nil
+      end
+
+      def clear_next
+        @next = nil
+      end
+    end # Node
+  end # LinkedQueue
+end

data/lib/contender/pool.rb

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

data/lib/contender/pool/pool_executor.rb

@@ -0,0 +1,697 @@
+module Contender
+  module Pool
+    # Executor that uses a thread pool to execute tasks asynchronously
+    #
+    # Made idiomatic by Ian Unruh
+    # Original author is Doug Lea, from the JDK
+    class PoolExecutor < ExecutorService
+      # @return [Integer]
+      attr_reader :core_size
+
+      # @return [Integer]
+      attr_reader :maximum_size
+
+      # @return [Integer]
+      attr_reader :largest_size
+
+      # @return [Boolean]
+      attr_reader :allow_core_timeout
+
+      # @return [Float]
+      attr_reader :work_timeout
+
+      # @return [ThreadFactory]
+      attr_reader :thread_factory
+
+      # @return [Queue]
+      attr_reader :queue
+
+      # @return [RejectionPolicy]
+      attr_accessor :rejection_policy
+
+      # @raise [ArgumentError]
+      #   If the core size is less than zero
+      # @raise [ArgumentError]
+      #   If the maximum size is less than one or less than the core size
+      # @raise [ArgumentError]
+      #   If the work timeout is less than zero
+      #
+      # @param [Integer] core_size
+      # @param [Integer] maximum_size
+      # @param [Float] work_timeout
+      # @param [Queue] queue
+      #   Used to hold tasks that will be executed by the thread pool
+      # @param [ThreadFactory] thread_factory
+      #   Used to create threads for new pool workers
+      #
+      # @return [undefined]
+      def initialize(core_size, maximum_size, work_timeout, queue, thread_factory)
+        raise ArgumentError if core_size < 0
+        raise ArgumentError if maximum_size <= 0 || maximum_size < core_size
+        raise ArgumentError if work_timeout < 0
+
+        @queue = queue
+        @thread_factory = thread_factory
+        @rejection_policy = AbortPolicy.new
+
+        @core_size = core_size
+        @maximum_size = maximum_size
+        @allow_core_timeout = false
+        @work_timeout = work_timeout
+
+        @control = Atomic.new(control_for(RUNNING, 0))
+
+        @monitor = Monitor.new
+        @termination = @monitor.new_cond
+
+        # The following instance variables are guarded by the monitor
+        @workers = Set.new
+
+        @largest_size = 0
+        @completed_task_count = 0
+      end
+
+      # @api public
+      # @raise [TaskRejectionError] If task was rejected by the thread pool
+      # @param [Object] task
+      # @return [undefined]
+      def execute(task = nil, &block)
+        task ||= block
+
+        raise ArgumentError unless task
+
+        return if try_core_worker task
+
+        # Core worker couldn't be started with the task; enqueue it instead
+        control = current_control
+
+        if control.state == RUNNING && @queue.offer(task)
+          after_task_enqueue task
+          return
+        end
+
+        # Either the pool is shutting down or the queue is full
+        unless add_worker false, task
+          reject task
+        end
+      end
+
+      # @!group State management
+
+      # @api public
+      # @return [undefined]
+      def shutdown
+        synchronize do
+          advance_state_to SHUTDOWN
+          interrupt_idle_workers
+          on_shutdown
+        end
+
+        try_terminate
+      end
+
+      # @api public
+      # @return [Array]
+      def shutdown!
+        tasks = Array.new
+
+        synchronize do
+          advance_state_to STOP
+          interrupt_workers
+
+          @queue.drain_to tasks
+        end
+
+        try_terminate
+        tasks
+      end
+
+      # @api public
+      # @param [Float] timeout
+      # @return [Boolean]
+      def await_termination(timeout)
+        synchronize do
+          return true if terminated?
+
+          @termination.wait timeout
+          terminated?
+        end
+      end
+
+      # @api public
+      # @return [Boolean]
+      def shutdown?
+        current_control.state != RUNNING
+      end
+
+      # @api public
+      # @return [Boolean]
+      def terminating?
+        state = current_control.state
+        state > RUNNING && state < TERMINATED
+      end
+
+      # @api public
+      # @return [Boolean]
+      def terminated?
+        current_control.state == TERMINATED
+      end
+
+      # @!endgroup
+
+      # @!group Pool size management
+
+      # @api public
+      # @return [Boolean]
+      def prestart
+        current_control.worker_count < @core_size && add_worker(true)
+      end
+
+      # @api public
+      # @return [Integer]
+      def prestart!
+        count = 0
+
+        while add_worker true
+          count += 1
+        end
+
+        count
+      end
+
+      # @api public
+      # @param [Integer] core_size
+      # @return [undefined]
+      def core_size=(core_size)
+        raise ArgumentError if core_size < 0
+
+        if @maximum_size < core_size
+          @maximum_size = core_size
+        end
+
+        delta = core_size - @core_size
+        @core_size = core_size
+
+        if current_control.worker_count > core_size
+          interrupt_idle_workers
+        elsif delta > 0
+          k = [delta, backlog].min
+
+          # Expand the core size to meet the needs of the work backlog
+          loop do
+            break unless k > 0
+            break unless add_worker false
+
+            k -= 1
+
+            break if @queue.empty?
+          end
+        end
+      end
+
+      # @api public
+      # @param [Integer] maximum_size
+      # @return [undefined]
+      def maximum_size=(maximum_size)
+        raise ArgumentError if maximum_size <= 0 || maximum_size < @core_size
+
+        @maximum_size = maximum_size
+
+        if current_control.worker_count > maximum_size
+          interrupt_idle_workers
+        end
+      end
+
+      # @api public
+      # @param [Boolean] allow_core_timeout
+      # @return [undefined]
+      def allow_core_timeout=(allow_core_timeout)
+        raise ArgumentError if allow_core_timeout && @work_timeout <= 0
+
+        return if allow_core_timeout == @allow_core_timeout
+
+        @allow_core_timeout = allow_core_timeout
+
+        if allow_core_timeout
+          interrupt_idle_workers
+        end
+      end
+
+      # @api public
+      # @param [Float] work_timeout
+      # @return [undefined]
+      def work_timeout=(work_timeout)
+        raise ArgumentError if work_timeout < 0
+        raise ArgumentError if work_timeout == 0 && @allow_core_timeout
+
+        delta = work_timeout - @work_timeout
+        @work_timeout = work_timeout
+
+        if delta < 0
+          interrupt_idle_workers
+        end
+      end
+
+      # @!endgroup
+
+      # @!group Work queue management
+
+      # @api public
+      # @param [Object] task
+      # @return [Boolean]
+      def remove(task)
+        removed = @queue.delete task
+        try_terminate
+        removed
+      end
+
+      # @!endgroup
+
+      # @!group Statistics
+
+      # @api public
+      # @return [Integer]
+      def backlog
+        @queue.size
+      end
+
+      # @api public
+      # @return [Integer]
+      def current_size
+        synchronize do
+          return 0 if current_control.state > STOP
+          return @workers.size
+        end
+      end
+
+      # @api public
+      # @return [Integer]
+      def active_count
+        synchronize do
+          @workers.count do |worker|
+            worker.locked?
+          end
+        end
+      end
+
+      # @api public
+      # @return [Integer]
+      def total_tasks
+        completed_tasks + backlog
+      end
+
+      # @api public
+      # @return [Integer]
+      def completed_tasks
+        synchronize do
+          total = @completed_task_count
+
+          @workers.each do |worker|
+            total += worker.completed_task_count
+          end
+
+          total
+        end
+      end
+
+      # @!endgroup
+
+      # @api public
+      # @return [String]
+      def to_s
+        state = current_control.state
+
+        state_text = "Running" if state == RUNNING
+        state_text = "Shutting down" if state > RUNNING && state < TERMINATED
+        state_text = "Terminated" if state == TERMINATED
+
+        "{#{state_text}" +
+        ", pool size = #{current_size}" +
+        ", active threads = #{active_count}" +
+        ", queued tasks = #{backlog}" +
+        ", completed tasks = #{completed_tasks}" +
+        "}"
+      end
+
+    protected
+
+      # @param [Object] task
+      # @param [Thread] thread
+      # @return [undefined]
+      def before_execution(task, thread); end
+
+      # @param [Object] task
+      # @param [Exception] exception
+      # @return [undefined]
+      def after_execution(task, exception); end
+
+      # @return [undefined]
+      def on_shutdown; end
+
+      # @return [undefined]
+      def on_termination; end
+
+      # @param [Object] task
+      # @return [undefined]
+      def reject(task)
+        @rejection_policy.on_rejection task, self
+      end
+
+      # @return [undefined]
+      def try_terminate
+        loop do
+          control = current_control
+
+          state = control.state
+          worker_count = control.worker_count
+
+          return if state == RUNNING || state > STOP
+          return if state == SHUTDOWN && @queue.size > 0
+
+          if worker_count > 0
+            # Eligible to terminate, but there are still workers left
+            interrupt_idle_workers true
+            return
+          end
+
+          break if @control.compare_and_swap(control, control_for(TIDYING, 0))
+        end
+
+        terminate
+      end
+
+      # @return [PoolControl]
+      def current_control
+        @control.value
+      end
+
+    private
+
+      RUNNING = 0
+      SHUTDOWN = 1
+      STOP = 2
+      TIDYING = 3
+      TERMINATED = 4
+
+      # @param [Integer] state
+      # @param [Integer] worker_count
+      # @return [PoolControl]
+      def control_for(state, worker_count)
+        PoolControl.new state, worker_count
+      end
+
+      # @param [Integer] state
+      # @return [undefined]
+      def advance_state_to(state)
+        loop do
+          ctl = current_control
+          return if ctl.state >= state ||
+            @control.compare_and_swap(ctl, control_for(state, ctl.worker_count))
+        end
+      end
+
+      # @param [PoolControl] exp
+      # @return [Boolean]
+      def compare_and_increment_worker_count(exp)
+        @control.compare_and_swap(exp, control_for(exp.state, exp.worker_count + 1))
+      end
+
+      # @param [PoolControl] exp
+      # @return [Boolean]
+      def compare_and_decrement_worker_count(exp)
+        @control.compare_and_swap(exp, control_for(exp.state, exp.worker_count - 1))
+      end
+
+      # @return [undefined]
+      def decrement_worker_count
+        loop do
+          return if compare_and_decrement_worker_count current_control
+        end
+      end
+
+      # @yield
+      # @return [undefined]
+      def synchronize(&block)
+        @monitor.synchronize &block
+      end
+
+      # @return [undefined]
+      def interrupt_workers
+        synchronize do
+          @workers.each do |worker|
+            worker.interrupt
+          end
+        end
+      end
+
+      # @param [Boolean] single
+      # @return [undefined]
+      def interrupt_idle_workers(single = false)
+        synchronize do
+          @workers.each do |worker|
+            if worker.try_lock
+              worker.interrupt
+              worker.unlock
+            end
+
+            break if single
+          end
+        end
+      end
+
+      # @return [undefined]
+      def terminate
+        synchronize do
+          begin
+            on_termination
+          ensure
+            @control.value = control_for(TERMINATED, 0)
+            @termination.broadcast
+          end
+        end
+      end
+
+      # @param [Object] first_task
+      # @return [Boolean]
+      def try_core_worker(first_task)
+        if current_control.worker_count < @core_size
+          add_worker true, first_task
+        end
+      end
+
+      # @param [Object] task
+      # @return [undefined]
+      def after_task_enqueue(task)
+        control = current_control
+        if control.state != RUNNING && remove(task)
+          # The pool state changed after the task got enqueued, but the task was able to be
+          # removed from the work queue before it could be processed
+          reject task
+        elsif control.worker_count == 0
+          # There are no workers to process the task, add one
+          add_worker false
+        end
+      end
+
+      # @param [Boolean] core
+      # @param [Object] first_task
+      # @return [Boolean]
+      def add_worker(core, first_task = nil)
+        unless add_worker? core, first_task
+          return false
+        end
+
+        worker = PoolWorker.new thread_factory, first_task
+
+        synchronize do
+          control = current_control
+          state = control.state
+
+          if state >= SHUTDOWN && !(state == SHUTDOWN && first_task.nil?)
+            decrement_worker_count
+            try_terminate
+
+            return false
+          end
+
+          @workers.add worker
+
+          count = @workers.size
+          @largest_size = count if count > @largest_size
+        end
+
+        worker.start do
+          run_worker worker
+        end
+
+        return true
+      end
+
+      def add_worker?(core, first_task)
+        loop do
+          control = current_control
+          state = control.state
+
+          if state == SHUTDOWN
+            return false unless first_task || @queue.size > 0
+          elsif state > SHUTDOWN
+            return false
+          end
+
+          loop do
+            worker_count = control.worker_count
+
+            maximum = @core_size if core
+            maximum ||= @maximum_size
+
+            return false unless worker_count < maximum
+
+            # CAS was successful, worker can be started
+            return true if compare_and_increment_worker_count control
+
+            # Pool state changed, retry the entire loop
+            break unless current_control.state == state
+
+            # Worker count changed, retry inter loop
+            control = current_control
+          end
+        end
+      end
+
+      # @param [PoolWorker] worker
+      # @return [undefined]
+      def run_worker(worker)
+        task = worker.first_task!
+
+        clean_exit = false
+
+        loop do
+          task ||= next_task
+          break unless task
+
+          worker.lock
+          begin
+            before_execution task, worker.thread
+            exception = nil
+
+            begin
+              task.call
+            rescue Exception
+              exception = $!
+              raise
+            ensure
+              after_execution task, exception
+            end
+          ensure
+            task = nil
+
+            worker.on_task_completion
+            worker.unlock
+          end
+        end
+
+        clean_exit = true
+      ensure
+        process_worker_exit worker, clean_exit
+      end
+
+      # @return [Object]
+      def next_task
+        timed_out = false
+
+        loop do
+          failed = false
+
+          control = current_control
+          state = control.state
+
+          if state > SHUTDOWN || (state == SHUTDOWN && @queue.empty?)
+            decrement_worker_count
+            return
+          end
+
+          timed = false
+
+          loop do
+            worker_count = control.worker_count
+            timed = @allow_core_timeout || worker_count > @core_size
+
+            if worker_count <= @maximum_size
+              break unless timed && timed_out
+            end
+
+            # Pool has either gone over its maximum size OR the worker thread has timed out
+            # Now attempt to just quietly remove this worker
+            return if compare_and_decrement_worker_count control
+
+            # The compare and swap of the worker count failed
+            unless current_control.state == state
+              # The compare and swap operation failed because the pool state changed
+              # Start completely over so that the pool state is checked
+              failed = true
+              break
+            end
+
+            # The compare and swap operation failed because the worker count changed
+            # Start this inner loop over and ensure that this worker is still eligible for culling
+
+            control = current_control
+          end
+
+          next if failed
+
+          begin
+            if timed
+              task = @queue.poll @work_timeout
+            else
+              task = @queue.take
+            end
+
+            return task if task
+
+            timed_out = true
+          rescue Interrupt
+            # Something interrupted the worker, this may signal the need to reduce the size of the
+            # pool or prepare for termination
+            timed_out = false
+          end
+        end
+      end
+
+      # @param [PoolWorker] worker
+      # @param [Boolean] clean_exit
+      # @return [undefined]
+      def process_worker_exit(worker, clean_exit)
+        unless clean_exit
+          # If worker did not exit cleanly, then the worker count was not adjusted
+          decrement_worker_count
+        end
+
+        synchronize do
+          @completed_task_count += worker.completed_task_count
+          @workers.delete worker
+        end
+
+        try_terminate
+
+        control = current_control
+        if control.state < STOP
+          if clean_exit
+            # Some action caused the pool size to change
+            minimum = (@allow_core_timeout && 0) || @core_size
+            minimum = 1 if minimum == 0 && @queue.size > 0
+
+            # No need to replace the dying worker with a new thread
+            return unless control.worker_count < minimum
+          end
+
+          # Dying worker will be replaced with a new one
+          add_worker false
+        end
+      end
+    end
+
+    # Used in atomic operations relating to the state of the pool
+    PoolControl = Struct.new :state, :worker_count
+  end
+end