concurrent-ruby 0.9.2 → 1.0.0.pre1

data/lib/concurrent/concern/logging.rb

@@ -9,7 +9,7 @@ module Concurrent
     module Logging
       include Logger::Severity
 
-      # Logs through {Configuration#logger}, it can be overridden by setting @logger
+      # Logs through {Concurrent.global_logger}, it can be overridden by setting @logger
       # @param [Integer] level one of Logger::Severity constants
       # @param [String] progname e.g. a path of an Actor
       # @param [String, nil] message when nil block is used to generate the message

data/lib/concurrent/concern/obligation.rb

@@ -3,14 +3,12 @@ require 'timeout'
 
 require 'concurrent/atomic/event'
 require 'concurrent/concern/dereferenceable'
-require 'concurrent/concern/deprecation'
 
 module Concurrent
   module Concern
 
     module Obligation
       include Concern::Dereferenceable
-      include Concern::Deprecation
 
       # Has the obligation been fulfilled?
       #
@@ -48,16 +46,6 @@ module Concurrent
         [:fulfilled, :rejected].include? state
       end
 
-      # Has the obligation completed processing?
-      #
-      # @return [Boolean]
-      #
-      # @deprecated
-      def completed?
-        deprecated_method 'completed?', 'complete?'
-        complete?
-      end
-
       # Is the obligation still awaiting completion of processing?
       #
       # @return [Boolean]

data/lib/concurrent/configuration.rb

@@ -2,7 +2,6 @@ require 'thread'
 require 'concurrent/delay'
 require 'concurrent/errors'
 require 'concurrent/atomic/atomic_reference'
-require 'concurrent/concern/deprecation'
 require 'concurrent/concern/logging'
 require 'concurrent/executor/timer_set'
 require 'concurrent/executor/immediate_executor'
@@ -13,7 +12,6 @@ require 'concurrent/utility/processor_counter'
 
 module Concurrent
   extend Concern::Logging
-  extend Concern::Deprecation
 
   # @return [Logger] Logger with provided level and output.
   def self.create_stdlib_logger(level = Logger::FATAL, output = $stderr)
@@ -25,19 +23,19 @@ module Concurrent
                             msg
                           when Exception
                             format "%s (%s)\n%s",
-                                   msg.message, msg.class, (msg.backtrace || []).join("\n")
+                              msg.message, msg.class, (msg.backtrace || []).join("\n")
                           else
                             msg.inspect
                           end
       format "[%s] %5s -- %s: %s\n",
-             datetime.strftime('%Y-%m-%d %H:%M:%S.%L'),
-             severity,
-             progname,
-             formatted_message
+        datetime.strftime('%Y-%m-%d %H:%M:%S.%L'),
+        severity,
+        progname,
+        formatted_message
     end
 
     lambda do |loglevel, progname, message = nil, &block|
-      logger.add loglevel, message, progname, &block
+    logger.add loglevel, message, progname, &block
     end
   end
 
@@ -95,25 +93,6 @@ module Concurrent
     AtExit.enabled = false
   end
 
-  def self.disable_executor_auto_termination!
-    deprecated_method 'disable_executor_auto_termination!', 'disable_at_exit_handlers!'
-    disable_at_exit_handlers!
-  end
-
-  # @return [true,false]
-  # @see .disable_executor_auto_termination!
-  def self.disable_executor_auto_termination?
-    deprecated_method 'disable_executor_auto_termination?', 'Concurrent::AtExit.enabled?'
-    AtExit.enabled?
-  end
-
-  # terminates all pools and blocks until they are terminated
-  # @see .disable_executor_auto_termination!
-  def self.terminate_pools!
-    deprecated_method 'terminate_pools!', 'Concurrent::AtExit.run'
-    AtExit.run
-  end
-
   # Global thread pool optimized for short, fast *operations*.
   #
   # @return [ThreadPoolExecutor] the thread pool
@@ -151,132 +130,23 @@ module Concurrent
 
   def self.new_fast_executor(opts = {})
     FixedThreadPool.new(
-        [2, Concurrent.processor_count].max,
-        auto_terminate:  opts.fetch(:auto_terminate, true),
-        idletime:        60, # 1 minute
-        max_queue:       0, # unlimited
-        fallback_policy: :abort # shouldn't matter -- 0 max queue
+      [2, Concurrent.processor_count].max,
+      auto_terminate:  opts.fetch(:auto_terminate, true),
+      idletime:        60, # 1 minute
+      max_queue:       0, # unlimited
+      fallback_policy: :abort # shouldn't matter -- 0 max queue
     )
   end
 
   def self.new_io_executor(opts = {})
     ThreadPoolExecutor.new(
-        min_threads:     [2, Concurrent.processor_count].max,
-        max_threads:     ThreadPoolExecutor::DEFAULT_MAX_POOL_SIZE,
-        # max_threads:     1000,
-        auto_terminate:  opts.fetch(:auto_terminate, true),
-        idletime:        60, # 1 minute
-        max_queue:       0, # unlimited
-        fallback_policy: :abort # shouldn't matter -- 0 max queue
+      min_threads:     [2, Concurrent.processor_count].max,
+      max_threads:     ThreadPoolExecutor::DEFAULT_MAX_POOL_SIZE,
+      # max_threads:     1000,
+      auto_terminate:  opts.fetch(:auto_terminate, true),
+      idletime:        60, # 1 minute
+      max_queue:       0, # unlimited
+      fallback_policy: :abort # shouldn't matter -- 0 max queue
     )
   end
-
-  # A gem-level configuration object.
-  class Configuration
-    include Concern::Deprecation
-
-    # Create a new configuration object.
-    def initialize
-    end
-
-    # if assigned to {#logger}, it will log nothing.
-    # @deprecated Use Concurrent::NULL_LOGGER instead
-    def no_logger
-      deprecated_method 'Concurrent.configuration.no_logger', 'Concurrent::NULL_LOGGER'
-      NULL_LOGGER
-    end
-
-    # a proc defining how to log messages, its interface has to be:
-    #   lambda { |level, progname, message = nil, &block| _ }
-    #
-    # @deprecated Use Concurrent.global_logger instead
-    def logger
-      deprecated_method 'Concurrent.configuration.logger', 'Concurrent.global_logger'
-      Concurrent.global_logger.value
-    end
-
-    # a proc defining how to log messages, its interface has to be:
-    #   lambda { |level, progname, message = nil, &block| _ }
-    #
-    # @deprecated Use Concurrent.global_logger instead
-    def logger=(value)
-      deprecated_method 'Concurrent.configuration.logger=', 'Concurrent.global_logger='
-      Concurrent.global_logger = value
-    end
-
-    # @deprecated Use Concurrent.global_io_executor instead
-    def global_task_pool
-      deprecated_method 'Concurrent.configuration.global_task_pool', 'Concurrent.global_io_executor'
-      Concurrent.global_io_executor
-    end
-
-    # @deprecated Use Concurrent.global_fast_executor instead
-    def global_operation_pool
-      deprecated_method 'Concurrent.configuration.global_operation_pool', 'Concurrent.global_fast_executor'
-      Concurrent.global_fast_executor
-    end
-
-    # @deprecated Use Concurrent.global_timer_set instead
-    def global_timer_set
-      deprecated_method 'Concurrent.configuration.global_timer_set', 'Concurrent.global_timer_set'
-      Concurrent.global_timer_set
-    end
-
-    # @deprecated Replacing global thread pools is deprecated.
-    #   Use the :executor constructor option instead.
-    def global_task_pool=(executor)
-      deprecated 'Replacing global thread pools is deprecated. Use the :executor constructor option instead.'
-      GLOBAL_IO_EXECUTOR.reconfigure { executor } or
-          raise ConfigurationError.new('global task pool was already set')
-    end
-
-    # @deprecated Replacing global thread pools is deprecated.
-    #   Use the :executor constructor option instead.
-    def global_operation_pool=(executor)
-      deprecated 'Replacing global thread pools is deprecated. Use the :executor constructor option instead.'
-      GLOBAL_FAST_EXECUTOR.reconfigure { executor } or
-          raise ConfigurationError.new('global operation pool was already set')
-    end
-
-    # @deprecated Use Concurrent.new_io_executor instead
-    def new_task_pool
-      deprecated_method 'Concurrent.configuration.new_task_pool', 'Concurrent.new_io_executor'
-      Concurrent.new_io_executor
-    end
-
-    # @deprecated Use Concurrent.new_fast_executor instead
-    def new_operation_pool
-      deprecated_method 'Concurrent.configuration.new_operation_pool', 'Concurrent.new_fast_executor'
-      Concurrent.new_fast_executor
-    end
-
-    # @deprecated Use Concurrent.disable_executor_auto_termination! instead
-    def auto_terminate=(value)
-      deprecated_method 'Concurrent.configuration.auto_terminate=', 'Concurrent.disable_executor_auto_termination!'
-      Concurrent.disable_executor_auto_termination! if !value
-    end
-
-    # @deprecated Use Concurrent.auto_terminate_global_executors? instead
-    def auto_terminate
-      deprecated_method 'Concurrent.configuration.auto_terminate', 'Concurrent.auto_terminate_global_executors?'
-      Concurrent.auto_terminate_global_executors?
-    end
-  end
-
-  # create the default configuration on load
-  CONFIGURATION = AtomicReference.new(Configuration.new)
-  private_constant :CONFIGURATION
-
-  # @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
 end

data/lib/concurrent/delay.rb

@@ -1,4 +1,5 @@
 require 'thread'
+require 'concurrent/configuration'
 require 'concurrent/concern/obligation'
 require 'concurrent/executor/executor'
 require 'concurrent/executor/immediate_executor'
@@ -78,7 +79,7 @@ module Concurrent
       else
         # this function has been optimized for performance and
         # should not be modified without running new benchmarks
-        mutex.synchronize do
+        synchronize do
           execute = @computing = true unless @computing
           if execute
             begin
@@ -140,7 +141,7 @@ module Concurrent
     # @yield the delayed operation to perform
     # @return [true, false] if success
     def reconfigure(&block)
-      mutex.synchronize do
+      synchronize do
         raise ArgumentError.new('no block given') unless block_given?
         unless @computing
           @task = block
@@ -170,7 +171,7 @@ module Concurrent
       # this function has been optimized for performance and
       # should not be modified without running new benchmarks
       execute = task = nil
-      mutex.synchronize do
+      synchronize do
         execute = @computing = true unless @computing
         task    = @task
       end
@@ -183,7 +184,7 @@ module Concurrent
           rescue => ex
             reason = ex
           end
-          mutex.synchronize do
+          synchronize do
             set_state(success, result, reason)
             event.set
           end

data/lib/concurrent/exchanger.rb

@@ -1,58 +1,344 @@
+require 'concurrent/errors'
+require 'concurrent/maybe'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/count_down_latch'
+require 'concurrent/utility/engine'
+require 'concurrent/utility/monotonic_time'
+
 module Concurrent
 
-  # A synchronization point at which threads can pair and swap elements within
-  # pairs. Each thread presents some object on entry to the exchange method,
-  # matches with a partner thread, and receives its partner's object on return.
+  # @!macro [attach] exchanger
+  #
+  #   A synchronization point at which threads can pair and swap elements within
+  #   pairs. Each thread presents some object on entry to the exchange method,
+  #   matches with a partner thread, and receives its partner's object on return.
+  #
+  #   This implementation is very simple, using only a single slot for each
+  #   exchanger (unlike more advanced implementations which use an "arena").
+  #   This approach will work perfectly fine when there are only a few threads
+  #   accessing a single `Exchanger`. Beyond a handful of threads the performance
+  #   will degrade rapidly due to contention on the single slot, but the algorithm
+  #   will remain correct.
+  #
+  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html java.util.concurrent.Exchanger
+  #
+  #   @!macro edge_warning
   #
-  # Uses `MVar` to manage synchronization of the individual elements.
-  # Since `MVar` is also a `Dereferenceable`, the exchanged values support all
-  # dereferenceable options. The constructor options hash will be passed to
-  # the `MVar` constructors.
-  # 
-  # @see Concurrent::MVar
-  # @see Concurrent::Concern::Dereferenceable
-  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html java.util.concurrent.Exchanger
+  #   @example
   #
-  # @!macro edge_warning
-  class Exchanger
+  #     exchanger = Concurrent::Exchanger.new
+  #
+  #     threads = [
+  #       Thread.new { puts "first: " << exchanger.exchange('foo', 1) }, #=> "first: bar"
+  #       Thread.new { puts "second: " << exchanger.exchange('bar', 1) } #=> "second: foo"
+  #     ]
+  #     threads.each {|t| t.join(2) }
+  #
+  # @!visibility private
+  class AbstractExchanger
 
-    EMPTY = Object.new
+    # @!visibility private
+    CANCEL = Object.new
+    private_constant :CANCEL
 
-    # Create a new `Exchanger` object.
-    #
-    # @param [Hash] opts the options controlling how the managed references
-    #   will be processed
-    def initialize(opts = {})
-      @first = MVar.new(EMPTY, opts)
-      @second = MVar.new(MVar::EMPTY, opts)
+    # @!macro [attach] exchanger_method_initialize
+    def initialize
+      raise NotImplementedError
     end
 
-    # Waits for another thread to arrive at this exchange point (unless the
-    # current thread is interrupted), and then transfers the given object to
-    # it, receiving its object in return.
+    # @!macro [attach] exchanger_method_do_exchange
+    #
+    #   Waits for another thread to arrive at this exchange point (unless the
+    #   current thread is interrupted), and then transfers the given object to
+    #   it, receiving its object in return. The timeout value indicates the
+    #   approximate number of seconds the method should block while waiting
+    #   for the exchange. When the timeout value is `nil` the method will
+    #   block indefinitely.
     #
-    # @param [Object] value the value to exchange with an other thread
-    # @param [Numeric] timeout the maximum time in second to wait for one other
-    #   thread. nil (default value) means no timeout
-    # @return [Object] the value exchanged by the other thread; nil if timed out
+    #   @param [Object] value the value to exchange with another thread
+    #   @param [Numeric, nil] timeout in seconds, `nil` blocks indefinitely
+    #
+    # @!macro [attach] exchanger_method_exchange
+    #
+    #   In some edge cases when a `timeout` is given a return value of `nil` may be
+    #   ambiguous. Specifically, if `nil` is a valid value in the exchange it will
+    #   be impossible to tell whether `nil` is the actual return value or if it
+    #   signifies timeout. When `nil` is a valid value in the exchange consider
+    #   using {#exchange!} or {#try_exchange} instead.
+    #
+    #   @return [Object] the value exchanged by the other thread or `nil` on timeout
     def exchange(value, timeout = nil)
-      first = @first.take(timeout)
-      if first == MVar::TIMEOUT
-        nil
-      elsif first == EMPTY
-        @first.put value
-        second = @second.take timeout
-        if second == MVar::TIMEOUT
-          nil
+      (value = do_exchange(value, timeout)) == CANCEL ? nil : value
+    end
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @!macro [attach] exchanger_method_exchange_bang
+    #
+    #   On timeout a {Concurrent::TimeoutError} exception will be raised.
+    #
+    #   @return [Object] the value exchanged by the other thread
+    #   @raise [Concurrent::TimeoutError] on timeout
+    def exchange!(value, timeout = nil)
+      if (value = do_exchange(value, timeout)) == CANCEL
+        raise Concurrent::TimeoutError
+      else
+        value
+      end
+    end
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @!macro [attach] exchanger_method_try_exchange
+    #
+    #   The return value will be a {Concurrent::Maybe} set to `Just` on success or
+    #   `Nothing` on timeout.
+    #
+    #   @return [Concurrent::Maybe] on success a `Just` maybe will be returned with
+    #     the item exchanged by the other thread as `#value`; on timeout a
+    #     `Nothing` maybe will be returned with {Concurrent::TimeoutError} as `#reason`
+    #
+    #   @example
+    #
+    #     exchanger = Concurrent::Exchanger.new
+    #
+    #     result = exchanger.exchange(:foo, 0.5)
+    #
+    #     if result.just?
+    #       puts result.value #=> :bar
+    #     else
+    #       puts 'timeout'
+    #     end
+    def try_exchange(value, timeout = nil)
+      if (value = do_exchange(value, timeout)) == CANCEL
+        Concurrent::Maybe.nothing(Concurrent::TimeoutError)
+      else
+        Concurrent::Maybe.just(value)
+      end
+    end
+
+    private
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+    def do_exchange(value, timeout)
+      raise NotImplementedError
+    end
+  end
+
+  # @!macro exchanger
+  # @!macro internal_implementation_note
+  # @!visibility private
+  class RubyExchanger < AbstractExchanger
+    # A simplified version of java.util.concurrent.Exchanger written by
+    # Doug Lea, Bill Scherer, and Michael Scott with assistance from members
+    # of JCP JSR-166 Expert Group and released to the public domain. It does
+    # not include the arena or the multi-processor spin loops.
+    # http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/6-b14/java/util/concurrent/Exchanger.java
+
+    # @!visibility private
+    NIL_SENTINEL = Object.new
+    private_constant :NIL_SENTINEL
+
+    # @!visibility private
+    class Node < Concurrent::AtomicReference
+      attr_reader :item, :latch
+      def initialize(item)
+        @item = item
+        @latch = Concurrent::CountDownLatch.new
+        super(nil)
+      end
+    end
+    private_constant :Node
+
+    # @!macro exchanger_method_initialize
+    def initialize
+      @slot = Concurrent::AtomicReference.new
+    end
+
+    private
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+    def do_exchange(value, timeout)
+
+      # ALGORITHM
+      #
+      # From the original Java version:
+      #
+      # > The basic idea is to maintain a "slot", which is a reference to
+      # > a Node containing both an Item to offer and a "hole" waiting to
+      # > get filled in.  If an incoming "occupying" thread sees that the
+      # > slot is null, it CAS'es (compareAndSets) a Node there and waits
+      # > for another to invoke exchange.  That second "fulfilling" thread
+      # > sees that the slot is non-null, and so CASes it back to null,
+      # > also exchanging items by CASing the hole, plus waking up the
+      # > occupying thread if it is blocked.  In each case CAS'es may
+      # > fail because a slot at first appears non-null but is null upon
+      # > CAS, or vice-versa.  So threads may need to retry these
+      # > actions.
+      #
+      # This version:
+      #
+      # An exchange occurs between an "occupier" thread and a "fulfiller" thread.
+      # The "slot" is used to setup this interaction. The first thread in the
+      # exchange puts itself into the slot (occupies) and waits for a fulfiller.
+      # The second thread removes the occupier from the slot and attempts to
+      # perform the exchange. Removing the occupier also frees the slot for
+      # another occupier/fulfiller pair.
+      #
+      # Because the occupier and the fulfiller are operating independently and
+      # because there may be contention with other threads, any failed operation
+      # indicates contention. Both the occupier and the fulfiller operate within
+      # spin loops. Any failed actions along the happy path will cause the thread
+      # to repeat the loop and try again.
+      #
+      # When a timeout value is given the thread must be cognizant of time spent
+      # in the spin loop. The remaining time is checked every loop. When the time
+      # runs out the thread will exit.
+      #
+      # A "node" is the data structure used to perform the exchange. Only the
+      # occupier's node is necessary. It's the node used for the exchange.
+      # Each node has an "item," a "hole" (self), and a "latch." The item is the
+      # node's initial value. It never changes. It's what the fulfiller returns on
+      # success. The occupier's hole is where the fulfiller put its item. It's the
+      # item that the occupier returns on success. The latch is used for synchronization.
+      # Becuase a thread may act as either an occupier or fulfiller (or possibly
+      # both in periods of high contention) every thread creates a node when
+      # the exchange method is first called.
+      #
+      # The following steps occur within the spin loop. If any actions fail
+      # the thread will loop and try again, so long as there is time remaining.
+      # If time runs out the thread will return CANCEL.
+      #
+      # Check the slot for an occupier:
+      #
+      #   * If the slot is empty try to occupy
+      #   * If the slot is full try to fulfill
+      #
+      # Attempt to occupy:
+      #
+      #   * Attempt to CAS myself into the slot
+      #   * Go to sleep and wait to be woken by a fulfiller
+      #   * If the sleep is successful then the fulfiller completed its happy path
+      #     - Return the value from my hole (the value given by the fulfiller)
+      #   * When the sleep fails (time ran out) attempt to cancel the operation
+      #     - Attempt to CAS myself out of the hole
+      #     - If successful there is no contention
+      #       - Return CANCEL
+      #     - On failure, I am competing with a fulfiller
+      #       - Attempt to CAS my hole to CANCEL
+      #       - On success
+      #         - Let the fulfiller deal with my cancel
+      #         - Return CANCEL
+      #       - On failure the fulfiller has completed its happy path
+      #         - Return th value from my hole (the fulfiller's value)
+      #
+      # Attempt to fulfill:
+      #
+      # * Attempt to CAS the occupier out of the slot
+      #   - On failure loop again
+      # * Attempt to CAS my item into the occupier's hole
+      #   - On failure the occupier is trying to cancel
+      #     - Loop again
+      #   - On success we are on the happy path
+      #     - Wake the sleeping occupier
+      #     - Return the occupier's item
+
+      value = NIL_SENTINEL if value.nil?                # The sentinel allows nil to be a valid value
+      slot = @slot                                      # Convenience to minimize typing @
+      me = Node.new(value)                              # create my node in case I need to occupy
+      end_at = Concurrent.monotonic_time + timeout.to_f # The time to give up
+
+      result = loop do
+        other = slot.get
+        if other && slot.compare_and_set(other, nil)
+          # try to fulfill
+          if other.compare_and_set(nil, value)
+            # happy path
+            other.latch.count_down
+            break other.item
+          end
+        elsif other.nil? && slot.compare_and_set(nil, me)
+          # try to occupy
+          timeout = end_at - Concurrent.monotonic_time if timeout
+          if me.latch.wait(timeout)
+            # happy path
+            break me.value
+          else
+            # attempt to remove myself from the slot
+            if slot.compare_and_set(me, nil)
+              break CANCEL
+            elsif !me.compare_and_set(nil, CANCEL)
+              # I've failed to block the fulfiller
+              break me.get
+            end
+          end
+        end
+        break CANCEL if timeout && Concurrent.monotonic_time >= end_at
+      end
+
+      result == NIL_SENTINEL ? nil : result
+    end
+  end
+
+  if Concurrent.on_jruby?
+
+    # @!macro exchanger
+    # @!macro internal_implementation_note
+    # @!visibility private
+    class JavaExchanger < AbstractExchanger
+
+      # @!macro exchanger_method_initialize
+      def initialize
+        @exchanger = java.util.concurrent.Exchanger.new
+      end
+
+      private
+
+      # @!macro exchanger_method_do_exchange
+      #
+      # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+      def do_exchange(value, timeout)
+        if timeout.nil?
+          @exchanger.exchange(value)
         else
-          second
+          @exchanger.exchange(value, 1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
         end
-      else
-        @first.put EMPTY
-        @second.put value
-        first
+      rescue java.util.concurrent.TimeoutException
+        CANCEL
       end
     end
+  end
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  ExchangerImplementation = case
+                            when Concurrent.on_jruby?
+                              JavaExchanger
+                            else
+                              RubyExchanger
+                            end
+  private_constant :ExchangerImplementation
+
+  # @!macro exchanger
+  class Exchanger < ExchangerImplementation
+
+    # @!method initialize
+    #   @!macro exchanger_method_initialize
+
+    # @!method exchange(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_exchange
+
+    # @!method exchange!(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_exchange_bang
 
+    # @!method try_exchange(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_try_exchange
   end
 end