concurrent-ruby-edge 0.3.1 → 0.7.0

data/lib/{concurrent → concurrent-ruby-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/{concurrent → concurrent-ruby-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/{concurrent → concurrent-ruby-edge/concurrent}/edge/lock_free_queue.rb

@@ -1,3 +1,5 @@
+require 'concurrent/synchronization/object'
+
 module Concurrent
 
   # @!visibility private

data/lib/{concurrent → concurrent-ruby-edge/concurrent}/edge/old_channel_integration.rb

@@ -1,3 +1,5 @@
+require 'concurrent/promises'
+
 module Concurrent
   module Promises
     module FactoryMethods

data/lib/concurrent-ruby-edge/concurrent/edge/processing_actor.rb

@@ -0,0 +1,184 @@
+require 'concurrent/synchronization/object'
+require 'concurrent/promises'
+require 'concurrent/edge/channel'
+
+module Concurrent
+
+  # A new implementation of actor which also simulates the process, therefore it can be used
+  # in the same way as Erlang's actors but **without** occupying thread. A tens of thousands
+  # ProcessingActors can run at the same time sharing a thread pool.
+  # @example
+  #     # Runs on a pool, does not consume 50_000 threads
+  #     actors = 50_000.times.map do |i|
+  #       Concurrent::ProcessingActor.act(i) { |a, i| a.receive.then_on(:fast, i) { |m, i| m + i } }
+  #     end
+  #
+  #     actors.each { |a| a.tell 1 }
+  #     values = actors.map(&:termination).map(&:value)
+  #     values[0,5]                                        # => [1, 2, 3, 4, 5]
+  #     values[-5, 5]                                      # => [49996, 49997, 49998, 49999, 50000]
+  # @!macro warn.edge
+  class ProcessingActor < Synchronization::Object
+
+    # TODO (pitr-ch 29-Jan-2019): simplify as much as possible, maybe even do not delegate to mailbox, no ask linking etc
+    # TODO (pitr-ch 03-Feb-2019): remove completely
+
+    safe_initialization!
+
+    # @return [Promises::Channel] actor's mailbox.
+    def mailbox
+      @Mailbox
+    end
+
+    # @return [Promises::Future(Object)] a future which is resolved when the actor ends its processing.
+    #   It can either be fulfilled with a value when actor ends normally or rejected with
+    #   a reason (exception) when actor fails.
+    def termination
+      @Terminated.with_hidden_resolvable
+    end
+
+    # Creates an actor.
+    # @see #act_listening Behaves the same way, but does not take mailbox as a first argument.
+    # @return [ProcessingActor]
+    # @example
+    #   actor = Concurrent::ProcessingActor.act do |actor|
+    #     actor.receive.then do |message|
+    #       # the actor ends normally with message
+    #       message
+    #     end
+    #   end
+    #
+    #   actor.tell :a_message
+    #       # => <#Concurrent::ProcessingActor:0x7fff11280560 termination:pending>
+    #   actor.termination.value! # => :a_message
+    def self.act(*args, &process)
+      act_listening Promises::Channel.new, *args, &process
+    end
+
+    # Creates an actor listening to a specified channel (mailbox).
+    # @param [Object] args Arguments passed to the process.
+    # @param [Promises::Channel] channel which serves as mailing box. The channel can have limited
+    #   size to achieve backpressure.
+    # @yield [actor, *args] to the process to get back a future which represents the actors execution.
+    # @yieldparam [ProcessingActor] actor
+    # @yieldparam [Object] *args
+    # @yieldreturn [Promises::Future(Object)] a future representing next step of execution
+    # @return [ProcessingActor]
+    def self.act_listening(channel, *args, &process)
+      ProcessingActor.new channel, *args, &process
+    end
+
+    # # Receives a message when available, used in the actor's process.
+    # # @return [Promises::Future(Object)] a future which will be fulfilled with a message from
+    # #   mailbox when it is available.
+    # def receive(*channels)
+    #   channels = [@Mailbox] if channels.empty?
+    #   Promises::Channel.select(*channels)
+    #   # TODO (pitr-ch 27-Dec-2016): support patterns
+    #   #   - put any received message aside if it does not match
+    #   #   - on each receive call check the messages put aside
+    #   #   - track where the message came from, cannot later receive m form other channel only because it matches
+    # end
+
+    def receive(channel = mailbox)
+      channel.pop_op
+    end
+
+    # Tells a message to the actor. May block current thread if the mailbox is full.
+    # {#tell_op} is a better option since it does not block. It's usually used to integrate with
+    # threading code.
+    # @example
+    #   Thread.new(actor) do |actor|
+    #     # ...
+    #     actor.tell! :a_message # blocks until the message is told
+    #     #   (there is a space for it in the channel)
+    #     # ...
+    #   end
+    # @param [Object] message
+    # @return [self]
+    def tell!(message)
+      @Mailbox.push(message)
+      self
+    end
+
+    # Tells a message to the actor.
+    # @param [Object] message
+    # @return [Promises::Future(ProcessingActor)] a future which will be fulfilled with the actor
+    #   when the message is pushed to mailbox.
+    def tell_op(message)
+      @Mailbox.push_op(message).then(self) { |_ch, actor| actor }
+    end
+
+    # # Simplifies common pattern when a message sender also requires an answer to the message
+    # # from the actor. It appends a resolvable_future for the answer after the message.
+    # # @todo has to be nice also on the receive side, cannot make structure like this [message = [...], answer]
+    # #   all receives should receive something friendly
+    # # @param [Object] message
+    # # @param [Promises::ResolvableFuture] answer
+    # # @return [Promises::Future] a future which will be fulfilled with the answer to the message
+    # # @example
+    # #     add_once_actor = Concurrent::ProcessingActor.act do |actor|
+    # #       actor.receive.then do |(a, b), answer|
+    # #         result = a + b
+    # #         answer.fulfill result
+    # #         # terminate with result value
+    # #         result
+    # #       end
+    # #     end
+    # #     # => <#Concurrent::ProcessingActor:0x7fcd1315f6e8 termination:pending>
+    # #
+    # #     add_once_actor.ask([1, 2]).value!                  # => 3
+    # #     # fails the actor already added once
+    # #     add_once_actor.ask(%w(ab cd)).reason
+    # #     # => #<RuntimeError: actor terminated normally before answering with a value: 3>
+    # #     add_once_actor.termination.value!                  # => 3
+    # def ask(message, answer = Promises.resolvable_future)
+    #   raise 'to be removed'
+    #
+    #   # TODO (pitr-ch 12-Dec-2018): REMOVE, the process ends up as another future not a value, no nice way to do ask in the actor
+    #   tell [message, answer]
+    #   # do not leave answers unanswered when actor terminates.
+    #   Promises.any(
+    #       Promises.fulfilled_future(:answer).zip(answer),
+    #       Promises.fulfilled_future(:termination).zip(@Terminated)
+    #   ).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
+    #     # 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
+    #       fulfilled ? value : raise(reason)
+    #     end
+    #   end
+    # end
+
+    # actor.ask2 { |a| [:count, a] }
+    def ask_op(answer = Promises.resolvable_future, &message_provider)
+      # TODO (pitr-ch 12-Dec-2018): is it ok to let the answers be unanswered when the actor terminates
+      tell_op(message_provider.call(answer)).then(answer) { |_, a| a }
+
+      # answer.chain { |v| [true, v] } | @Terminated.then
+    end
+
+    # @return [String] string representation.
+    def to_s
+      format '%s termination: %s>', super[0..-2], termination.state
+    end
+
+    alias_method :inspect, :to_s
+
+    def to_ary
+      [@Mailbox, @Terminated]
+    end
+
+    private
+
+    def initialize(channel, *args, &process)
+      @Mailbox    = channel
+      @Terminated = Promises.future(self, *args, &process).run
+      super()
+    end
+
+  end
+end

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

@@ -0,0 +1,174 @@
+# 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(actor) { |v, a| a.ask_op(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
+
+    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_channel_push(channel)
+          self.then(channel) { |value, ch| ch.push_op value }.flat_future
+        end
+
+      end
+
+      include NewChannelIntegration
+    end
+
+    module FactoryMethods
+      # @!macro promises.shortcut.on
+      # @return [Future]
+      # @!macro warn.edge
+      def zip_futures_over(enumerable, &future_factory)
+        zip_futures_over_on default_executor, enumerable, &future_factory
+      end
+
+      # Creates new future which is resolved after all the futures created by future_factory from
+      # enumerable elements are resolved. Simplified it does:
+      # `zip(*enumerable.map { |e| future e, &future_factory })`
+      # @example
+      #   # `#succ` calls are executed in parallel
+      #   zip_futures_over_on(:io, [1, 2], &:succ).value! # => [2, 3]
+      #
+      # @!macro promises.param.default_executor
+      # @param [Enumerable] enumerable
+      # @yield a task to be executed in future
+      # @yieldparam [Object] element from enumerable
+      # @yieldreturn [Object] a value of the future
+      # @return [Future]
+      # @!macro warn.edge
+      def zip_futures_over_on(default_executor, enumerable, &future_factory)
+        # ZipFuturesPromise.new_blocked_by(futures_and_or_events, default_executor).future
+        zip_futures_on(default_executor, *enumerable.map { |e| future e, &future_factory })
+      end
+    end
+
+    module Resolvable
+      include InternalStates
+
+      # Reserves the event or future, if reserved others are prevented from resolving it.
+      # Advanced feature.
+      # Be careful about the order of reservation to avoid deadlocks,
+      # the method blocks if the future or event is already reserved
+      # until it is released or resolved.
+      #
+      # @example
+      #   f = Concurrent::Promises.resolvable_future
+      #   reserved = f.reserve
+      #   Thread.new { f.resolve true, :val, nil } # fails
+      #   f.resolve true, :val, nil, true if reserved # must be called only if reserved
+      # @return [true, false] on successful reservation
+      def reserve
+        while true
+          return true if compare_and_set_internal_state(PENDING, RESERVED)
+          return false if resolved?
+          # FIXME (pitr-ch 17-Jan-2019): sleep until given up or resolved instead of busy wait
+          Thread.pass
+        end
+      end
+
+      # @return [true, false] on successful release of the reservation
+      def release
+        compare_and_set_internal_state(RESERVED, PENDING)
+      end
+
+      # @return [Comparable] an item to sort the resolvable events or futures
+      #   by to get the right global locking order of resolvable events or futures
+      # @see .atomic_resolution
+      def self.locking_order_by(resolvable)
+        resolvable.object_id
+      end
+
+      # Resolves all passed events and futures to the given resolutions
+      # if possible (all are unresolved) or none.
+      #
+      # @param [Hash{Resolvable=>resolve_arguments}, Array<Array(Resolvable, resolve_arguments)>] resolvable_map
+      #   collection of resolvable events and futures which should be resolved all at once
+      #   and what should they be resolved to, examples:
+      #   ```ruby
+      #   { a_resolvable_future1 => [true, :val, nil],
+      #     a_resolvable_future2 => [false, nil, :err],
+      #     a_resolvable_event => [] }
+      #   ```
+      #    or
+      #   ```ruby
+      #   [[a_resolvable_future1, [true, :val, nil]],
+      #    [a_resolvable_future2, [false, nil, :err]],
+      #    [a_resolvable_event, []]]
+      #   ```
+      # @return [true, false] if success
+      def self.atomic_resolution(resolvable_map)
+        # atomic_resolution event => [], future => [true, :v, nil]
+        sorted = resolvable_map.to_a.sort_by { |resolvable, _| locking_order_by resolvable }
+
+        reserved = 0
+        while reserved < sorted.size && sorted[reserved].first.reserve
+          reserved += 1
+        end
+
+        if reserved == sorted.size
+          sorted.each { |resolvable, args| resolvable.resolve(*args, true, true) }
+          true
+        else
+          while reserved > 0
+            reserved -= 1
+            raise 'has to be reserved' unless sorted[reserved].first.release
+          end
+          false
+        end
+      end
+    end
+
+
+  end
+end

data/lib/concurrent-ruby-edge/concurrent/edge/throttle.rb

@@ -0,0 +1,229 @@
+require 'concurrent/edge/lock_free_queue'
+require 'concurrent/promises'
+require 'concurrent/synchronization/object'
+
+module Concurrent
+  # A tool managing concurrency level of tasks.
+  # The maximum capacity is set in constructor.
+  # Each acquire will lower the available capacity and release will increase it.
+  # When there is no available capacity the current thread may either be blocked or
+  # an event is returned which will be resolved when capacity becomes available.
+  #
+  # The more common usage of the Throttle is with a proxy executor
+  # `a_throttle.on(Concurrent.global_io_executor)`.
+  # Anything executed on the proxy executor will be throttled and
+  # execute on the given executor. There can be more than one proxy executors.
+  # All abstractions which execute tasks have option to specify executor,
+  # therefore the proxy executor can be injected to any abstraction
+  # throttling its concurrency level.
+  #
+  # {include:file:docs-source/throttle.out.md}
+  #
+  # @!macro warn.edge
+  class Throttle < Synchronization::Object
+    safe_initialization!
+
+    attr_atomic(:capacity)
+    private :capacity, :capacity=, :swap_capacity, :compare_and_set_capacity, :update_capacity
+
+    # @return [Integer] The available capacity.
+    def available_capacity
+      current_capacity = capacity
+      current_capacity >= 0 ? current_capacity : 0
+    end
+
+    # Create throttle.
+    # @param [Integer] capacity How many tasks using this throttle can run at the same time.
+    def initialize(capacity)
+      super()
+      @MaxCapacity            = capacity
+      @Queue                  = LockFreeQueue.new
+      @executor_cache         = [nil, nil]
+      self.capacity = capacity
+    end
+
+    # @return [Integer] The maximum capacity.
+    def max_capacity
+      @MaxCapacity
+    end
+
+    # Blocks current thread until there is capacity available in the throttle.
+    # The acquired capacity has to be returned to the throttle by calling {#release}.
+    # If block is passed then the block is called after the capacity is acquired and
+    # it is automatically released after the block is executed.
+    #
+    # @param [Numeric] timeout the maximum time in second to wait.
+    # @yield [] block to execute after the capacity is acquired
+    # @return [Object, self, true, false]
+    #   * When no timeout and no block it returns self
+    #   * When no timeout and with block it returns the result of the block
+    #   * When with timeout and no block it returns true when acquired and false when timed out
+    #   * When with timeout and with block it returns the result of the block of nil on timing out
+    # @see #release
+    def acquire(timeout = nil, &block)
+      event = acquire_or_event
+      if event
+        within_timeout = event.wait(timeout)
+        # release immediately when acquired later after the timeout since it is unused
+        event.on_resolution!(self, &:release) unless within_timeout
+      else
+        within_timeout = true
+      end
+
+      called = false
+      if timeout
+        if block
+          if within_timeout
+            called = true
+            block.call
+          else
+            nil
+          end
+        else
+          within_timeout
+        end
+      else
+        if block
+          called = true
+          block.call
+        else
+          self
+        end
+      end
+    ensure
+      release if called
+    end
+
+    # Tries to acquire capacity from the throttle.
+    # Returns true when there is capacity available.
+    # The acquired capacity has to be returned to the throttle by calling {#release}.
+    # @return [true, false]
+    # @see #release
+    def try_acquire
+      while true
+        current_capacity = capacity
+        if current_capacity > 0
+          return true if compare_and_set_capacity(
+              current_capacity, current_capacity - 1)
+        else
+          return false
+        end
+      end
+    end
+
+    # Releases previously acquired capacity back to Throttle.
+    # Has to be called exactly once for each acquired capacity.
+    # @return [self]
+    # @see #acquire_operation, #acquire, #try_acquire
+    def release
+      while true
+        current_capacity = capacity
+        if compare_and_set_capacity current_capacity, current_capacity + 1
+          if current_capacity < 0
+            # release called after trigger which pushed a trigger, busy wait is ok
+            Thread.pass until (trigger = @Queue.pop)
+            trigger.resolve
+          end
+          return self
+        end
+      end
+    end
+
+    # @return [String] Short string representation.
+    def to_s
+      format '%s capacity available %d of %d>', super[0..-2], capacity, @MaxCapacity
+    end
+
+    alias_method :inspect, :to_s
+
+    # @!visibility private
+    def acquire_or_event
+      while true
+        current_capacity = capacity
+        if compare_and_set_capacity current_capacity, current_capacity - 1
+          if current_capacity > 0
+            return nil
+          else
+            event = Promises.resolvable_event
+            @Queue.push event
+            return event
+          end
+        end
+      end
+    end
+
+    include Promises::FactoryMethods
+
+    # @param [ExecutorService] executor
+    # @return [ExecutorService] An executor which wraps given executor and allows to post tasks only
+    #   as available capacity in the throttle allows.
+    # @example throttling future
+    #   a_future.then_on(a_throttle.on(:io)) { a_throttled_task }
+    def on(executor = Promises::FactoryMethods.default_executor)
+      current_executor, current_cache = @executor_cache
+      return current_cache if current_executor == executor && current_cache
+
+      if current_executor.nil?
+        # cache first proxy
+        proxy_executor  = ProxyExecutor.new(self, Concurrent.executor(executor))
+        @executor_cache = [executor, proxy_executor]
+        return proxy_executor
+      else
+        # do not cache more than 1 executor
+        ProxyExecutor.new(self, Concurrent.executor(executor))
+      end
+    end
+
+    # Uses executor provided by {#on} therefore
+    # all events and futures created using factory methods on this object will be throttled.
+    # Overrides {Promises::FactoryMethods#default_executor}.
+    #
+    # @return [ExecutorService]
+    # @see Promises::FactoryMethods#default_executor
+    def default_executor
+      on(super)
+    end
+
+    class ProxyExecutor < Synchronization::Object
+      safe_initialization!
+
+      include ExecutorService
+
+      def initialize(throttle, executor)
+        super()
+        @Throttle = throttle
+        @Executor = executor
+      end
+
+      def post(*args, &task)
+        if (event = @Throttle.acquire_or_event)
+          event.on_resolution! { inner_post(*args, &task) }
+        else
+          inner_post(*args, &task)
+        end
+      end
+
+      def can_overflow?
+        @Executor.can_overflow?
+      end
+
+      def serialized?
+        @Executor.serialized?
+      end
+
+      private
+
+      def inner_post(*arguments, &task)
+        @Executor.post(*arguments) do |*args|
+          begin
+            task.call(*args)
+          ensure
+            @Throttle.release
+          end
+        end
+      end
+    end
+
+    private_constant :ProxyExecutor
+  end
+end

data/lib/concurrent-ruby-edge/concurrent/edge/version.rb

@@ -0,0 +1,3 @@
+module Concurrent
+  EDGE_VERSION = '0.7.0'
+end