concurrent-ruby 0.7.0-java

data/lib/concurrent/executor/single_thread_executor.rb

@@ -0,0 +1,35 @@
+require 'concurrent/executor/ruby_single_thread_executor'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+
+    require 'concurrent/executor/java_single_thread_executor'
+
+    # @!macro [attach] single_thread_executor
+    #
+    #   A thread pool with a set number of threads. The number of threads in the pool
+    #   is set on construction and remains constant. When all threads are busy new
+    #   tasks `#post` to the thread pool are enqueued until a thread becomes available.
+    #   Should a thread crash for any reason the thread will immediately be removed
+    #   from the pool and replaced.
+    #
+    #   The API and behavior of this class are based on Java's `SingleThreadExecutor`
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaSingleThreadExecutor`.
+    #     On all other platforms it will inherit from `RubySingleThreadExecutor`.
+    #
+    #   @see Concurrent::RubySingleThreadExecutor
+    #   @see Concurrent::JavaSingleThreadExecutor
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    class SingleThreadExecutor < JavaSingleThreadExecutor
+    end
+  else
+    # @!macro single_thread_executor
+    class SingleThreadExecutor < RubySingleThreadExecutor
+    end
+  end
+end

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -0,0 +1,68 @@
+require 'concurrent/executor/ruby_thread_pool_executor'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+    require 'concurrent/executor/java_thread_pool_executor'
+    # @!macro [attach] thread_pool_executor
+    #
+    #   An abstraction composed of one or more threads and a task queue. Tasks
+    #   (blocks or `proc` objects) are submit to the pool and added to the queue.
+    #   The threads in the pool remove the tasks and execute them in the order
+    #   they were received. When there are more tasks queued than there are
+    #   threads to execute them the pool will create new threads, up to the
+    #   configured maximum. Similarly, threads that are idle for too long will
+    #   be garbage collected, down to the configured minimum options. Should a
+    #   thread crash it, too, will be garbage collected.
+    #
+    #   `ThreadPoolExecutor` is based on the Java class of the same name. From
+    #   the official Java documentationa;
+    #
+    #   > Thread pools address two different problems: they usually provide
+    #   > improved performance when executing large numbers of asynchronous tasks,
+    #   > due to reduced per-task invocation overhead, and they provide a means
+    #   > of bounding and managing the resources, including threads, consumed
+    #   > when executing a collection of tasks. Each ThreadPoolExecutor also
+    #   > maintains some basic statistics, such as the number of completed tasks.
+    #   >
+    #   > To be useful across a wide range of contexts, this class provides many
+    #   > adjustable parameters and extensibility hooks. However, programmers are
+    #   > urged to use the more convenient Executors factory methods
+    #   > [CachedThreadPool] (unbounded thread pool, with automatic thread reclamation),
+    #   > [FixedThreadPool] (fixed size thread pool) and [SingleThreadExecutor] (single
+    #   > background thread), that preconfigure settings for the most common usage
+    #   > scenarios.
+    #
+    #   Thread pools support several configuration options:
+    #
+    #   * `max_threads`: The maximum number of threads that may be created in the pool.
+    #   * `min_threads`: The minimum number of threads that may be retained in the pool.
+    #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
+    #   * `max_queue`: The maximum number of tasks that may be waiting in the work queue at
+    #     any one time. When the queue size reaches `max_queue` subsequent tasks will be
+    #     rejected in accordance with the configured `overflow_policy`.
+    #   * `overflow_policy`: The policy defining how rejected tasks are handled.    #
+    #
+    #   Three overflow policies are supported:
+    #
+    #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
+    #   * `:discard`: Silently discard the task and return `nil` as the task result.
+    #   * `:caller_runs`: Execute the task on the calling thread.
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaThreadPoolExecutor`.
+    #     On all other platforms it will inherit from `RubyThreadPoolExecutor`.
+    #
+    #   @see Concurrent::RubyThreadPoolExecutor
+    #   @see Concurrent::JavaThreadPoolExecutor
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    class ThreadPoolExecutor < JavaThreadPoolExecutor
+    end
+  else
+    # @!macro thread_pool_executor
+    class ThreadPoolExecutor < RubyThreadPoolExecutor
+    end
+  end
+end

data/lib/concurrent/executor/timer_set.rb

@@ -0,0 +1,143 @@
+require 'thread'
+require_relative 'executor'
+require 'concurrent/options_parser'
+require 'concurrent/atomic/event'
+require 'concurrent/collection/priority_queue'
+require 'concurrent/executor/single_thread_executor'
+
+module Concurrent
+
+  # Executes a collection of tasks at the specified times. A master thread
+  # monitors the set and schedules each task for execution at the appropriate
+  # time. Tasks are run on the global task pool or on the supplied executor.
+  class TimerSet
+    include RubyExecutor
+
+    # Create a new set of timed tasks.
+    #
+    # @param [Hash] opts the options controlling how the future will be processed
+    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
+    #   operation pool (for long-running operations), when `false` will execute the future on the
+    #   global task pool (for short-running tasks)
+    # @option opts [object] :executor when provided will run all operations on
+    #   this executor rather than the global thread pool (overrides :operation)
+    def initialize(opts = {})
+      @queue = PriorityQueue.new(order: :min)
+      @task_executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_task_pool
+      @timer_executor = SingleThreadExecutor.new
+      @condition = Condition.new
+      init_executor
+    end
+
+    # Post a task to be execute at the specified time. The given time may be either
+    # a `Time` object or the number of seconds to wait. If the intended execution
+    # time is within 1/100th of a second of the current time the task will be
+    # immediately post to the executor.
+    #
+    # @param [Object] intended_time the time to schedule the task for execution
+    #
+    # @yield the task to be performed
+    #
+    # @return [Boolean] true if the message is post, false after shutdown
+    #
+    # @raise [ArgumentError] if the intended execution time is not in the future
+    # @raise [ArgumentError] if no block is given
+    def post(intended_time, *args, &task)
+      time = TimerSet.calculate_schedule_time(intended_time).to_f
+      raise ArgumentError.new('no block given') unless block_given?
+
+      mutex.synchronize do
+        return false unless running?
+
+        if (time - Time.now.to_f) <= 0.01
+          @task_executor.post(*args, &task)
+        else
+          @queue.push(Task.new(time, args, task))
+          @timer_executor.post(&method(:process_tasks))
+        end
+
+        true
+      end
+
+    end
+
+    # For a timer, #kill is like an orderly shutdown, except we need to manually
+    # (and destructively) clear the queue first
+    def kill
+      @queue.clear
+      shutdown
+    end
+
+    # Calculate an Epoch time with milliseconds at which to execute a
+    # task. If the given time is a `Time` object it will be converted
+    # accordingly. If the time is an integer value greater than zero
+    # it will be understood as a number of seconds in the future and
+    # will be added to the current time to calculate Epoch.
+    #
+    # @param [Object] intended_time the time (as a `Time` object or an integer)
+    #   to schedule the task for execution
+    # @param [Time] now (Time.now) the time from which to calculate an interval
+    #
+    # @return [Fixnum] the intended time as seconds/millis from Epoch
+    #
+    # @raise [ArgumentError] if the intended execution time is not in the future
+    def self.calculate_schedule_time(intended_time, now = Time.now)
+      if intended_time.is_a?(Time)
+        raise ArgumentError.new('schedule time must be in the future') if intended_time <= now
+        intended_time
+      else
+        raise ArgumentError.new('seconds must be greater than zero') if intended_time.to_f < 0.0
+        now + intended_time
+      end
+    end
+
+    private
+
+    # A struct for encapsulating a task and its intended execution time.
+    # It facilitates proper prioritization by overriding the comparison
+    # (spaceship) operator as a comparison of the intended execution
+    # times.
+    #
+    # @!visibility private
+    Task = Struct.new(:time, :args, :op) do
+      include Comparable
+
+      def <=>(other)
+        self.time <=> other.time
+      end
+    end
+
+    private_constant :Task
+
+    # @!visibility private
+    def shutdown_execution
+      @queue.clear
+      @timer_executor.kill
+      stopped_event.set
+    end
+
+    # Run a loop and execute tasks in the scheduled order and at the approximate
+    # scheduled time. If no tasks remain the thread will exit gracefully so that
+    # garbage collection can occur. If there are no ready tasks it will sleep
+    # for up to 60 seconds waiting for the next scheduled task.
+    #
+    # @!visibility private
+    def process_tasks
+      loop do
+        break if @queue.empty?
+
+        task = @queue.peek
+        interval = task.time - Time.now.to_f
+
+        if interval <= 0
+          @task_executor.post(*task.args, &task.op)
+          @queue.pop
+        else
+          mutex.synchronize do
+            @condition.wait(mutex, [interval, 60].min)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/executors.rb

@@ -0,0 +1,9 @@
+require 'concurrent/executor/cached_thread_pool'
+require 'concurrent/executor/fixed_thread_pool'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/per_thread_executor'
+require 'concurrent/executor/safe_task_executor'
+require 'concurrent/executor/single_thread_executor'
+require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/timer_set'
+require 'concurrent/executor/serialized_execution'

data/lib/concurrent/future.rb

@@ -0,0 +1,125 @@
+require 'thread'
+
+require 'concurrent/options_parser'
+require 'concurrent/ivar'
+require 'concurrent/executor/safe_task_executor'
+
+module Concurrent
+
+  # A `Future` represents a promise to complete an action at some time in the future.
+  # The action is atomic and permanent. The idea behind a future is to send an operation
+  # for asynchronous completion, do other stuff, then return and retrieve the result
+  # of the async operation at a later time.
+  #
+  # A `Future` has four possible states: *:unscheduled*, *:pending*, *:rejected*, or *:fulfilled*.
+  # When a `Future` is created its state is set to *:unscheduled*. Once the `#execute` method is
+  # called the state becomes *:pending* and will remain in that state until processing is
+  # complete. A completed `Future` is either *:rejected*, indicating that an exception was
+  # thrown during processing, or *:fulfilled*, indicating success. If a `Future` is *:fulfilled*
+  # its `value` will be updated to reflect the result of the operation. If *:rejected* the
+  # `reason` will be updated with a reference to the thrown exception. The predicate methods
+  # `#unscheduled?`, `#pending?`, `#rejected?`, and `fulfilled?` can be called at any time to
+  # obtain the state of the `Future`, as can the `#state` method, which returns a symbol. 
+  #
+  # Retrieving the value of a `Future` is done through the `#value` (alias: `#deref`) method.
+  # Obtaining the value of a `Future` is a potentially blocking operation. When a `Future` is
+  # *:rejected* a call to `#value` will return `nil` immediately. When a `Future` is
+  # *:fulfilled* a call to `#value` will immediately return the current value. When a
+  # `Future` is *:pending* a call to `#value` will block until the `Future` is either
+  # *:rejected* or *:fulfilled*. A *timeout* value can be passed to `#value` to limit how
+  # long the call will block. If `nil` the call will block indefinitely. If `0` the call will
+  # not block. Any other integer or float value will indicate the maximum number of seconds to block.
+  #
+  # The `Future` class also includes the behavior of the Ruby standard library `Observable` module,
+  # but does so in a thread-safe way. On fulfillment or rejection all observers will be notified
+  # according to the normal `Observable` behavior. The observer callback function will be called
+  # with three parameters: the `Time` of fulfillment/rejection, the final `value`, and the final
+  # `reason`. Observers added after fulfillment/rejection will still be notified as normal.
+  #
+  # @see http://ruby-doc.org/stdlib-2.1.1/libdoc/observer/rdoc/Observable.html Ruby Observable module
+  # @see http://clojuredocs.org/clojure_core/clojure.core/future Clojure's future function
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html java.util.concurrent.Future
+  class Future < IVar
+
+    # Create a new `Future` in the `:unscheduled` state.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @param [Hash] opts the options controlling how the future will be processed
+    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
+    #   operation pool (for long-running operations), when `false` will execute the future on the
+    #   global task pool (for short-running tasks)
+    # @option opts [object] :executor when provided will run all operations on
+    #   this executor rather than the global thread pool (overrides :operation)
+    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc
+    #
+    # @raise [ArgumentError] if no block is given
+    def initialize(opts = {}, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+      super(IVar::NO_VALUE, opts)
+      @state = :unscheduled
+      @task = block
+      @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
+    end
+
+    # Execute an `:unscheduled` `Future`. Immediately sets the state to `:pending` and
+    # passes the block to a new thread/thread pool for eventual execution.
+    # Does nothing if the `Future` is in any state other than `:unscheduled`.
+    #
+    # @return [Future] a reference to `self`
+    #
+    # @example Instance and execute in separate steps
+    #   future = Concurrent::Future.new{ sleep(1); 42 }
+    #   future.state #=> :unscheduled
+    #   future.execute
+    #   future.state #=> :pending
+    #
+    # @example Instance and execute in one line
+    #   future = Concurrent::Future.new{ sleep(1); 42 }.execute
+    #   future.state #=> :pending
+    #
+    # @since 0.5.0
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        @executor.post{ work }
+        self
+      end
+    end
+
+    # Create a new `Future` object with the given block, execute it, and return the
+    # `:pending` object.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc
+    #
+    # @return [Future] the newly created `Future` in the `:pending` state
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example
+    #   future = Concurrent::Future.execute{ sleep(1); 42 }
+    #   future.state #=> :pending
+    #
+    # @since 0.5.0
+    def self.execute(opts = {}, &block)
+      Future.new(opts, &block).execute
+    end
+
+    protected :set, :fail, :complete
+
+    private
+
+    # @!visibility private
+    def work # :nodoc:
+      success, val, reason = SafeTaskExecutor.new(@task).execute
+      complete(success, val, reason)
+    end
+  end
+end

data/lib/concurrent/ivar.rb

@@ -0,0 +1,111 @@
+require 'thread'
+
+require 'concurrent/errors'
+require 'concurrent/obligation'
+require 'concurrent/observable'
+
+module Concurrent
+
+  # An `IVar` is a single-element container that is normally created empty, and
+  # can only be set once. The I in `IVar` stands for immutable. Reading an `IVar`
+  # normally blocks until it is set. It is safe to set and read an `IVar` from
+  # different threads.
+  #
+  # If you want to have some parallel task set the value in an `IVar`, you want
+  # a `Future`. If you want to create a graph of parallel tasks all executed when
+  # the values they depend on are ready you want `dataflow`. `IVar` is generally
+  # a low-level primitive.
+  #
+  # @example Create, set and get an `IVar`
+  #   ivar = Concurrent::IVar.new
+  #   ivar.set 14
+  #   ivar.get #=> 14
+  #   ivar.set 2 # would now be an error
+  class IVar
+
+    include Obligation
+    include Observable
+
+    # @!visibility private
+    NO_VALUE = Object.new # :nodoc:
+
+    # Create a new `IVar` in the `:pending` state with the (optional) initial value.
+    #
+    # @param [Object] value the initial value
+    # @param [Hash] opts the options to create a message with
+    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc
+    def initialize(value = NO_VALUE, opts = {})
+      init_obligation
+      self.observers = CopyOnWriteObserverSet.new
+      set_deref_options(opts)
+
+      if value == NO_VALUE
+        @state = :pending
+      else
+        set(value)
+      end
+    end
+
+    # Add an observer on this object that will receive notification on update.
+    #
+    # Upon completion the `IVar` will notify all observers in a thread-say way. The `func`
+    # method of the observer will be called with three arguments: the `Time` at which the
+    # `Future` completed the asynchronous operation, the final `value` (or `nil` on rejection),
+    # and the final `reason` (or `nil` on fulfillment).
+    #
+    # @param [Object] observer the object that will be notified of changes
+    # @param [Symbol] func symbol naming the method to call when this `Observable` has changes`
+    def add_observer(observer = nil, func = :update, &block)
+      raise ArgumentError.new('cannot provide both an observer and a block') if observer && block
+      direct_notification = false
+
+      if block
+        observer = block
+        func = :call
+      end
+
+      mutex.synchronize do
+        if event.set?
+          direct_notification = true
+        else
+          observers.add_observer(observer, func)
+        end
+      end
+
+      observer.send(func, Time.now, self.value, reason) if direct_notification
+      observer
+    end
+
+    # Set the `IVar` to a value and wake or notify all threads waiting on it.
+    #
+    # @param [Object] value the value to store in the `IVar`
+    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
+    def set(value)
+      complete(true, value, nil)
+    end
+
+    # Set the `IVar` to failed due to some error and wake or notify all threads waiting on it.
+    #
+    # @param [Object] reason for the failure
+    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
+    def fail(reason = StandardError.new)
+      complete(false, nil, reason)
+    end
+
+    # @!visibility private
+    def complete(success, value, reason) # :nodoc:
+      mutex.synchronize do
+        raise MultipleAssignmentError.new('multiple assignment') if [:fulfilled, :rejected].include? @state
+        set_state(success, value, reason)
+        event.set
+      end
+
+      time = Time.now
+      observers.notify_and_delete_observers{ [time, self.value, reason] }
+      self
+    end
+  end
+end