concurrent-ruby 0.7.0.rc0-x64-mingw32

data/lib/concurrent/collection/priority_queue.rb

@@ -0,0 +1,305 @@
+module Concurrent
+
+  # @!macro [attach] priority_queue
+  #
+  #   A queue collection in which the elements are sorted based on their
+  #   comparison (spaceship) operator `<=>`. Items are added to the queue
+  #   at a position relative to their priority. On removal the element
+  #   with the "highest" priority is removed. By default the sort order is
+  #   from highest to lowest, but a lowest-to-highest sort order can be
+  #   set on construction.
+  #
+  #   The API is based on the `Queue` class from the Ruby standard library.
+  #
+  #   The pure Ruby implementation, `MutexPriorityQueue` uses a heap algorithm
+  #   stored in an array. The algorithm is based on the work of Robert Sedgewick
+  #   and Kevin Wayne.
+  #
+  #   The JRuby native implementation is a thin wrapper around the standard
+  #   library `java.util.PriorityQueue`.
+  #
+  #   When running under JRuby the class `PriorityQueue` extends `JavaPriorityQueue`.
+  #   When running under all other interpreters it extends `MutexPriorityQueue`.
+  #
+  #   @note This implementation is *not* thread safe and performs no blocking.
+  #
+  #   @see http://en.wikipedia.org/wiki/Priority_queue
+  #   @see http://ruby-doc.org/stdlib-2.0.0/libdoc/thread/rdoc/Queue.html
+  #
+  #   @see http://algs4.cs.princeton.edu/24pq/index.php#2.6
+  #   @see http://algs4.cs.princeton.edu/24pq/MaxPQ.java.html
+  #
+  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/PriorityQueue.html
+  class MutexPriorityQueue
+
+    # @!macro [attach] priority_queue_method_initialize
+    #
+    #   Create a new priority queue with no items.
+    #  
+    #   @param [Hash] opts the options for creating the queue
+    #   @option opts [Symbol] :order (:max) dictates the order in which items are
+    #     stored: from highest to lowest when `:max` or `:high`; from lowest to
+    #     highest when `:min` or `:low`
+    def initialize(opts = {})
+      order = opts.fetch(:order, :max)
+      @comparator = [:min, :low].include?(order) ? -1 : 1
+      clear
+    end
+
+    # @!macro [attach] priority_queue_method_clear
+    #
+    #   Removes all of the elements from this priority queue.
+    def clear
+      @queue = [nil]
+      @length = 0
+      true
+    end
+
+    # @!macro [attach] priority_queue_method_delete
+    #
+    #   Deletes all items from `self` that are equal to `item`.
+    #  
+    #   @param [Object] item the item to be removed from the queue
+    #   @return [Object] true if the item is found else false
+    def delete(item)
+      original_length = @length
+      k = 1
+      while k <= @length
+        if @queue[k] == item
+          swap(k, @length)
+          @length -= 1
+          sink(k)
+          @queue.pop
+        else
+          k += 1
+        end
+      end
+      @length != original_length
+    end
+
+    # @!macro [attach] priority_queue_method_empty
+    #  
+    #   Returns `true` if `self` contains no elements.
+    #  
+    #   @return [Boolean] true if there are no items in the queue else false
+    def empty?
+      size == 0
+    end
+
+    # @!macro [attach] priority_queue_method_include
+    #
+    #   Returns `true` if the given item is present in `self` (that is, if any
+    #   element == `item`), otherwise returns false.
+    #  
+    #   @param [Object] item the item to search for
+    #  
+    #   @return [Boolean] true if the item is found else false
+    def include?(item)
+      @queue.include?(item)
+    end
+    alias_method :has_priority?, :include?
+
+    # @!macro [attach] priority_queue_method_length
+    #  
+    #   The current length of the queue.
+    #  
+    #   @return [Fixnum] the number of items in the queue
+    def length
+      @length
+    end
+    alias_method :size, :length
+
+    # @!macro [attach] priority_queue_method_peek
+    #  
+    #   Retrieves, but does not remove, the head of this queue, or returns `nil`
+    #   if this queue is empty.
+    #   
+    #   @return [Object] the head of the queue or `nil` when empty
+    def peek
+      @queue[1]
+    end
+
+    # @!macro [attach] priority_queue_method_pop
+    #  
+    #   Retrieves and removes the head of this queue, or returns `nil` if this
+    #   queue is empty.
+    #   
+    #   @return [Object] the head of the queue or `nil` when empty
+    def pop
+      max = @queue[1]
+      swap(1, @length)
+      @length -= 1
+      sink(1)
+      @queue.pop
+      max
+    end
+    alias_method :deq, :pop
+    alias_method :shift, :pop
+
+    # @!macro [attach] priority_queue_method_push
+    #  
+    #   Inserts the specified element into this priority queue.
+    #  
+    #   @param [Object] item the item to insert onto the queue
+    def push(item)
+      @length += 1
+      @queue << item
+      swim(@length)
+      true
+    end
+    alias_method :<<, :push
+    alias_method :enq, :push
+
+    # @!macro [attach] priority_queue_method_from_list
+    #  
+    #   Create a new priority queue from the given list.
+    #  
+    #   @param [Enumerable] list the list to build the queue from
+    #   @param [Hash] opts the options for creating the queue
+    #  
+    #   @return [PriorityQueue] the newly created and populated queue
+    def self.from_list(list, opts = {})
+      queue = new(opts)
+      list.each{|item| queue << item }
+      queue
+    end
+
+    protected
+
+    # Exchange the values at the given indexes within the internal array.
+    # 
+    # @param [Integer] x the first index to swap
+    # @param [Integer] y the second index to swap
+    # 
+    # @!visibility private
+    def swap(x, y)
+      temp = @queue[x]
+      @queue[x] = @queue[y]
+      @queue[y] = temp
+    end
+
+    # Are the items at the given indexes ordered based on the priority
+    # order specified at construction?
+    #
+    # @param [Integer] x the first index from which to retrieve a comparable value
+    # @param [Integer] y the second index from which to retrieve a comparable value
+    #
+    # @return [Boolean] true if the two elements are in the correct priority order
+    #   else false
+    # 
+    # @!visibility private
+    def ordered?(x, y)
+      (@queue[x] <=> @queue[y]) == @comparator
+    end
+
+    # Percolate down to maintain heap invariant.
+    # 
+    # @param [Integer] k the index at which to start the percolation
+    # 
+    # @!visibility private
+    def sink(k)
+      while (j = (2 * k)) <= @length do
+        j += 1 if j < @length && ! ordered?(j, j+1)
+        break if ordered?(k, j)
+        swap(k, j)
+        k = j
+      end
+    end
+
+    # Percolate up to maintain heap invariant.
+    # 
+    # @param [Integer] k the index at which to start the percolation
+    # 
+    # @!visibility private
+    def swim(k)
+      while k > 1 && ! ordered?(k/2, k) do
+        swap(k, k/2)
+        k = k/2
+      end
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    # @!macro priority_queue
+    class JavaPriorityQueue
+
+      # @!macro priority_queue_method_initialize
+      def initialize(opts = {})
+        order = opts.fetch(:order, :max)
+        if [:min, :low].include?(order)
+          @queue = java.util.PriorityQueue.new(11) # 11 is the default initial capacity
+        else
+          @queue = java.util.PriorityQueue.new(11, java.util.Collections.reverseOrder())
+        end
+      end
+
+      # @!macro priority_queue_method_clear
+      def clear
+        @queue.clear
+        true
+      end
+
+      # @!macro priority_queue_method_delete
+      def delete(item)
+        found = false
+        while @queue.remove(item) do
+          found = true
+        end
+        found
+      end
+
+      # @!macro priority_queue_method_empty
+      def empty?
+        @queue.size == 0
+      end
+
+      # @!macro priority_queue_method_include
+      def include?(item)
+        @queue.contains(item)
+      end
+      alias_method :has_priority?, :include?
+
+      # @!macro priority_queue_method_length
+      def length
+        @queue.size
+      end
+      alias_method :size, :length
+
+      # @!macro priority_queue_method_peek
+      def peek
+        @queue.peek
+      end
+
+      # @!macro priority_queue_method_pop
+      def pop
+        @queue.poll
+      end
+      alias_method :deq, :pop
+      alias_method :shift, :pop
+
+      # @!macro priority_queue_method_push
+      def push(item)
+        @queue.add(item)
+      end
+      alias_method :<<, :push
+      alias_method :enq, :push
+
+      # @!macro priority_queue_method_from_list
+      def self.from_list(list, opts = {})
+        queue = new(opts)
+        list.each{|item| queue << item }
+        queue
+      end
+    end
+
+    # @!macro priority_queue
+    class PriorityQueue < JavaPriorityQueue
+    end
+  else
+
+    # @!macro priority_queue
+    class PriorityQueue < MutexPriorityQueue
+    end
+  end
+end

data/lib/concurrent/collection/ring_buffer.rb

@@ -0,0 +1,59 @@
+module Concurrent
+
+  # non-thread safe buffer
+  class RingBuffer
+
+    def initialize(capacity)
+      @buffer = Array.new(capacity)
+      @first = @last = 0
+      @count = 0
+    end
+
+
+    # @return [Integer] the capacity of the buffer
+    def capacity
+      @buffer.size
+    end
+
+    # @return [Integer] the number of elements currently in the buffer
+    def count
+      @count
+    end
+
+    # @return [Boolean] true if buffer is empty, false otherwise
+    def empty?
+      @count == 0
+    end
+
+    # @return [Boolean] true if buffer is full, false otherwise
+    def full?
+      @count == capacity
+    end
+
+    # @param [Object] value
+    # @return [Boolean] true if value has been inserted, false otherwise
+    def offer(value)
+      return false if full?
+
+      @buffer[@last] = value
+      @last = (@last + 1) % @buffer.size
+      @count += 1
+      true
+    end
+
+    # @return [Object] the first available value and removes it from the buffer. If buffer is empty returns nil
+    def poll
+      result = @buffer[@first]
+      @buffer[@first] = nil
+      @first = (@first + 1) % @buffer.size
+      @count -= 1
+      result
+    end
+
+    # @return [Object] the first available value and without removing it from the buffer. If buffer is empty returns nil
+    def peek
+      @buffer[@first]
+    end
+
+  end
+end

data/lib/concurrent/collections.rb

@@ -0,0 +1,3 @@
+require 'concurrent/collection/priority_queue'
+require 'concurrent/collection/ring_buffer'
+require 'concurrent/collection/blocking_ring_buffer'

data/lib/concurrent/configuration.rb

@@ -0,0 +1,158 @@
+require 'thread'
+require 'concurrent/delay'
+require 'concurrent/errors'
+require 'concurrent/atomic'
+require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/timer_set'
+require 'concurrent/utility/processor_count'
+
+module Concurrent
+  extend Logging
+
+  # A gem-level configuration object.
+  class Configuration
+
+    # a proc defining how to log messages, its interface has to be:
+    #   lambda { |level, progname, message = nil, &block| _ }
+    attr_accessor :logger
+
+    # Create a new configuration object.
+    def initialize
+      @global_task_pool      = Delay.new { new_task_pool }
+      @global_operation_pool = Delay.new { new_operation_pool }
+      @global_timer_set      = Delay.new { Concurrent::TimerSet.new }
+      @logger                = no_logger
+    end
+
+    # if assigned to {#logger}, it will log nothing.
+    def no_logger
+      lambda { |level, progname, message = nil, &block| }
+    end
+
+    # Global thread pool optimized for short *tasks*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    def global_task_pool
+      @global_task_pool.value
+    end
+
+    # Global thread pool optimized for long *operations*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    def global_operation_pool
+      @global_operation_pool.value
+    end
+
+    # Global thread pool optimized for *timers*
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    #
+    # @see Concurrent::timer
+    def global_timer_set
+      @global_timer_set.value
+    end
+
+    # Global thread pool optimized for short *tasks*.
+    #
+    # A global thread pool must be set as soon as the gem is loaded. Setting a new
+    # thread pool once tasks and operations have been post can lead to unpredictable
+    # results. The first time a task/operation is post a new thread pool will be
+    # created using the default configuration. Once set the thread pool cannot be
+    # changed. Thus, explicitly setting the thread pool must occur *before* any
+    # tasks/operations are post else an exception will be raised.
+    #
+    # @param [Executor] executor the executor to be used for this thread pool
+    #
+    # @return [ThreadPoolExecutor] the new thread pool
+    #
+    # @raise [Concurrent::ConfigurationError] if this thread pool has already been set
+    def global_task_pool=(executor)
+      @global_task_pool.reconfigure { executor } or
+          raise ConfigurationError.new('global task pool was already set')
+    end
+
+    # Global thread pool optimized for long *operations*.
+    #
+    # A global thread pool must be set as soon as the gem is loaded. Setting a new
+    # thread pool once tasks and operations have been post can lead to unpredictable
+    # results. The first time a task/operation is post a new thread pool will be
+    # created using the default configuration. Once set the thread pool cannot be
+    # changed. Thus, explicitly setting the thread pool must occur *before* any
+    # tasks/operations are post else an exception will be raised.
+    #
+    # @param [Executor] executor the executor to be used for this thread pool
+    #
+    # @return [ThreadPoolExecutor] the new thread pool
+    #
+    # @raise [Concurrent::ConfigurationError] if this thread pool has already been set
+    def global_operation_pool=(executor)
+      @global_operation_pool.reconfigure { executor } or
+          raise ConfigurationError.new('global operation pool was already set')
+    end
+
+    def new_task_pool
+      Concurrent::ThreadPoolExecutor.new(
+          min_threads:     [2, Concurrent.processor_count].max,
+          max_threads:     [20, Concurrent.processor_count * 15].max,
+          idletime:        2 * 60, # 2 minutes
+          max_queue:       0, # unlimited
+          overflow_policy: :abort # raise an exception
+      )
+    end
+
+    def new_operation_pool
+      Concurrent::ThreadPoolExecutor.new(
+          min_threads:     [2, Concurrent.processor_count].max,
+          max_threads:     [2, Concurrent.processor_count].max,
+          idletime:        10 * 60, # 10 minutes
+          max_queue:       [20, Concurrent.processor_count * 15].max,
+          overflow_policy: :abort # raise an exception
+      )
+    end
+  end
+
+  # create the default configuration on load
+  @configuration = Atomic.new Configuration.new
+
+  # @return [Configuration]
+  def self.configuration
+    @configuration.value
+  end
+
+  # Perform gem-level configuration.
+  #
+  # @yield the configuration commands
+  # @yieldparam [Configuration] the current configuration object
+  def self.configure
+    yield(configuration)
+  end
+
+  private
+
+  # Attempt to properly shutdown the given executor using the `shutdown` or
+  # `kill` method when available.
+  #
+  # @param [Executor] executor the executor to shutdown
+  #
+  # @return [Boolean] `true` if the executor is successfully shut down or `nil`, else `false`
+  def self.finalize_executor(executor)
+    return true if executor.nil?
+    if executor.respond_to?(:shutdown)
+      executor.shutdown
+    elsif executor.respond_to?(:kill)
+      executor.kill
+    end
+    true
+  rescue => ex
+    log DEBUG, ex
+    false
+  end
+
+
+  # set exit hook to shutdown global thread pools
+  at_exit do
+    self.finalize_executor(self.configuration.global_timer_set)
+    self.finalize_executor(self.configuration.global_task_pool)
+    self.finalize_executor(self.configuration.global_operation_pool)
+  end
+end