concurrent-ruby-edge 0.3.1 → 0.4.0.pre1

data/{lib → lib-edge}/concurrent/channel/buffer/base.rb

@@ -15,13 +15,13 @@ module Concurrent
       # used as a channel buffer should extend this class.
       class Base < Synchronization::LockableObject
 
-        # @!macro [attach] channel_buffer_capacity_reader
+        # @!macro channel_buffer_capacity_reader
         #
         #   The maximum number of values which can be {#put} onto the buffer
         #   it becomes full.
         attr_reader :capacity
 
-        # @!macro [attach] channel_buffer_initialize
+        # @!macro channel_buffer_initialize
         #
         #   Creates a new buffer.
         def initialize(*args)
@@ -35,7 +35,7 @@ module Concurrent
           end
         end
 
-        # @!macro [attach] channel_buffer_blocking_question
+        # @!macro channel_buffer_blocking_question
         #
         #   Predicate indicating if this buffer will block {#put} operations
         #   once it reaches its maximum capacity.
@@ -45,14 +45,14 @@ module Concurrent
           true
         end
 
-        # @!macro [attach] channel_buffer_size_reader
+        # @!macro channel_buffer_size_reader
         #
         #   The number of items currently in the buffer.
         def size
           synchronize { ns_size }
         end
 
-        # @!macro [attach] channel_buffer_empty_question
+        # @!macro channel_buffer_empty_question
         #
         #   Predicate indicating if the buffer is empty.
         #
@@ -63,7 +63,7 @@ module Concurrent
           synchronize { ns_empty? }
         end
 
-        # @!macro [attach] channel_buffer_full_question
+        # @!macro channel_buffer_full_question
         #
         #   Predicate indicating if the buffer is full.
         #
@@ -74,7 +74,7 @@ module Concurrent
           synchronize { ns_full? }
         end
 
-        # @!macro [attach] channel_buffer_put
+        # @!macro channel_buffer_put
         #
         #   Put an item onto the buffer if possible. If the buffer is open
         #   but not able to accept the item the calling thread will block
@@ -89,9 +89,9 @@ module Concurrent
           raise NotImplementedError
         end
 
-        # @!macro [attach] channel_buffer_offer
+        # @!macro channel_buffer_offer
         #
-        #   Put an item onto the buffer is possible. If the buffer is open but
+        #   Put an item onto the buffer if possible. If the buffer is open but
         #   unable to add an item, probably due to being full, the method will
         #   return immediately. Similarly, the method will return immediately
         #   when the buffer is closed. A return value of `false` does not
@@ -107,7 +107,7 @@ module Concurrent
           raise NotImplementedError
         end
 
-        # @!macro [attach] channel_buffer_take
+        # @!macro channel_buffer_take
         #
         #   Take an item from the buffer if one is available. If the buffer
         #   is open and no item is available the calling thread will block
@@ -123,7 +123,7 @@ module Concurrent
           raise NotImplementedError
         end
 
-        # @!macro [attach] channel_buffer_next
+        # @!macro channel_buffer_next
         #
         #   Take the next "item" from the buffer and also return a boolean
         #   indicating if "more" items can be taken. Used for iterating
@@ -152,7 +152,7 @@ module Concurrent
           raise NotImplementedError
         end
 
-        # @!macro [attach] channel_buffer_poll
+        # @!macro channel_buffer_poll
         #
         #   Take the next item from the buffer if one is available else return
         #   immediately. Failing to return a value does not necessarily
@@ -166,7 +166,7 @@ module Concurrent
           raise NotImplementedError
         end
 
-        # @!macro [attach] channel_buffer_close
+        # @!macro channel_buffer_close
         #
         #   Close the buffer, preventing new items from being added. Once a
         #   buffer is closed it cannot be opened again.
@@ -179,7 +179,7 @@ module Concurrent
           end
         end
 
-        # @!macro [attach] channel_buffer_closed_question
+        # @!macro channel_buffer_closed_question
         #
         #   Predicate indicating is this buffer closed.
         #

data/{lib → lib-edge}/concurrent/channel/buffer/unbuffered.rb

@@ -131,7 +131,7 @@ module Concurrent
         # waiting to {#put} items onto the buffer. This method exhibits the
         # same blocking behavior as {#take}.
         #
-        # @see {#take}
+        # @see #take
         def next
           item = take
           more = (item != Concurrent::NULL)

data/{lib → lib-edge}/concurrent/channel.rb

@@ -8,7 +8,8 @@ require 'concurrent/executor/cached_thread_pool'
 
 module Concurrent
 
-  # {include:file:doc/channel.md}
+  # {include:file:docs-source/channel.md}
+  # @!macro warn.edge
   class Channel
     extend Forwardable
     include Enumerable

data/{lib → lib-edge}/concurrent/edge/cancellation.rb

@@ -14,6 +14,7 @@ module Concurrent
   #   end
   #   sleep 0.1
   #   cancellation.cancel # Stop the thread by cancelling
+  # @!macro warn.edge
   class Cancellation < Synchronization::Object
     safe_initialization!
 
@@ -54,7 +55,7 @@ module Concurrent
     # Short string representation.
     # @return [String]
     def to_s
-      format '<#%s:0x%x canceled:%s>', self.class, object_id << 1, canceled?
+      format '%s canceled:%s>', super[0..-2], canceled?
     end
 
     alias_method :inspect, :to_s
@@ -113,14 +114,14 @@ module Concurrent
       # @param [Token] tokens to combine
       # @return [Token] new token
       def join(*tokens, &block)
-        block ||= -> tokens { Promises.any_event(*tokens.map(&:to_event)) }
+        block ||= -> token_list { Promises.any_event(*token_list.map(&:to_event)) }
         self.class.new block.call([@Cancel, *tokens])
       end
 
       # Short string representation.
       # @return [String]
       def to_s
-        format '<#%s:0x%x canceled:%s>', self.class, object_id << 1, canceled?
+        format '%s canceled:%s>', super[0..-2], canceled?
       end
 
       alias_method :inspect, :to_s
@@ -132,7 +133,7 @@ module Concurrent
       end
     end
 
-    # FIXME (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
+    # TODO (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
     # TODO (pitr-ch 27-Mar-2016): examples (scheduled to be cancelled in 10 sec)
   end
 end

data/{lib → lib-edge}/concurrent/edge/lock_free_linked_set/node.rb

@@ -1,4 +1,4 @@
-require 'concurrent/edge/atomic_markable_reference'
+require 'concurrent/atomic/atomic_markable_reference'
 
 module Concurrent
   module Edge
@@ -10,7 +10,7 @@ module Concurrent
 
         def initialize(data = nil, successor = nil)
           super()
-          @SuccessorReference = AtomicMarkableReference.new(successor || Tail.new)
+          @SuccessorReference  = AtomicMarkableReference.new(successor || Tail.new)
           @Data                = data
           @Key                 = key_for data
         end

data/{lib → lib-edge}/concurrent/edge/lock_free_linked_set.rb

@@ -18,12 +18,13 @@ module Concurrent
     #
     # This algorithm is a variation of the Nonblocking Linked Set found in
     # 'The Art of Multiprocessor Programming' by Herlihy and Shavit.
+    # @!macro warn.edge
     class LockFreeLinkedSet
       include Enumerable
 
-      # @!macro [attach] lock_free_linked_list_method_initialize
+      # @!macro lock_free_linked_list_method_initialize
       #
-      # @param [Fixnum] initial_size the size of the linked_list to initialize
+      #   @param [Fixnum] initial_size the size of the linked_list to initialize
       def initialize(initial_size = 0, val = nil)
         @head = Head.new
 
@@ -33,7 +34,7 @@ module Concurrent
         end
       end
 
-      # @!macro [attach] lock_free_linked_list_method_add
+      # @!macro lock_free_linked_list_method_add
       #
       #   Atomically adds the item to the set if it does not yet exist. Note:
       #   internally the set uses `Object#hash` to compare equality of items,
@@ -61,7 +62,7 @@ module Concurrent
         end
       end
 
-      # @!macro [attach] lock_free_linked_list_method_<<
+      # @!macro lock_free_linked_list_method_<<
       #
       #   Atomically adds the item to the set if it does not yet exist.
       #
@@ -73,7 +74,7 @@ module Concurrent
         self
       end
 
-      # @!macro [attach] lock_free_linked_list_method_contains
+      # @!macro lock_free_linked_list_method_contains
       #
       #   Atomically checks to see if the set contains an item. This method
       #   compares equality based on the `Object#hash` method, meaning that the
@@ -94,7 +95,7 @@ module Concurrent
         curr == item && !marked
       end
 
-      # @!macro [attach] lock_free_linked_list_method_remove
+      # @!macro lock_free_linked_list_method_remove
       #
       #   Atomically attempts to remove an item, comparing using `Object#hash`.
       #
@@ -120,7 +121,7 @@ module Concurrent
         end
       end
 
-      # @!macro [attach] lock_free_linked_list_method_each
+      # @!macro lock_free_linked_list_method_each
       #
       #   An iterator to loop through the set.
       #

data/{lib → lib-edge}/concurrent/edge/processing_actor.rb

@@ -13,7 +13,7 @@ module Concurrent
   #     values = actors.map(&:termination).map(&:value)
   #     values[0,5]                                        # => [1, 2, 3, 4, 5]
   #     values[-5, 5]                                      # => [49996, 49997, 49998, 49999, 50000]
-  # @!macro edge_warning
+  # @!macro warn.edge
   class ProcessingActor < Synchronization::Object
     # TODO (pitr-ch 18-Dec-2016): (un)linking, bidirectional, sends special message, multiple link calls has no effect,
     # TODO (pitr-ch 21-Dec-2016): Make terminated a cancellation token?
@@ -135,7 +135,7 @@ module Concurrent
       ).chain do |fulfilled, (which, value), (_, reason)|
         # TODO (pitr-ch 20-Jan-2017): we have to know which future was resolved
         # TODO (pitr-ch 20-Jan-2017): make the combinator programmable, so anyone can create what is needed
-        # TODO (pitr-ch 19-Jan-2017): ensure no callbacks are accumulated on @Terminated
+        # FIXME (pitr-ch 19-Jan-2017): ensure no callbacks are accumulated on @Terminated
         if which == :termination
           raise reason.nil? ? format('actor terminated normally before answering with a value: %s', value) : reason
         else
@@ -146,7 +146,7 @@ module Concurrent
 
     # @return [String] string representation.
     def inspect
-      format '<#%s:0x%x termination:%s>', self.class, object_id << 1, termination.state
+      format '%s termination:%s>', super[0..-2], termination.state
     end
 
     private

data/lib-edge/concurrent/edge/promises.rb

@@ -0,0 +1,178 @@
+# TODO try stealing pool, each thread has it's own queue
+
+require 'concurrent/promises'
+
+module Concurrent
+  module Promises
+
+    class Future < AbstractEventFuture
+
+      # @!macro warn.edge
+      module ActorIntegration
+        # Asks the actor with its value.
+        # @return [Future] new future with the response form the actor
+        def then_ask(actor)
+          self.then { |v| actor.ask(v) }.flat
+        end
+      end
+
+      include ActorIntegration
+
+      # @!macro warn.edge
+      module FlatShortcuts
+
+        # @return [Future]
+        def then_flat_future(*args, &block)
+          self.then(*args, &block).flat_future
+        end
+
+        alias_method :then_flat, :then_flat_future
+
+        # @return [Future]
+        def then_flat_future_on(executor, *args, &block)
+          self.then_on(executor, *args, &block).flat_future
+        end
+
+        alias_method :then_flat_on, :then_flat_future_on
+
+        # @return [Event]
+        def then_flat_event(*args, &block)
+          self.then(*args, &block).flat_event
+        end
+
+        # @return [Event]
+        def then_flat_event_on(executor, *args, &block)
+          self.then_on(executor, *args, &block).flat_event
+        end
+      end
+
+      include FlatShortcuts
+    end
+
+    # @!macro warn.edge
+    class Channel < Concurrent::Synchronization::Object
+      safe_initialization!
+
+      # Default size of the Channel, makes it accept unlimited number of messages.
+      UNLIMITED = ::Object.new
+      UNLIMITED.singleton_class.class_eval do
+        include Comparable
+
+        def <=>(other)
+          1
+        end
+
+        def to_s
+          'unlimited'
+        end
+      end
+
+      # A channel to pass messages between promises. The size is limited to support back pressure.
+      # @param [Integer, UNLIMITED] size the maximum number of messages stored in the channel.
+      def initialize(size = UNLIMITED)
+        super()
+        @Size        = size
+        # TODO (pitr-ch 26-Dec-2016): replace with lock-free implementation
+        @Mutex       = Mutex.new
+        @Probes      = []
+        @Messages    = []
+        @PendingPush = []
+      end
+
+
+      # Returns future which will fulfill when the message is added to the channel. Its value is the message.
+      # @param [Object] message
+      # @return [Future]
+      def push(message)
+        @Mutex.synchronize do
+          while true
+            if @Probes.empty?
+              if @Size > @Messages.size
+                @Messages.push message
+                return Promises.fulfilled_future message
+              else
+                pushed = Promises.resolvable_future
+                @PendingPush.push [message, pushed]
+                return pushed.with_hidden_resolvable
+              end
+            else
+              probe = @Probes.shift
+              if probe.fulfill [self, message], false
+                return Promises.fulfilled_future(message)
+              end
+            end
+          end
+        end
+      end
+
+      # Returns a future witch will become fulfilled with a value from the channel when one is available.
+      # @param [ResolvableFuture] probe the future which will be fulfilled with a channel value
+      # @return [Future] the probe, its value will be the message when available.
+      def pop(probe = Concurrent::Promises.resolvable_future)
+        # TODO (pitr-ch 26-Dec-2016): improve performance
+        pop_for_select(probe).then(&:last)
+      end
+
+      # @!visibility private
+      def pop_for_select(probe = Concurrent::Promises.resolvable_future)
+        @Mutex.synchronize do
+          if @Messages.empty?
+            @Probes.push probe
+          else
+            message = @Messages.shift
+            probe.fulfill [self, message]
+
+            unless @PendingPush.empty?
+              message, pushed = @PendingPush.shift
+              @Messages.push message
+              pushed.fulfill message
+            end
+          end
+        end
+        probe
+      end
+
+      # @return [String] Short string representation.
+      def to_s
+        format '%s size:%s>', super[0..-2], @Size
+      end
+
+      alias_method :inspect, :to_s
+    end
+
+    class Future < AbstractEventFuture
+      # @!macro warn.edge
+      module NewChannelIntegration
+
+        # @param [Channel] channel to push to.
+        # @return [Future] a future which is fulfilled after the message is pushed to the channel.
+        #   May take a moment if the channel is full.
+        def then_push_channel(channel)
+          self.then { |value| channel.push value }.flat_future
+        end
+
+      end
+
+      include NewChannelIntegration
+    end
+
+    module FactoryMethods
+      # @!macro warn.edge
+      module NewChannelIntegration
+
+        # Selects a channel which is ready to be read from.
+        # @param [Channel] channels
+        # @return [Future] a future which is fulfilled with pair [channel, message] when one of the channels is
+        #   available for reading
+        def select_channel(*channels)
+          probe = Promises.resolvable_future
+          channels.each { |ch| ch.pop_for_select probe }
+          probe
+        end
+      end
+
+      include NewChannelIntegration
+    end
+
+  end
+end

data/{lib → lib-edge}/concurrent/edge/throttle.rb

@@ -1,5 +1,5 @@
 module Concurrent
-  # @!macro [new] throttle.example.throttled_block
+  # @!macro throttle.example.throttled_block
   #   @example
   #     max_two = Throttle.new 2
   #     10.times.map do
@@ -10,12 +10,12 @@ module Concurrent
   #         end
   #       end
   #     end
-  # @!macro [new] throttle.example.throttled_future
+  # @!macro throttle.example.throttled_future
   #   @example
   #     throttle.throttled_future(1) do |arg|
   #       arg.succ
   #     end
-  # @!macro [new] throttle.example.throttled_future_chain
+  # @!macro throttle.example.throttled_future_chain
   #   @example
   #     throttle.throttled_future_chain do |trigger|
   #       trigger.
@@ -23,7 +23,7 @@ module Concurrent
   #           chain { 1 }.
   #           then(&:succ)
   #     end
-  # @!macro [new] throttle.example.then_throttled_by
+  # @!macro throttle.example.then_throttled_by
   #   @example
   #     data     = (1..5).to_a
   #     db       = data.reduce({}) { |h, v| h.update v => v.to_s }
@@ -48,11 +48,13 @@ module Concurrent
   # @!macro throttle.example.throttled_future
   # @!macro throttle.example.throttled_future_chain
   # @!macro throttle.example.throttled_block
+  # @!macro warn.edge
   class Throttle < Synchronization::Object
     # TODO (pitr-ch 21-Dec-2016): consider using sized channel for implementation instead when available
 
     safe_initialization!
-    private *attr_atomic(:can_run)
+    attr_atomic(:can_run)
+    private :can_run, :can_run=, :swap_can_run, :compare_and_set_can_run, :update_can_run
 
     # New throttle.
     # @param [Integer] limit
@@ -95,6 +97,7 @@ module Concurrent
         current_can_run = can_run
         if compare_and_set_can_run current_can_run, current_can_run + 1
           if current_can_run < 0
+            # release called after trigger which pushed a trigger, busy wait is ok
             Thread.pass until (trigger = @Queue.pop)
             trigger.resolve
           end
@@ -117,7 +120,7 @@ module Concurrent
 
     # @return [String] Short string representation.
     def to_s
-      format '<#%s:0x%x limit:%s can_run:%d>', self.class, object_id << 1, @Limit, can_run
+      format '%s limit:%s can_run:%d>', super[0..-2], @Limit, can_run
     end
 
     alias_method :inspect, :to_s
@@ -151,17 +154,23 @@ module Concurrent
 
     class AbstractEventFuture < Synchronization::Object
       module ThrottleIntegration
+
+        # @yieldparam [Future] a trigger
+        # @yieldreturn [Future, Event]
+        # @return [Future, Event]
         def throttled_by(throttle, &throttled_futures)
           a_trigger = self & self.chain { throttle.trigger }.flat_event
           throttled_futures.call(a_trigger).on_resolution! { throttle.release }
         end
 
-        # Behaves as {Promises::AbstractEventFuture#chain} but the it is throttled.
-        # @return [Promises::Future, Promises::Event]
-        # @see Promises::AbstractEventFuture#chain
+        # Behaves as {AbstractEventFuture#chain} but the it is throttled.
+        # @return [Future, Event]
+        # @see AbstractEventFuture#chain
         def chain_throttled_by(throttle, *args, &block)
           throttled_by(throttle) { |trigger| trigger.chain(*args, &block) }
         end
+
+        # TODO (pitr-ch 11-Jul-2018): add other then/rescue methods
       end
 
       include ThrottleIntegration
@@ -170,17 +179,17 @@ module Concurrent
     class Future < AbstractEventFuture
       module ThrottleIntegration
 
-        # Behaves as {Promises::Future#then} but the it is throttled.
-        # @return [Promises::Future]
-        # @see Promises::Future#then
+        # Behaves as {Future#then} but the it is throttled.
+        # @return [Future]
+        # @see Future#then
         # @!macro throttle.example.then_throttled_by
         def then_throttled_by(throttle, *args, &block)
           throttled_by(throttle) { |trigger| trigger.then(*args, &block) }
         end
 
-        # Behaves as {Promises::Future#rescue} but the it is throttled.
-        # @return [Promises::Future]
-        # @see Promises::Future#rescue
+        # Behaves as {Future#rescue} but the it is throttled.
+        # @return [Future]
+        # @see Future#rescue
         def rescue_throttled_by(throttle, *args, &block)
           throttled_by(throttle) { |trigger| trigger.rescue(*args, &block) }
         end

data/lib-edge/concurrent/edge.rb

@@ -0,0 +1,21 @@
+module Concurrent
+
+  # A submodule for unstable, highly experimental features that are likely to
+  # change often and which may never become part of the core gem. Also for
+  # new, experimental version of abstractions already in the core gem.
+  #
+  # Most new features should start in this module, clearly indicating the
+  # experimental and unstable nature of the feature. Once a feature becomes
+  # more stable and is a candidate for inclusion in the core gem it should
+  # be moved up to the `Concurrent` module, where it would reside once merged
+  # into the core gem.
+  #
+  # The only exception to this is for features which *replace* features from
+  # the core gem in ways that are breaking and not backward compatible. These
+  # features should remain in this module until merged into the core gem. This
+  # will prevent namespace collisions.
+  #
+  # @!macro warn.edge
+  module Edge
+  end
+end