concurrent-ruby-edge 0.3.1 → 0.7.0

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

@@ -1,3 +1,5 @@
+require 'concurrent/actor/context'
+
 module Concurrent
   module Actor
     class DefaultDeadLetterHandler < RestartingContext

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

@@ -1,3 +1,5 @@
+require 'concurrent/actor/type_check'
+
 module Concurrent
   module Actor
     class Envelope

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

@@ -1,3 +1,5 @@
+require 'concurrent/actor/type_check'
+
 module Concurrent
   module Actor
     Error = Class.new(StandardError)

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

@@ -1,3 +1,6 @@
+require 'logger'
+require 'concurrent/actor/public_delegations'
+
 module Concurrent
   module Actor
     module InternalDelegations

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

@@ -1,3 +1,6 @@
+require 'concurrent/actor/type_check'
+require 'concurrent/actor/public_delegations'
+
 module Concurrent
   module Actor
 
@@ -35,12 +38,7 @@ module Concurrent
 
       alias_method :<<, :tell
 
-      # @note it's a good practice to use tell whenever possible. Ask should be used only for
-      # testing and when it returns very shortly. It can lead to deadlock if all threads in
-      # global_io_executor will block on while asking. It's fine to use it form outside of actors and
-      # global_io_executor.
-      #
-      # @note it's a good practice to use {#tell} whenever possible. Results can be send back with other messages.
+      # @note it's a good practice to use {#tell} whenever possible. Results can be sent back with other messages.
       #   Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in
       #   global_io_executor will block on while asking. It's fine to use it form outside of actors and
       #   global_io_executor.
@@ -55,10 +53,13 @@ module Concurrent
         message message, future
       end
 
+      # @!visibility privated
+      alias_method :ask_op, :ask
+
       # Sends the message synchronously and blocks until the message
       # is processed. Raises on error.
       #
-      # @note it's a good practice to use {#tell} whenever possible. Results can be send back with other messages.
+      # @note it's a good practice to use {#tell} whenever possible. Results can be sent back with other messages.
       #   Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in
       #   global_io_executor will block on while asking. It's fine to use it form outside of actors and
       #   global_io_executor.
@@ -89,7 +90,7 @@ module Concurrent
       end
 
       def to_s
-        "#<#{self.class}:0x#{'%x' % (object_id << 1)} #{path} (#{actor_class})>"
+        format '%s %s (%s)>', super[0..-2], path, actor_class
       end
 
       alias_method :inspect, :to_s

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

@@ -1,3 +1,6 @@
+require 'concurrent/actor/context'
+require 'concurrent/actor/core'
+
 module Concurrent
   module Actor
     # implements the root actor

data/lib/{concurrent → concurrent-ruby-edge/concurrent}/actor/utils/ad_hoc.rb

@@ -1,3 +1,5 @@
+require 'concurrent/actor/context'
+
 module Concurrent
   module Actor
     module Utils

data/lib/{concurrent → concurrent-ruby-edge/concurrent}/actor/utils/balancer.rb

@@ -1,3 +1,5 @@
+require 'concurrent/actor/context'
+
 module Concurrent
   module Actor
     module Utils

data/lib/{concurrent → concurrent-ruby-edge/concurrent}/actor/utils/broadcast.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'concurrent/actor/context'
 
 module Concurrent
   module Actor

data/lib/{concurrent → concurrent-ruby-edge/concurrent}/actor/utils/pool.rb

@@ -1,4 +1,5 @@
 require 'concurrent/actor/utils/balancer'
+require 'concurrent/actor/context'
 
 module Concurrent
   module Actor

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

@@ -1,6 +1,7 @@
+# NOTE: finer grained than require 'concurrent/actor' not supported
+
 require 'concurrent/configuration'
 require 'concurrent/executor/serialized_execution'
-require 'concurrent/synchronization'
 require 'concurrent/edge/promises'
 
 module Concurrent
@@ -10,9 +11,9 @@ module Concurrent
   # TODO supervision tree, pause children on error in parent, pause may need higher priority
   # TODO more effective executor
 
-  # {include:file:doc/actor/main.md}
+  # {include:file:docs-source/actor/main.md}
   # @api Actor
-  # @!macro edge_warning
+  # @!macro warn.edge
   module Actor
 
     require 'concurrent/actor/type_check'
@@ -35,9 +36,13 @@ module Concurrent
     end
 
     @root = Concurrent::Promises.delay do
-      Core.new(parent: nil, name: '/', class: Root, initialized: future = Concurrent::Promises.resolvable_future).reference.tap do
-        future.wait!
-      end
+      Core.
+        new(parent:      nil,
+            name:        '/',
+            class:       Root,
+            initialized: future = Concurrent::Promises.resolvable_future).
+        reference.
+        tap { future.wait! }
     end
 
     # A root actor, a default parent of all actors spawned outside an actor

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

@@ -1,4 +1,5 @@
 require 'concurrent/channel/buffer/base'
+require 'concurrent/channel/buffer/buffered'
 
 module Concurrent
   class Channel

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

@@ -1,4 +1,5 @@
 require 'concurrent/channel/buffer/base'
+require 'concurrent/channel/buffer/buffered'
 
 module Concurrent
   class Channel

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

@@ -1,4 +1,4 @@
-require 'concurrent/synchronization'
+require 'concurrent/synchronization/object'
 require 'concurrent/utility/monotonic_time'
 
 module Concurrent

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

@@ -8,13 +8,14 @@ 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
 
     # NOTE: Move to global IO pool once stable
-    GOROUTINES = Concurrent::CachedThreadPool.new(auto_terminate: true)
+    GOROUTINES = Concurrent::CachedThreadPool.new
     private_constant :GOROUTINES
 
     BUFFER_TYPES = {

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

@@ -0,0 +1,107 @@
+require 'concurrent/concern/deprecation'
+require 'concurrent/synchronization/object'
+require 'concurrent/promises'
+
+module Concurrent
+
+  # TODO (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
+  # TODO (pitr-ch 10-Dec-2018): integrate with enumerator?
+  # token.cancelable(array.each_with_index).each do |v, i|
+  #   # stops iterating when cancelled
+  # end
+  # token.cancelable(array).each_with_index do |v, i|
+  #   # stops iterating when cancelled
+  # end
+
+  # The Cancellation abstraction provides cooperative cancellation.
+  #
+  # The standard methods `Thread#raise` of `Thread#kill` available in Ruby
+  # are very dangerous (see linked the blog posts bellow).
+  # Therefore concurrent-ruby provides an alternative.
+  # * <https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/>
+  # * <http://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/>
+  # * <http://blog.headius.com/2008/02/rubys-threadraise-threadkill-timeoutrb.html>
+  #
+  # It provides an object which represents a task which can be executed,
+  # the task has to get the reference to the object and periodically cooperatively check that it is not cancelled.
+  # Good practices to make tasks cancellable:
+  # * check cancellation every cycle of a loop which does significant work,
+  # * do all blocking actions in a loop with a timeout then on timeout check cancellation
+  #   and if ok block again with the timeout
+  #
+  # The idea was inspired by <https://msdn.microsoft.com/en-us/library/dd537607(v=vs.110).aspx>
+  # @!macro warn.edge
+  #
+  # {include:file:docs-source/cancellation.out.md}
+  class Cancellation < Synchronization::Object
+    safe_initialization!
+
+    # Create Cancellation which will cancel itself in given time
+    #
+    # @!macro promises.param.intended_time
+    # @return [Cancellation]
+    def self.timeout(intended_time)
+      new Concurrent::Promises.schedule(intended_time)
+    end
+
+    # Creates the cancellation object.
+    #
+    # @param [Promises::Future, Promises::Event] origin of the cancellation.
+    #   When it is resolved the cancellation is canceled.
+    # @example
+    #   cancellation, origin = Concurrent::Cancellation.new
+    # @see #to_ary
+    def initialize(origin = Promises.resolvable_event)
+      super()
+      @Origin = origin
+    end
+
+    # Allow to multi-assign the Cancellation object
+    # @return [Array(Cancellation, Promises::Future), Array(Cancellation, Promises::Event)]
+    # @example
+    #   cancellation         = Concurrent::Cancellation.new
+    #   cancellation, origin = Concurrent::Cancellation.new
+    def to_ary
+      [self, @Origin]
+    end
+
+    # The event or future which is the origin of the cancellation
+    # @return [Promises::Future, Promises::Event]
+    def origin
+      @Origin
+    end
+
+    # Is the cancellation cancelled?
+    # Respective, was the origin of the cancellation resolved.
+    # @return [true, false]
+    def canceled?
+      @Origin.resolved?
+    end
+
+    # Raise error when cancelled
+    # @param [#exception] error to be risen
+    # @raise the error
+    # @return [self]
+    def check!(error = CancelledOperationError)
+      raise error if canceled?
+      self
+    end
+
+    # Creates a new Cancellation which is cancelled when first
+    # of the supplied cancellations or self is cancelled.
+    #
+    # @param [Cancellation] cancellations to combine
+    # @return [Cancellation] new cancellation
+    def join(*cancellations)
+      Cancellation.new Promises.any_event(*[@Origin, *cancellations.map(&:origin)])
+    end
+
+    # Short string representation.
+    # @return [String]
+    def to_s
+      format '%s %s>', super[0..-2], canceled? ? 'canceled' : 'pending'
+    end
+
+    alias_method :inspect, :to_s
+  end
+end