concurrent-ruby-edge 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a73af2e066aeacd850f4d90e0b6e479e49f01c2
-  data.tar.gz: 5579712d4b29cea99935106ede50cc838e879dcb
+  metadata.gz: 051e8d02906d153d112b5f2e2c86948d3cf0fd26
+  data.tar.gz: f4a53c06cfbf931dfc11245be8dabdf579d0e361
 SHA512:
-  metadata.gz: a35e94c5897426ea016c966f29bf18c0a06c46f90365e45fa82d69584c9f3c2680f95d9920354fc17211b9cced7475cca596d6c3a116a1b8a153ded45a5ce720
-  data.tar.gz: b8a8f94e251a406dde85ec6003de8cfc8e83bdadafff888244e28201666d386b7a549d2da697dd5973c79c152d43fc06de4a86a512bb717465e537cbff222ded
+  metadata.gz: 9b8490d330375764f70d70f212de4697dd3fbf83b0b4a7da1ffba7c86599fc64df3c4f25801ea0531970a04d2b62e04bad7701df9ce25afd24779dbd6b54d0fd
+  data.tar.gz: 6fc402ca7a4434e2b8e97a71fd351c81bbf8ff9467ccceb8159c78993fc8219e032704644cfbb965a34879aa5922bddc8d96f5f78343d0b0834602340d122a52

data/README.md

@@ -9,39 +9,28 @@
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
 [![Gitter chat](https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
-<table>
-  <tr>
-    <td align="left" valign="top">
-      <p>
-        Modern concurrency tools for Ruby. Inspired by
-        <a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
-        <a href="http://clojure.org/concurrent_programming">Clojure</a>,
-        <a href="http://akka.io/">Scala</a>,
-        <a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
-        <a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
-        <a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
-        <a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
-        and classic concurrency patterns.
-      </p>
-      <p>
-        The design goals of this gem are:
-        <ul>
-          <li>Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why</li>
-          <li>Remain free of external gem dependencies</li>
-          <li>Stay true to the spirit of the languages providing inspiration</li>
-          <li>But implement in a way that makes sense for Ruby</li>
-          <li>Keep the semantics as idiomatic Ruby as possible</li>
-          <li>Support features that make sense in Ruby</li>
-          <li>Exclude features that don't make sense in Ruby</li>
-          <li>Be small, lean, and loosely coupled</li>
-        </ul>
-      </p>
-    </td>
-    <td align="right" valign="top">
-      <img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png"/>
-    </td>
-  </tr>
-</table>
+Modern concurrency tools for Ruby. Inspired by
+[Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
+[Clojure](http://clojure.org/concurrent_programming),
+[Scala](http://akka.io/),
+[Haskell](http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell),
+[F#](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx),
+[C#](http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx),
+[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
+and classic concurrency patterns.
+
+<img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" />
+
+The design goals of this gem are:
+
+* Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why
+* Remain free of external gem dependencies
+* Stay true to the spirit of the languages providing inspiration
+* But implement in a way that makes sense for Ruby
+* Keep the semantics as idiomatic Ruby as possible
+* Support features that make sense in Ruby
+* Exclude features that don't make sense in Ruby
+* Be small, lean, and loosely coupled
 
 ### Supported Ruby versions
 
@@ -127,13 +116,13 @@ These features are under active development and may change frequently. They are
 keep backward compatibility (there may also lack tests and documentation). Semantic versions will
 be obeyed though. Features developed in `concurrent-ruby-edge` are expected to move to `concurrent-ruby` when final.
 
-* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
-  Implements the Actor Model, where concurrent actors exchange messages.
-* [New Future Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/FutureShortcuts.html):
+* [Promises Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promises.html):
   Unified implementation of futures and promises which combines features of previous `Future`,
   `Promise`, `IVar`, `Event`, `dataflow`, `Delay`, and `TimerTask` into a single framework. It extensively uses the
   new synchronization layer to make all the features **non-blocking** and **lock-free**, with the exception of obviously blocking
   operations like `#wait`, `#value`. It also offers better performance.
+* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
+  Implements the Actor Model, where concurrent actors exchange messages.
 * [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/Channel.html):
   Communicating Sequential Processes ([CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes)).
   Functionally equivalent to Go [channels](https://tour.golang.org/concurrency/2) with additional
@@ -141,15 +130,16 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
 * [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
 * [AtomicMarkableReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
 * [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
-* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeStack.html)
+* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LockFreeStack.html)
 
 #### Statuses:
 
 *Why are these not in core?*
 
+- **Promises Framework** - They are being finalized to be able to be moved to core. They'll deprecate old 
+  implementation.
 - **Actor** - Partial documentation and tests; depends on new future/promise framework; stability is good.
 - **Channel** - Brand new implementation; partial documentation and tests; stability is good.
-- **Future/Promise Framework** - API changes; partial documentation and tests; stability is good.
 - **LazyRegister** - Missing documentation and tests.
 - **AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack** - Need real world battle testing.
 

data/lib/concurrent-edge.rb

@@ -6,7 +6,11 @@ require 'concurrent/channel'
 require 'concurrent/exchanger'
 require 'concurrent/lazy_register'
 
-require 'concurrent/edge/future'
-require 'concurrent/edge/lock_free_stack'
 require 'concurrent/edge/atomic_markable_reference'
 require 'concurrent/edge/lock_free_linked_set'
+require 'concurrent/edge/lock_free_queue'
+require 'concurrent/edge/lock_free_stack'
+
+require 'concurrent/edge/promises'
+require 'concurrent/edge/cancellation'
+require 'concurrent/edge/throttle'

data/lib/concurrent/actor.rb

@@ -1,7 +1,7 @@
 require 'concurrent/configuration'
 require 'concurrent/executor/serialized_execution'
 require 'concurrent/synchronization'
-require 'concurrent/edge/future'
+require 'concurrent/edge/promises'
 
 module Concurrent
   # TODO https://github.com/celluloid/celluloid/wiki/Supervision-Groups ?
@@ -34,8 +34,8 @@ module Concurrent
       Thread.current[:__current_actor__]
     end
 
-    @root = Concurrent.delay do
-      Core.new(parent: nil, name: '/', class: Root, initialized: future = Concurrent.future).reference.tap do
+    @root = Concurrent::Promises.delay do
+      Core.new(parent: nil, name: '/', class: Root, initialized: future = Concurrent::Promises.resolvable_future).reference.tap do
         future.wait!
       end
     end
@@ -65,16 +65,20 @@ module Concurrent
     # @param args see {.to_spawn_options}
     # @return [Reference] never the actual actor
     def self.spawn(*args, &block)
+      options = to_spawn_options(*args)
+      if options[:executor] && options[:executor].is_a?(ImmediateExecutor)
+        raise ArgumentError, 'ImmediateExecutor is not supported'
+      end
       if Actor.current
-        Core.new(to_spawn_options(*args).merge(parent: Actor.current), &block).reference
+        Core.new(options.merge(parent: Actor.current), &block).reference
       else
-        root.ask([:spawn, to_spawn_options(*args), block]).value!
+        root.ask([:spawn, options, block]).value!
       end
     end
 
     # as {.spawn} but it'll block until actor is initialized or it'll raise exception on error
     def self.spawn!(*args, &block)
-      spawn(to_spawn_options(*args).merge(initialized: future = Concurrent.future), &block).tap { future.wait! }
+      spawn(to_spawn_options(*args).merge(initialized: future = Concurrent::Promises.resolvable_future), &block).tap { future.wait! }
     end
 
     # @overload to_spawn_options(context_class, name, *args)

data/lib/concurrent/actor/behaviour/sets_results.rb

@@ -1,7 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
-      # Collects returning value and sets the CompletableFuture in the {Envelope} or error on failure.
+      # Collects returning value and sets the ResolvableFuture in the {Envelope} or error on failure.
       class SetResults < Abstract
         attr_reader :error_strategy
 
@@ -13,7 +13,7 @@ module Concurrent
         def on_envelope(envelope)
           result = pass envelope
           if result != MESSAGE_PROCESSED && !envelope.future.nil?
-            envelope.future.success result
+            envelope.future.fulfill result
             log(DEBUG) { "finished processing of #{envelope.message.inspect}"}
           end
           nil
@@ -29,7 +29,7 @@ module Concurrent
           else
             raise
           end
-          envelope.future.fail error unless envelope.future.nil?
+          envelope.future.reject error unless envelope.future.nil?
         end
       end
     end

data/lib/concurrent/actor/behaviour/termination.rb

@@ -14,8 +14,8 @@ module Concurrent
 
         def initialize(core, subsequent, core_options, trapping = false, terminate_children = true)
           super core, subsequent, core_options
-          @terminated         = Concurrent.future
-          @public_terminated  = @terminated.hide_completable
+          @terminated         = Concurrent::Promises.resolvable_future
+          @public_terminated  = @terminated.with_hidden_resolvable
           @trapping           = trapping
           @terminate_children = terminate_children
         end
@@ -23,7 +23,7 @@ module Concurrent
         # @note Actor rejects envelopes when terminated.
         # @return [true, false] if actor is terminated
         def terminated?
-          @terminated.completed?
+          @terminated.resolved?
         end
 
         def trapping?
@@ -62,15 +62,15 @@ module Concurrent
         def terminate!(reason = nil, envelope = nil)
           return true if terminated?
 
-          self_termination = Concurrent.completed_future(reason.nil?, reason.nil? || nil, reason)
+          self_termination = Concurrent::Promises.resolved_future(reason.nil?, reason.nil? || nil, reason)
           all_terminations = if @terminate_children
-                               Concurrent.zip(*children.map { |ch| ch.ask(:terminate!) }, self_termination)
+                               Concurrent::Promises.zip(*children.map { |ch| ch.ask(:terminate!) }, self_termination)
                              else
                                self_termination
                              end
 
-          all_terminations.chain_completable(@terminated)
-          all_terminations.chain_completable(envelope.future) if envelope && envelope.future
+          all_terminations.chain_resolvable(@terminated)
+          all_terminations.chain_resolvable(envelope.future) if envelope && envelope.future
 
           broadcast(true, [:terminated, reason]) # TODO do not end up in Dead Letter Router
           parent << :remove_child if parent

data/lib/concurrent/actor/core.rb

@@ -42,7 +42,7 @@ module Concurrent
       # @option opts [Class] reference a custom descendant of {Reference} to use
       # @option opts [Array<Array(Behavior::Abstract, Array<Object>)>] behaviour_definition, array of pairs
       #   where each pair is behaviour class and its args, see {Behaviour.basic_behaviour_definition}
-      # @option opts [CompletableFuture, nil] initialized, if present it'll be set or failed after {Context} initialization
+      # @option opts [ResolvableFuture, nil] initialized, if present it'll be set or failed after {Context} initialization
       # @option opts [Reference, nil] parent **private api** parent of the actor (the one spawning )
       # @option opts [Proc, nil] logger a proc accepting (level, progname, message = nil, &block) params,
       #   can be used to hook actor instance to any logging system, see {Concurrent::Concern::Logging}
@@ -172,7 +172,6 @@ module Concurrent
         allocate_context
 
         @executor = Type! opts.fetch(:executor, @context.default_executor), Concurrent::AbstractExecutorService
-        raise ArgumentError, 'ImmediateExecutor is not supported' if @executor.is_a? ImmediateExecutor
 
         @reference = (Child! opts[:reference_class] || @context.default_reference_class, Reference).new self
         @name      = (Type! opts.fetch(:name), String, Symbol).to_s
@@ -192,17 +191,17 @@ module Concurrent
 
         @args       = opts.fetch(:args, [])
         @block      = block
-        initialized = Type! opts[:initialized], Edge::CompletableFuture, NilClass
+        initialized = Type! opts[:initialized], Promises::ResolvableFuture, NilClass
 
         schedule_execution do
           begin
             build_context
-            initialized.success reference if initialized
+            initialized.fulfill reference if initialized
             log DEBUG, 'spawned'
           rescue => ex
             log ERROR, ex
             @first_behaviour.terminate!
-            initialized.fail ex if initialized
+            initialized.reject ex if initialized
           end
         end
       end

data/lib/concurrent/actor/envelope.rb

@@ -16,7 +16,7 @@ module Concurrent
 
       def initialize(message, future, sender, address)
         @message = message
-        @future  = Type! future, Edge::CompletableFuture, NilClass
+        @future  = Type! future, Promises::ResolvableFuture, NilClass
         @sender  = Type! sender, Reference, Thread
         @address = Type! address, Reference
       end
@@ -34,7 +34,7 @@ module Concurrent
       end
 
       def reject!(error)
-        future.fail error unless future.nil?
+        future.reject error unless future.nil?
       end
     end
   end

data/lib/concurrent/actor/errors.rb

@@ -20,7 +20,7 @@ module Concurrent
 
       def initialize(envelope)
         @envelope = Type! envelope, Envelope
-        super envelope.message.inspect
+        super "#{envelope.message.inspect} from #{envelope.sender_path}"
       end
     end
   end

data/lib/concurrent/actor/reference.rb

@@ -45,13 +45,13 @@ module Concurrent
       #   global_io_executor will block on while asking. It's fine to use it form outside of actors and
       #   global_io_executor.
       # @param [Object] message
-      # @param [Edge::Future] future to be fulfilled be message's processing result
-      # @return [Edge::Future] supplied future
+      # @param [Promises::Future] future to be fulfilled be message's processing result
+      # @return [Promises::Future] supplied future
       # @example
       #   adder = AdHoc.spawn('adder') { -> message { message + 1 } }
       #   adder.ask(1).value # => 2
       #   adder.ask(nil).wait.reason # => #<NoMethodError: undefined method `+' for nil:NilClass>
-      def ask(message, future = Concurrent.future)
+      def ask(message, future = Concurrent::Promises.resolvable_future)
         message message, future
       end
 
@@ -63,13 +63,13 @@ module Concurrent
       #   global_io_executor will block on while asking. It's fine to use it form outside of actors and
       #   global_io_executor.
       # @param [Object] message
-      # @param [Edge::Future] future to be fulfilled be message's processing result
+      # @param [Promises::Future] future to be fulfilled be message's processing result
       # @return [Object] message's processing result
-      # @raise [Exception] future.reason if future is #failed?
+      # @raise [Exception] future.reason if future is #rejected?
       # @example
       #   adder = AdHoc.spawn('adder') { -> message { message + 1 } }
       #   adder.ask!(1) # => 2
-      def ask!(message, future = Concurrent.future)
+      def ask!(message, future = Concurrent::Promises.resolvable_future)
         ask(message, future).value!
       end
 
@@ -80,7 +80,7 @@ module Concurrent
       # behaves as {#tell} when no future and as {#ask} when future
       def message(message, future = nil)
         core.on_envelope Envelope.new(message, future, Actor.current || Thread.current, self)
-        return future ? future.hide_completable : self
+        return future ? future.with_hidden_resolvable : self
       end
 
       # @see AbstractContext#dead_letter_routing

data/lib/concurrent/actor/utils/pool.rb

@@ -43,9 +43,9 @@ module Concurrent
           envelope_to_redirect = if envelope.future
                                    envelope
                                  else
-                                   Envelope.new(envelope.message, Concurrent.future, envelope.sender, envelope.address)
+                                   Envelope.new(envelope.message, Concurrent::Promises.future, envelope.sender, envelope.address)
                                  end
-          envelope_to_redirect.future.on_completion! { @balancer << :subscribe } # TODO check safety of @balancer reading
+          envelope_to_redirect.future.on_fulfillment! { @balancer << :subscribe } # TODO check safety of @balancer reading
           redirect @balancer, envelope_to_redirect
         end
       end

data/lib/concurrent/edge/cancellation.rb

@@ -0,0 +1,137 @@
+module Concurrent
+
+  # Provides tools for cooperative cancellation.
+  # Inspired by https://msdn.microsoft.com/en-us/library/dd537607(v=vs.110).aspx
+  # @example
+  #   # Create new cancellation. `cancellation` is used for cancelling, `token` is passed down to
+  #   # tasks for cooperative cancellation
+  #   cancellation, token = Concurrent::Cancellation.create
+  #   Thread.new(token) do |token|
+  #     # Count 1+1 (simulating some other meaningful work) repeatedly until the token is cancelled through
+  #     # cancellation.
+  #     token.loop_until_canceled { 1+1 }
+  #   end
+  #   sleep 0.1
+  #   cancellation.cancel # Stop the thread by cancelling
+  class Cancellation < Synchronization::Object
+    safe_initialization!
+
+    # Creates the cancellation object. Returns both the cancellation and the token for convenience.
+    # @param [Object] resolve_args resolve_args Arguments which are used when resolve method is called on
+    #   resolvable_future_or_event
+    # @param [Promises::Resolvable] resolvable_future_or_event resolvable used to track cancellation.
+    #   Can be retrieved by `token.to_future` ot `token.to_event`.
+    # @example
+    #   cancellation, token = Concurrent::Cancellation.create
+    # @return [Array(Cancellation, Cancellation::Token)]
+    def self.create(resolvable_future_or_event = Promises.resolvable_event, *resolve_args)
+      cancellation = new(resolvable_future_or_event, *resolve_args)
+      [cancellation, cancellation.token]
+    end
+
+    private_class_method :new
+
+    # Returns the token associated with the cancellation.
+    # @return [Token]
+    def token
+      @Token
+    end
+
+    # Cancel this cancellation. All executions depending on the token will cooperatively stop.
+    # @return [true, false]
+    # @raise when cancelling for the second tim
+    def cancel(raise_on_repeated_call = true)
+      !!@Cancel.resolve(*@ResolveArgs, raise_on_repeated_call)
+    end
+
+    # Is the cancellation cancelled?
+    # @return [true, false]
+    def canceled?
+      @Cancel.resolved?
+    end
+
+    # Short string representation.
+    # @return [String]
+    def to_s
+      format '<#%s:0x%x canceled:%s>', self.class, object_id << 1, canceled?
+    end
+
+    alias_method :inspect, :to_s
+
+    private
+
+    def initialize(future, *resolve_args)
+      raise ArgumentError, 'future is not Resolvable' unless future.is_a?(Promises::Resolvable)
+      @Cancel      = future
+      @Token       = Token.new @Cancel.with_hidden_resolvable
+      @ResolveArgs = resolve_args
+    end
+
+    # Created through {Cancellation.create}, passed down to tasks to be able to check if canceled.
+    class Token < Synchronization::Object
+      safe_initialization!
+
+      # @return [Event] Event which will be resolved when the token is cancelled.
+      def to_event
+        @Cancel.to_event
+      end
+
+      # @return [Future] Future which will be resolved when the token is cancelled with arguments passed in
+      #   {Cancellation.create} .
+      def to_future
+        @Cancel.to_future
+      end
+
+      # Is the token cancelled?
+      # @return [true, false]
+      def canceled?
+        @Cancel.resolved?
+      end
+
+      # Repeatedly evaluates block until the token is {#canceled?}.
+      # @yield to the block repeatedly.
+      # @yieldreturn [Object]
+      # @return [Object] last result of the block
+      def loop_until_canceled(&block)
+        until canceled?
+          result = block.call
+        end
+        result
+      end
+
+      # Raise error when cancelled
+      # @param [#exception] error to be risen
+      # @raise the error
+      # @return [self]
+      def raise_if_canceled(error = CancelledOperationError)
+        raise error if canceled?
+        self
+      end
+
+      # Creates a new token which is cancelled when any of the tokens is.
+      # @param [Token] tokens to combine
+      # @return [Token] new token
+      def join(*tokens, &block)
+        block ||= -> tokens { Promises.any_event(*tokens.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?
+      end
+
+      alias_method :inspect, :to_s
+
+      private
+
+      def initialize(cancel)
+        @Cancel = cancel
+      end
+    end
+
+    # FIXME (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