concurrent-ruby 0.6.0.pre.1 → 0.6.0.pre.2

data/lib/concurrent/async.rb

@@ -2,7 +2,7 @@ require 'thread'
 require 'concurrent/configuration'
 require 'concurrent/ivar'
 require 'concurrent/future'
-require 'concurrent/thread_pool_executor'
+require 'concurrent/executor/thread_pool_executor'
 
 module Concurrent
 
@@ -17,20 +17,20 @@ module Concurrent
   # Stateful, mutable objects must be managed carefully when used asynchronously.
   # But Ruby is an object-oriented language so designing with objects and classes
   # plays to Ruby's strengths and is often more natural to many Ruby programmers.
-  # The +Async+ module is a way to mix simple yet powerful asynchronous capabilities
+  # The `Async` module is a way to mix simple yet powerful asynchronous capabilities
   # into any plain old Ruby object or class. These capabilities provide a reasonable
   # level of thread safe guarantees when used correctly.
   #
   # When this module is mixed into a class or object it provides to new methods:
-  # +async+ and +await+. These methods are thread safe with respect to the enclosing
+  # `async` and `await`. These methods are thread safe with respect to the enclosing
   # object. The former method allows methods to be called asynchronously by posting
   # to the global thread pool. The latter allows a method to be called synchronously
   # on the current thread but does so safely with respect to any pending asynchronous
-  # method calls. Both methods return an +Obligation+ which can be inspected for
-  # the result of the method call. Calling a method with +async+ will return a
-  # +:pending+ +Obligation+ whereas +await+ will return a +:complete+ +Obligation+.
+  # method calls. Both methods return an `Obligation` which can be inspected for
+  # the result of the method call. Calling a method with `async` will return a
+  # `:pending` `Obligation` whereas `await` will return a `:complete` `Obligation`.
   #
-  # Very loosely based on the +async+ and +await+ keywords in C#.
+  # Very loosely based on the `async` and `await` keywords in C#.
   #
   # @example Defining an asynchronous class
   #   class Echo
@@ -64,9 +64,9 @@ module Concurrent
   # @note Thread safe guarantees can only be made when asynchronous method calls
   #       are not mixed with synchronous method calls. Use only synchronous calls
   #       when the object is used exclusively on a single thread. Use only
-  #       +async+ and +await+ when the object is shared between threads. Once you
-  #       call a method using +async+, you should no longer call any methods
-  #       directly on the object. Use +async+ and +await+ exclusively from then on.
+  #       `async` and `await` when the object is shared between threads. Once you
+  #       call a method using `async`, you should no longer call any methods
+  #       directly on the object. Use `async` and `await` exclusively from then on.
   #       With careful programming it is possible to switch back and forth but it's
   #       also very easy to create race conditions and break your application.
   #       Basically, it's "async all the way down."
@@ -83,14 +83,14 @@ module Concurrent
     # @param [Symbol] method the method to check the object for
     # @param [Array] args zero or more arguments for the arity check
     #
-    # @raise [NameError] the object does not respond to +method+ method
-    # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+    # @raise [NameError] the object does not respond to `method` method
+    # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @note This check is imperfect because of the way Ruby reports the arity of
     #   methods with a variable number of arguments. It is possible to determine
     #   if too few arguments are given but impossible to determine if too many
     #   arguments are given. This check may also fail to recognize dynamic behavior
-    #   of the object, such as methods simulated with +method_missing+.
+    #   of the object, such as methods simulated with `method_missing`.
     #
     # @see http://www.ruby-doc.org/core-2.1.1/Method.html#method-i-arity Method#arity
     # @see http://ruby-doc.org/core-2.1.0/Object.html#method-i-respond_to-3F Object#respond_to?
@@ -112,8 +112,8 @@ module Concurrent
     # @!visibility private
     class AwaitDelegator # :nodoc:
 
-      # Create a new delegator object wrapping the given +delegate+ and
-      # protecting it with the given +mutex+.
+      # Create a new delegator object wrapping the given `delegate` and
+      # protecting it with the given `mutex`.
       #
       # @param [Object] delegate the object to wrap and delegate method calls to
       # @param [Mutex] mutex the mutex lock to use when delegating method calls
@@ -124,15 +124,15 @@ module Concurrent
 
       # Delegates method calls to the wrapped object. For performance,
       # dynamically defines the given method on the delegator so that
-      # all future calls to +method+ will not be directed here.
+      # all future calls to `method` will not be directed here.
       #
       # @param [Symbol] method the method being called
       # @param [Array] args zero or more arguments to the method
       #
       # @return [IVar] the result of the method call
       #
-      # @raise [NameError] the object does not respond to +method+ method
-      # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+      # @raise [NameError] the object does not respond to `method` method
+      # @raise [ArgumentError] the given `args` do not match the arity of `method`
       def method_missing(method, *args, &block)
         super unless @delegate.respond_to?(method)
         Async::validate_argc(@delegate, method, *args)
@@ -166,8 +166,8 @@ module Concurrent
     # @!visibility private
     class AsyncDelegator # :nodoc:
 
-      # Create a new delegator object wrapping the given +delegate+ and
-      # protecting it with the given +mutex+.
+      # Create a new delegator object wrapping the given `delegate` and
+      # protecting it with the given `mutex`.
       #
       # @param [Object] delegate the object to wrap and delegate method calls to
       # @param [Mutex] mutex the mutex lock to use when delegating method calls
@@ -179,15 +179,15 @@ module Concurrent
 
       # Delegates method calls to the wrapped object. For performance,
       # dynamically defines the given method on the delegator so that
-      # all future calls to +method+ will not be directed here.
+      # all future calls to `method` will not be directed here.
       #
       # @param [Symbol] method the method being called
       # @param [Array] args zero or more arguments to the method
       #
       # @return [IVar] the result of the method call
       #
-      # @raise [NameError] the object does not respond to +method+ method
-      # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+      # @raise [NameError] the object does not respond to `method` method
+      # @raise [ArgumentError] the given `args` do not match the arity of `method`
       def method_missing(method, *args, &block)
         super unless @delegate.respond_to?(method)
         Async::validate_argc(@delegate, method, *args)
@@ -214,20 +214,20 @@ module Concurrent
 
     # Causes the chained method call to be performed asynchronously on the
     # global thread pool. The method called by this method will return a
-    # +Future+ object in the +:pending+ state and the method call will have
+    # `Future` object in the `:pending` state and the method call will have
     # been scheduled on the global thread pool. The final disposition of the
-    # method call can be obtained by inspecting the returned +Future+.
+    # method call can be obtained by inspecting the returned `Future`.
     #
     # Before scheduling the method on the global thread pool a best-effort
     # attempt will be made to validate that the method exists on the object
     # and that the given arguments match the arity of the requested function.
     # Due to the dynamic nature of Ruby and limitations of its reflection
     # library, some edge cases will be missed. For more information see
-    # the documentation for the +validate_argc+ method.
+    # the documentation for the `validate_argc` method.
     #
     # @note The method call is guaranteed to be thread safe  with respect to
     #   all other method calls against the same object that are called with
-    #   either +async+ or +await+. The mutable nature of Ruby references
+    #   either `async` or `await`. The mutable nature of Ruby references
     #   (and object orientation in general) prevent any other thread safety
     #   guarantees. Do NOT mix non-protected method calls with protected
     #   method call. Use ONLY protected method calls when sharing the object
@@ -235,8 +235,8 @@ module Concurrent
     #
     # @return [Concurrent::Future] the pending result of the asynchronous operation
     #
-    # @raise [NameError] the object does not respond to +method+ method
-    # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+    # @raise [NameError] the object does not respond to `method` method
+    # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::Future
     def async
@@ -246,20 +246,20 @@ module Concurrent
 
     # Causes the chained method call to be performed synchronously on the
     # current thread. The method called by this method will return an
-    # +IVar+ object in either the +:fulfilled+ or +rejected+ state and the
+    # `IVar` object in either the `:fulfilled` or `rejected` state and the
     # method call will have completed. The final disposition of the
-    # method call can be obtained by inspecting the returned +IVar+.
+    # method call can be obtained by inspecting the returned `IVar`.
     #
     # Before scheduling the method on the global thread pool a best-effort
     # attempt will be made to validate that the method exists on the object
     # and that the given arguments match the arity of the requested function.
     # Due to the dynamic nature of Ruby and limitations of its reflection
     # library, some edge cases will be missed. For more information see
-    # the documentation for the +validate_argc+ method.
+    # the documentation for the `validate_argc` method.
     #
     # @note The method call is guaranteed to be thread safe  with respect to
     #   all other method calls against the same object that are called with
-    #   either +async+ or +await+. The mutable nature of Ruby references
+    #   either `async` or `await`. The mutable nature of Ruby references
     #   (and object orientation in general) prevent any other thread safety
     #   guarantees. Do NOT mix non-protected method calls with protected
     #   method call. Use ONLY protected method calls when sharing the object
@@ -267,8 +267,8 @@ module Concurrent
     #
     # @return [Concurrent::IVar] the completed result of the synchronous operation
     #
-    # @raise [NameError] the object does not respond to +method+ method
-    # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+    # @raise [NameError] the object does not respond to `method` method
+    # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def await

data/lib/concurrent/atomic/atomic_boolean.rb

@@ -0,0 +1,157 @@
+module Concurrent
+
+  # @!macro [attach] atomic_boolean
+  #
+  #   A boolean value that can be updated atomically. Reads and writes to an atomic
+  #   boolean and thread-safe and guaranteed to succeed. Reads and writes may block
+  #   briefly but no explicit locking is required.
+  #
+  #   @since 0.6.0
+  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
+  class MutexAtomicBoolean
+
+    # @!macro [attach] atomic_boolean_method_initialize
+    #
+    # Creates a new `AtomicBoolean` with the given initial value.
+    #
+    # @param [Boolean] init the initial value
+    def initialize(initial = false)
+      @value = !!initial
+      @mutex = Mutex.new
+    end
+
+    # @!macro [attach] atomic_boolean_method_value
+    #
+    #   Retrieves the current `Boolean` value.
+    #
+    #   @return [Boolean] the current value
+    def value
+      @mutex.lock
+      result = @value
+      @mutex.unlock
+      result
+    end
+
+    # @!macro [attach] atomic_boolean_method_value_eq
+    #
+    #   Explicitly sets the value.
+    #
+    #   @param [Boolean] value the new value to be set
+    #
+    #   @return [Boolean] the current value
+    def value=(value)
+      @mutex.lock
+      @value = !!value
+      result = @value
+      @mutex.unlock
+      result
+    end
+
+    # @!macro [attach] atomic_boolean_method_is_true
+    #
+    #   Is the current value `true`?
+    #
+    #   @return [Boolean] true if the current value is `true`, else false
+    def true?
+      @mutex.lock
+      result = @value
+      @mutex.unlock
+      result
+    end
+
+    # @!macro [attach] atomic_boolean_method_is_false
+    #
+    #   Is the current value `true`?false
+    #
+    #   @return [Boolean] true if the current value is `false`, else false
+    def false?
+      @mutex.lock
+      result = !@value
+      @mutex.unlock
+      result
+    end
+
+    # @!macro [attach] atomic_boolean_method_make_true
+    #
+    #   Explicitly sets the value to true.
+    #
+    #   @return [Boolean] true is value has changed, otherwise false
+    def make_true
+      @mutex.lock
+      old = @value
+      @value = true
+      @mutex.unlock
+
+      !old
+    end
+
+    # @!macro [attach] atomic_boolean_method_make_false
+    #
+    #   Explicitly sets the value to false.
+    #
+    #   @return [Boolean] true is value has changed, otherwise false
+    def make_false
+      @mutex.lock
+      old = @value
+      @value = false
+      @mutex.unlock
+
+      old
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    # @!macro atomic_boolean
+    class JavaAtomicBoolean
+
+      # @!macro atomic_boolean_method_initialize
+      #
+      def initialize(initial = false)
+        @atomic = java.util.concurrent.atomic.AtomicBoolean.new(!!initial)
+      end
+
+      # @!macro atomic_boolean_method_value
+      #
+      def value
+        @atomic.get
+      end
+
+      # @!macro atomic_boolean_method_value_eq
+      #
+      def value=(value)
+        @atomic.set(!!value)
+      end
+
+      # @!macro [attach] atomic_boolean_method_is_true
+      def true?
+        @atomic.get
+      end
+
+      # @!macro [attach] atomic_boolean_method_is_false
+      def false?
+        !@atomic.get
+      end
+
+      # @!macro atomic_boolean_method_make_true
+      def make_true
+        @atomic.compareAndSet(false, true)
+      end
+
+      # @!macro atomic_boolean_method_make_false
+      def make_false
+        @atomic.compareAndSet(true, false)
+      end
+    end
+
+    # @!macro atomic_boolean
+    class AtomicBoolean < JavaAtomicBoolean
+    end
+
+  else
+
+    # @!macro atomic_boolean
+    class AtomicBoolean < MutexAtomicBoolean
+    end
+  end
+end

data/lib/concurrent/atomic/atomic_fixnum.rb

@@ -0,0 +1,170 @@
+module Concurrent
+
+  # @!macro [attach] atomic_fixnum
+  #
+  #   A numeric value that can be updated atomically. Reads and writes to an atomic
+  #   fixnum and thread-safe and guaranteed to succeed. Reads and writes may block
+  #   briefly but no explicit locking is required.
+  #
+  #   @since 0.5.0
+  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
+  class MutexAtomicFixnum
+
+    # @!macro [attach] atomic_fixnum_method_initialize
+    #
+    # Creates a new `AtomicFixnum` with the given initial value.
+    #
+    # @param [Fixnum] init the initial value
+    # @raise [ArgumentError] if the initial value is not a `Fixnum`
+    def initialize(init = 0)
+      raise ArgumentError.new('initial value must be a Fixnum') unless init.is_a?(Fixnum)
+      @value = init
+      @mutex = Mutex.new
+    end
+
+    # @!macro [attach] atomic_fixnum_method_value
+    #
+    #   Retrieves the current `Fixnum` value.
+    #
+    #   @return [Fixnum] the current value
+    def value
+      @mutex.lock
+      result = @value
+      @mutex.unlock
+
+      result
+    end
+
+    # @!macro [attach] atomic_fixnum_method_value_eq
+    #
+    #   Explicitly sets the value.
+    #
+    #   @param [Fixnum] value the new value to be set
+    #
+    #   @return [Fixnum] the current value
+    #
+    #   @raise [ArgumentError] if the new value is not a `Fixnum`
+    def value=(value)
+      raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
+      @mutex.lock
+      result = @value = value
+      @mutex.unlock
+
+      result
+    end
+
+    # @!macro [attach] atomic_fixnum_method_increment
+    #
+    #   Increases the current value by 1.
+    #
+    #   @return [Fixnum] the current value after incrementation
+    def increment
+      @mutex.lock
+      @value += 1
+      result = @value
+      @mutex.unlock
+
+      result
+    end
+
+    alias_method :up, :increment
+
+    # @!macro [attach] atomic_fixnum_method_decrement
+    #
+    #   Decreases the current value by 1.
+    #
+    #   @return [Fixnum] the current value after decrementation
+    def decrement
+      @mutex.lock
+      @value -= 1
+      result = @value
+      @mutex.unlock
+
+      result
+    end
+
+    alias_method :down, :decrement
+
+    # @!macro [attach] atomic_fixnum_method_compare_and_set
+    # 
+    #   Atomically sets the value to the given updated value if the current
+    #   value == the expected value.
+    #
+    #   @param [Fixnum] expect the expected value
+    #   @param [Fixnum] update the new value
+    #
+    #   @return [Boolean] true if the value was updated else false 
+    def compare_and_set(expect, update)
+
+      @mutex.lock
+      if @value == expect
+        @value = update
+        result = true
+      else
+        result = false
+      end
+      @mutex.unlock
+
+      result
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    # @!macro atomic_fixnum
+    class JavaAtomicFixnum
+
+      # @!macro atomic_fixnum_method_initialize
+      #
+      def initialize(init = 0)
+        raise ArgumentError.new('initial value must be a Fixnum') unless init.is_a?(Fixnum)
+        @atomic = java.util.concurrent.atomic.AtomicLong.new(init)
+      end
+
+      # @!macro atomic_fixnum_method_value
+      #
+      def value
+        @atomic.get
+      end
+
+      # @!macro atomic_fixnum_method_value_eq
+      #
+      def value=(value)
+        raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
+        @atomic.set(value)
+      end
+
+      # @!macro atomic_fixnum_method_increment
+      #
+      def increment
+        @atomic.increment_and_get
+      end
+
+      alias_method :up, :increment
+
+      # @!macro atomic_fixnum_method_decrement
+      #
+      def decrement
+        @atomic.decrement_and_get
+      end
+
+      alias_method :down, :decrement
+
+      # @!macro atomic_fixnum_method_compare_and_set
+      #
+      def compare_and_set(expect, update)
+        @atomic.compare_and_set(expect, update)
+      end
+    end
+
+    # @!macro atomic_fixnum
+    class AtomicFixnum < JavaAtomicFixnum
+    end
+
+  else
+
+    # @!macro atomic_fixnum
+    class AtomicFixnum < MutexAtomicFixnum
+    end
+  end
+end