concurrent-ruby 1.0.5 → 1.1.1

data/lib/concurrent/map.rb

@@ -1,33 +1,27 @@
 require 'thread'
 require 'concurrent/constants'
 require 'concurrent/synchronization'
+require 'concurrent/utility/engine'
 
 module Concurrent
   # @!visibility private
   module Collection
 
     # @!visibility private
-    MapImplementation = if Concurrent.java_extensions_loaded?
+    MapImplementation = case
+                        when Concurrent.on_jruby?
                           # noinspection RubyResolve
                           JRubyMapBackend
-                        elsif defined?(RUBY_ENGINE)
-                          case RUBY_ENGINE
-                          when 'ruby'
-                            require 'concurrent/collection/map/mri_map_backend'
-                            MriMapBackend
-                          when 'rbx'
-                            require 'concurrent/collection/map/atomic_reference_map_backend'
-                            AtomicReferenceMapBackend
-                          when 'jruby+truffle'
-                            require 'concurrent/collection/map/atomic_reference_map_backend'
-                            AtomicReferenceMapBackend
-                          else
-                            warn 'Concurrent::Map: unsupported Ruby engine, using a fully synchronized Concurrent::Map implementation' if $VERBOSE
-                            require 'concurrent/collection/map/synchronized_map_backend'
-                            SynchronizedMapBackend
-                          end
-                        else
+                        when Concurrent.on_cruby?
+                          require 'concurrent/collection/map/mri_map_backend'
                           MriMapBackend
+                        when Concurrent.on_rbx? || Concurrent.on_truffleruby?
+                          require 'concurrent/collection/map/atomic_reference_map_backend'
+                          AtomicReferenceMapBackend
+                        else
+                          warn 'Concurrent::Map: unsupported Ruby engine, using a fully synchronized Concurrent::Map implementation'
+                          require 'concurrent/collection/map/synchronized_map_backend'
+                          SynchronizedMapBackend
                         end
   end
 
@@ -37,46 +31,89 @@ module Concurrent
   # -- for instance, it does not necessarily retain ordering by insertion time as `Hash`
   # does. For most uses it should do fine though, and we recommend you consider
   # `Concurrent::Map` instead of `Concurrent::Hash` for your concurrency-safe hash needs.
-  #
-  # > require 'concurrent'
-  # >
-  # > map = Concurrent::Map.new
   class Map < Collection::MapImplementation
 
-    # @!macro [new] map_method_is_atomic
-    #   This method is atomic. Atomic methods of `Map` which accept a block
-    #   do not allow the `self` instance to be used within the block. Doing
-    #   so will cause a deadlock.
-
-    # @!method put_if_absent
-    #   @!macro map_method_is_atomic
-
-    # @!method compute_if_absent
-    #   @!macro map_method_is_atomic
-
-    # @!method compute_if_present
-    #   @!macro map_method_is_atomic
-
-    # @!method compute
-    #   @!macro map_method_is_atomic
-
-    # @!method merge_pair
-    #   @!macro map_method_is_atomic
-
-    # @!method replace_pair
-    #   @!macro map_method_is_atomic
-
-    # @!method replace_if_exists
-    #   @!macro map_method_is_atomic
-
-    # @!method get_and_set
-    #   @!macro map_method_is_atomic
+    # @!macro map.atomic_method
+    #   This method is atomic.
+
+    # @!macro map.atomic_method_with_block
+    #   This method is atomic.
+    #   @note Atomic methods taking a block do not allow the `self` instance
+    #     to be used within the block. Doing so will cause a deadlock.
+
+    # @!method compute_if_absent(key)
+    #   Compute and store new value for key if the key is absent.
+    #   @param [Object] key
+    #   @yield new value
+    #   @yieldreturn [Object] new value
+    #   @return [Object] new value or current value
+    #   @!macro map.atomic_method_with_block
+
+    # @!method compute_if_present(key)
+    #   Compute and store new value for key if the key is present.
+    #   @param [Object] key
+    #   @yield new value
+    #   @yieldparam old_value [Object]
+    #   @yieldreturn [Object, nil] new value, when nil the key is removed
+    #   @return [Object, nil] new value or nil
+    #   @!macro map.atomic_method_with_block
+
+    # @!method compute(key)
+    #   Compute and store new value for key.
+    #   @param [Object] key
+    #   @yield compute new value from old one
+    #   @yieldparam old_value [Object, nil] old_value, or nil when key is absent
+    #   @yieldreturn [Object, nil] new value, when nil the key is removed
+    #   @return [Object, nil] new value or nil
+    #   @!macro map.atomic_method_with_block
+
+    # @!method merge_pair(key, value)
+    #   If the key is absent, the value is stored, otherwise new value is
+    #   computed with a block.
+    #   @param [Object] key
+    #   @param [Object] value
+    #   @yield compute new value from old one
+    #   @yieldparam old_value [Object] old value
+    #   @yieldreturn [Object, nil] new value, when nil the key is removed
+    #   @return [Object, nil] new value or nil
+    #   @!macro map.atomic_method_with_block
+
+    # @!method replace_pair(key, old_value, new_value)
+    #   Replaces old_value with new_value if key exists and current value
+    #   matches old_value
+    #   @param [Object] key
+    #   @param [Object] old_value
+    #   @param [Object] new_value
+    #   @return [true, false] true if replaced
+    #   @!macro map.atomic_method
+
+    # @!method replace_if_exists(key, new_value)
+    #   Replaces current value with new_value if key exists
+    #   @param [Object] key
+    #   @param [Object] new_value
+    #   @return [Object, nil] old value or nil
+    #   @!macro map.atomic_method
+
+    # @!method get_and_set(key, value)
+    #   Get the current value under key and set new value.
+    #   @param [Object] key
+    #   @param [Object] value
+    #   @return [Object, nil] old value or nil when the key was absent
+    #   @!macro map.atomic_method
+
+    # @!method delete(key)
+    #   Delete key and its value.
+    #   @param [Object] key
+    #   @return [Object, nil] old value or nil when the key was absent
+    #   @!macro map.atomic_method
+
+    # @!method delete_pair(key, value)
+    #   Delete pair and its value if current value equals the provided value.
+    #   @param [Object] key
+    #   @param [Object] value
+    #   @return [true, false] true if deleted
+    #   @!macro map.atomic_method
 
-    # @!method delete
-    #   @!macro map_method_is_atomic
-
-    # @!method delete_pair
-    #   @!macro map_method_is_atomic
 
     def initialize(options = nil, &block)
       if options.kind_of?(::Hash)
@@ -89,6 +126,9 @@ module Concurrent
       @default_proc = block
     end
 
+    # Get a value with key
+    # @param [Object] key
+    # @return [Object] the value
     def [](key)
       if value = super # non-falsy value is an existing mapping, return it right away
         value
@@ -104,17 +144,27 @@ module Concurrent
     end
 
     alias_method :get, :[]
+    # TODO (pitr-ch 30-Oct-2018): doc
     alias_method :put, :[]=
 
-    # @!macro [attach] map_method_not_atomic
-    #   The "fetch-then-act" methods of `Map` are not atomic. `Map` is intended
-    #   to be use as a concurrency primitive with strong happens-before
-    #   guarantees. It is not intended to be used as a high-level abstraction
-    #   supporting complex operations. All read and write operations are
-    #   thread safe, but no guarantees are made regarding race conditions
-    #   between the fetch operation and yielding to the block. Additionally,
-    #   this method does not support recursion. This is due to internal
-    #   constraints that are very unlikely to change in the near future.
+    # Get a value with key, or default_value when key is absent,
+    # or fail when no default_value is given.
+    # @param [Object] key
+    # @param [Object] default_value
+    # @yield default value for a key
+    # @yieldparam key [Object]
+    # @yieldreturn [Object] default value
+    # @return [Object] the value or default value
+    # @raise [KeyError] when key is missing and no default_value is provided
+    # @!macro map_method_not_atomic
+    #   @note The "fetch-then-act" methods of `Map` are not atomic. `Map` is intended
+    #     to be use as a concurrency primitive with strong happens-before
+    #     guarantees. It is not intended to be used as a high-level abstraction
+    #     supporting complex operations. All read and write operations are
+    #     thread safe, but no guarantees are made regarding race conditions
+    #     between the fetch operation and yielding to the block. Additionally,
+    #     this method does not support recursion. This is due to internal
+    #     constraints that are very unlikely to change in the near future.
     def fetch(key, default_value = NULL)
       if NULL != (value = get_or_default(key, NULL))
         value
@@ -127,23 +177,39 @@ module Concurrent
       end
     end
 
-    # @!macro map_method_not_atomic
+    # Fetch value with key, or store default value when key is absent,
+    # or fail when no default_value is given. This is a two step operation,
+    # therefore not atomic. The store can overwrite other concurrently
+    # stored value.
+    # @param [Object] key
+    # @param [Object] default_value
+    # @yield default value for a key
+    # @yieldparam key [Object]
+    # @yieldreturn [Object] default value
+    # @return [Object] the value or default value
+    # @!macro map.atomic_method_with_block
     def fetch_or_store(key, default_value = NULL)
       fetch(key) do
         put(key, block_given? ? yield(key) : (NULL == default_value ? raise_fetch_no_key : default_value))
       end
     end
 
-    # @!macro map_method_is_atomic
+    # Insert value into map with key if key is absent in one atomic step.
+    # @param [Object] key
+    # @param [Object] value
+    # @return [Object, nil] the value or nil when key was present
     def put_if_absent(key, value)
       computed = false
-      result = compute_if_absent(key) do
+      result   = compute_if_absent(key) do
         computed = true
         value
       end
       computed ? nil : result
     end unless method_defined?(:put_if_absent)
 
+    # Is the value stored in the map. Iterates over all values.
+    # @param [Object] value
+    # @return [true, false]
     def value?(value)
       each_value do |v|
         return true if value.equal?(v)
@@ -151,52 +217,86 @@ module Concurrent
       false
     end
 
+    # All keys
+    # @return [::Array<Object>] keys
     def keys
       arr = []
-      each_pair {|k, v| arr << k}
+      each_pair { |k, v| arr << k }
       arr
     end unless method_defined?(:keys)
 
+    # All values
+    # @return [::Array<Object>] values
     def values
       arr = []
-      each_pair {|k, v| arr << v}
+      each_pair { |k, v| arr << v }
       arr
     end unless method_defined?(:values)
 
+    # Iterates over each key.
+    # @yield for each key in the map
+    # @yieldparam key [Object]
+    # @return [self]
+    # @!macro map.atomic_method_with_block
     def each_key
-      each_pair {|k, v| yield k}
+      each_pair { |k, v| yield k }
     end unless method_defined?(:each_key)
 
+    # Iterates over each value.
+    # @yield for each value in the map
+    # @yieldparam value [Object]
+    # @return [self]
+    # @!macro map.atomic_method_with_block
     def each_value
-      each_pair {|k, v| yield v}
+      each_pair { |k, v| yield v }
     end unless method_defined?(:each_value)
 
+    # Iterates over each key value pair.
+    # @yield for each key value pair in the map
+    # @yieldparam key [Object]
+    # @yieldparam value [Object]
+    # @return [self]
+    # @!macro map.atomic_method_with_block
+    def each_pair
+      return enum_for :each_pair unless block_given?
+      super
+    end
+
     alias_method :each, :each_pair unless method_defined?(:each)
 
+    # Find key of a value.
+    # @param [Object] value
+    # @return [Object, nil] key or nil when not found
     def key(value)
-      each_pair {|k, v| return k if v == value}
+      each_pair { |k, v| return k if v == value }
       nil
     end unless method_defined?(:key)
     alias_method :index, :key if RUBY_VERSION < '1.9'
 
+    # Is map empty?
+    # @return [true, false]
     def empty?
-      each_pair {|k, v| return false}
+      each_pair { |k, v| return false }
       true
     end unless method_defined?(:empty?)
 
+    # The size of map.
+    # @return [Integer] size
     def size
       count = 0
-      each_pair {|k, v| count += 1}
+      each_pair { |k, v| count += 1 }
       count
     end unless method_defined?(:size)
 
+    # @!visibility private
     def marshal_dump
       raise TypeError, "can't dump hash with default proc" if @default_proc
       h = {}
-      each_pair {|k, v| h[k] = v}
+      each_pair { |k, v| h[k] = v }
       h
     end
 
+    # @!visibility private
     def marshal_load(hash)
       initialize
       populate_from(hash)
@@ -205,15 +305,12 @@ module Concurrent
     undef :freeze
 
     # @!visibility private
-    DEFAULT_OBJ_ID_STR_WIDTH = 0.size == 4 ? 7 : 14 # we want to look "native", 7 for 32-bit, 14 for 64-bit
-    # override default #inspect() method: firstly, we don't want to be spilling our guts (i-vars), secondly, MRI backend's
-    # #inspect() call on its @backend i-var will bump @backend's iter level while possibly yielding GVL
     def inspect
-      id_str = (object_id << 1).to_s(16).rjust(DEFAULT_OBJ_ID_STR_WIDTH, '0')
-      "#<#{self.class.name}:0x#{id_str} entries=#{size} default_proc=#{@default_proc.inspect}>"
+      format '%s entries=%d default_proc=%s>', to_s[0..-2], size.to_s, @default_proc.inspect
     end
 
     private
+
     def raise_fetch_no_key
       raise KeyError, 'key not found'
     end
@@ -224,7 +321,7 @@ module Concurrent
     end
 
     def populate_from(hash)
-      hash.each_pair {|k, v| self[k] = v}
+      hash.each_pair { |k, v| self[k] = v }
       self
     end
 

data/lib/concurrent/maybe.rb

@@ -108,7 +108,7 @@ module Concurrent
     # Indicates that the given attribute has not been set.
     # When `Just` the {#nothing} getter will return `NONE`.
     # When `Nothing` the {#just} getter will return `NONE`.
-    NONE = Object.new.freeze
+    NONE = ::Object.new.freeze
 
     # The value of a `Maybe` when `Just`. Will be `NONE` when `Nothing`.
     attr_reader :just

data/lib/concurrent/mutable_struct.rb

@@ -10,7 +10,7 @@ module Concurrent
   module MutableStruct
     include Synchronization::AbstractStruct
 
-    # @!macro [new] struct_new
+    # @!macro struct_new
     #
     #   Factory for creating new struct classes.
     #
@@ -42,7 +42,7 @@ module Concurrent
     #
     #   @see http://ruby-doc.org/core-2.2.0/Struct.html#method-c-new Ruby standard library `Struct#new`
 
-    # @!macro [attach] struct_values
+    # @!macro struct_values
     #
     #   Returns the values for this struct as an Array.
     #
@@ -53,7 +53,7 @@ module Concurrent
     end
     alias_method :to_a, :values
 
-    # @!macro [attach] struct_values_at
+    # @!macro struct_values_at
     #
     #   Returns the struct member values for each selector as an Array.
     #
@@ -64,7 +64,7 @@ module Concurrent
       synchronize { ns_values_at(indexes) }
     end
 
-    # @!macro [attach] struct_inspect
+    # @!macro struct_inspect
     #
     #   Describe the contents of this struct in a string.
     #
@@ -74,7 +74,7 @@ module Concurrent
     end
     alias_method :to_s, :inspect
 
-    # @!macro [attach] struct_merge
+    # @!macro struct_merge
     #
     #   Returns a new struct containing the contents of `other` and the contents
     #   of `self`. If no block is specified, the value for entries with duplicate
@@ -95,7 +95,7 @@ module Concurrent
       synchronize { ns_merge(other, &block) }
     end
 
-    # @!macro [attach] struct_to_h
+    # @!macro struct_to_h
     #
     #   Returns a hash containing the names and values for the struct’s members.
     #
@@ -104,11 +104,11 @@ module Concurrent
       synchronize { ns_to_h }
     end
 
-    # @!macro [attach] struct_get
+    # @!macro struct_get
     #
     #   Attribute Reference
     #
-    #   @param [Symbol, String, Integer] member the string or symbol name of the memeber
+    #   @param [Symbol, String, Integer] member the string or symbol name of the member
     #     for which to obtain the value or the member's index
     #
     #   @return [Object] the value of the given struct member or the member at the given index.
@@ -119,7 +119,7 @@ module Concurrent
       synchronize { ns_get(member) }
     end
 
-    # @!macro [attach] struct_equality
+    # @!macro struct_equality
     #
     #   Equality
     #
@@ -129,7 +129,7 @@ module Concurrent
       synchronize { ns_equality(other) }
     end
 
-    # @!macro [attach] struct_each
+    # @!macro struct_each
     #
     #   Yields the value of each struct member in order. If no block is given
     #   an enumerator is returned.
@@ -141,7 +141,7 @@ module Concurrent
       synchronize { ns_each(&block) }
     end
 
-    # @!macro [attach] struct_each_pair
+    # @!macro struct_each_pair
     #
     #   Yields the name and value of each struct member in order. If no block is
     #   given an enumerator is returned.
@@ -154,7 +154,7 @@ module Concurrent
       synchronize { ns_each_pair(&block) }
     end
 
-    # @!macro [attach] struct_select
+    # @!macro struct_select
     #
     #   Yields each member value from the struct to the block and returns an Array
     #   containing the member values from the struct for which the given block
@@ -169,13 +169,13 @@ module Concurrent
       synchronize { ns_select(&block) }
     end
 
-    # @!macro [new] struct_set
+    # @!macro struct_set
     #
     #   Attribute Assignment
     #
     #   Sets the value of the given struct member or the member at the given index.
     #
-    #   @param [Symbol, String, Integer] member the string or symbol name of the memeber
+    #   @param [Symbol, String, Integer] member the string or symbol name of the member
     #     for which to obtain the value or the member's index
     #
     #   @return [Object] the value of the given struct member or the member at the given index.
@@ -212,6 +212,7 @@ module Concurrent
         synchronize do
           clazz = Synchronization::AbstractStruct.define_struct_class(MutableStruct, Synchronization::LockableObject, name, members, &block)
           members.each_with_index do |member, index|
+            clazz.send :remove_method, member
             clazz.send(:define_method, member) do
               synchronize { @values[index] }
             end

data/lib/concurrent/mvar.rb

@@ -40,11 +40,11 @@ module Concurrent
     safe_initialization!
 
     # Unique value that represents that an `MVar` was empty
-    EMPTY = Object.new
+    EMPTY = ::Object.new
 
     # Unique value that represents that an `MVar` timed out before it was able
     # to produce a value.
-    TIMEOUT = Object.new
+    TIMEOUT = ::Object.new
 
     # Create a new `MVar`, either empty or with an initial value.
     #

data/lib/concurrent/promise.rb

@@ -161,15 +161,15 @@ module Concurrent
   # receive the rejection `reason` as the rejection callable parameter:
   #
   # ```ruby
-  # p = [ Concurrent::Promise.execute{ Thread.pass; raise StandardError } ]
+  # p = Concurrent::Promise.execute { Thread.pass; raise StandardError }
   #
-  # c1 = p.then(Proc.new{ |reason| 42 })
-  # c2 = p.then(Proc.new{ |reason| raise 'Boom!' })
+  # c1 = p.then(-> reason { 42 })
+  # c2 = p.then(-> reason { raise 'Boom!' })
   #
-  # sleep(0.1)
-  #
-  # c1.state  #=> :rejected
-  # c2.state  #=> :rejected
+  # c1.wait.state  #=> :fulfilled
+  # c1.value       #=> 45
+  # c2.wait.state  #=> :rejected
+  # c2.reason      #=> #<RuntimeError: Boom!>
   # ```
   #
   # Once a promise is rejected it will continue to accept children that will
@@ -193,7 +193,7 @@ module Concurrent
     #
     # @!macro executor_and_deref_options
     #
-    # @!macro [attach] promise_init_options
+    # @!macro promise_init_options
     #
     #   @option opts [Promise] :parent the parent `Promise` when building a chain/tree
     #   @option opts [Proc] :on_fulfill fulfillment handler
@@ -298,16 +298,28 @@ module Concurrent
 
     # Chain a new promise off the current promise.
     #
-    # @param [Proc] rescuer An optional rescue block to be executed if the
-    #   promise is rejected.
-    #
-    # @param [ThreadPool] executor An optional thread pool executor to be used
-    # in the new Promise
-    #
-    # @yield The block operation to be performed asynchronously.
-    #
     # @return [Promise] the new promise
-    def then(rescuer = nil, executor = @executor, &block)
+    # @yield The block operation to be performed asynchronously.
+    # @overload then(rescuer, executor, &block)
+    #   @param [Proc] rescuer An optional rescue block to be executed if the
+    #     promise is rejected.
+    #   @param [ThreadPool] executor An optional thread pool executor to be used
+    #     in the new Promise
+    # @overload then(rescuer, executor: executor, &block)
+    #   @param [Proc] rescuer An optional rescue block to be executed if the
+    #     promise is rejected.
+    #   @param [ThreadPool] executor An optional thread pool executor to be used
+    #     in the new Promise
+    def then(*args, &block)
+      if args.last.is_a?(::Hash)
+        executor = args.pop[:executor]
+        rescuer = args.first
+      else
+        rescuer, executor = args
+      end
+
+      executor ||= @executor
+
       raise ArgumentError.new('rescuers and block are both missing') if rescuer.nil? && !block_given?
       block = Proc.new { |result| result } unless block_given?
       child = Promise.new(
@@ -383,11 +395,24 @@ module Concurrent
     # Builds a promise that produces the result of promises in an Array
     # and fails if any of them fails.
     #
-    # @param [Array<Promise>] promises
+    # @overload zip(*promises)
+    #   @param [Array<Promise>] promises
+    #
+    # @overload zip(*promises, opts)
+    #   @param [Array<Promise>] promises
+    #   @param [Hash] opts the configuration options
+    #   @option opts [Executor] :executor (ImmediateExecutor.new) when set use the given `Executor` instance.
+    #   @option opts [Boolean] :execute (true) execute promise before returning
     #
     # @return [Promise<Array>]
     def self.zip(*promises)
-      zero = fulfill([], executor: ImmediateExecutor.new)
+      opts = promises.last.is_a?(::Hash) ? promises.pop.dup : {}
+      opts[:executor] ||= ImmediateExecutor.new
+      zero = if !opts.key?(:execute) || opts.delete(:execute)
+        fulfill([], opts)
+      else
+        Promise.new(opts) { [] }
+      end
 
       promises.reduce(zero) do |p1, p2|
         p1.flat_map do |results|
@@ -401,7 +426,14 @@ module Concurrent
     # Builds a promise that produces the result of self and others in an Array
     # and fails if any of them fails.
     #
-    # @param [Array<Promise>] others
+    # @overload zip(*promises)
+    #   @param [Array<Promise>] others
+    #
+    # @overload zip(*promises, opts)
+    #   @param [Array<Promise>] others
+    #   @param [Hash] opts the configuration options
+    #   @option opts [Executor] :executor (ImmediateExecutor.new) when set use the given `Executor` instance.
+    #   @option opts [Boolean] :execute (true) execute promise before returning
     #
     # @return [Promise<Array>]
     def zip(*others)
@@ -414,7 +446,7 @@ module Concurrent
     # fail. Upon execution will execute any of the aggregate promises that
     # were not already executed.
     #
-    # @!macro [attach] promise_self_aggregate
+    # @!macro promise_self_aggregate
     #
     #   The returned promise will not yet have been executed. Additional `#then`
     #   and `#rescue` handlers may still be provided. Once the returned promise