concurrent-ruby-edge 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fbdcb68284676b68b0826e622fbf09d4c5582791155d43a7ecfd2bb13c580e4
-  data.tar.gz: eb6b90d57d7c81b4f53bb1916fd8ecb38756574b85927a3f27cb19a6ba949476
+  metadata.gz: e86341312f902de51400e475c3f05e35592c6c8178974e6a1bb58b16e91230ac
+  data.tar.gz: dafef294e63a9fa19760978ef848b60bb6ec2b2e6db0cb948a893d2d379d2eeb
 SHA512:
-  metadata.gz: '00384bbf0fef2ede15415470ba56bd433565142dbd174e2a9c4fa244e14acbd75eeaa806f190c3f43139c459ebcc9ef61f874911dce917c4e395727ad8053db3'
-  data.tar.gz: 53ce62dd73f9b3b4524ad591bf580c2fca45b3e47961b939845d05a35e38afcca29a535c9ce8062fad59932b0f118df6afa1fa9a4bf52d597743917ec9108470
+  metadata.gz: 6251909073feaacc9bf1dbaacf192a1fa71cf264ed9a0cca60a7039151b27458252ccc857377761d4c2a104610e6f978d983f75bd474eebbb3f5b1e3d68ecb56
+  data.tar.gz: 7e201108e4e985a4afa99e8b6ab280420c20b0e07e1dc83988555c11f6fd52383068f59af935000fccaa41a01717251ba6827cfe48c4404c35faf29791b845c0

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## Current
 
+## Release v1.1.5, edge v0.5.0 (10 mar 2019)
+
+concurrent-ruby:
+
+* fix potential leak of context on JRuby and Java 7
+
+concurrent-ruby-edge:
+
+* Add finalized Concurrent::Cancellation
+* Add finalized Concurrent::Throttle
+* Add finalized Concurrent::Promises::Channel
+* Add new Concurrent::ErlangActor
+
+## Release v1.1.4 (14 Dec 2018)
+
+* (#780) Remove java_alias of 'submit' method of Runnable to let executor service work on java 11
+* (#776) Fix NameError on defining a struct with a name which is already taken in an ancestor
+
+## Release v1.1.3 (7 Nov 2018)
+
+* (#775) fix partial require of the gem (although not officially supported)
+
+## Release v1.1.2 (6 Nov 2018)
+
+* (#773) more defensive 1.9.3 support
+
 ## Release v1.1.1, edge v0.4.1 (1 Nov 2018)
 
 * (#768) add support for 1.9.3 back 

data/README.md

@@ -42,8 +42,8 @@ appreciate your help. Would you like to contribute? Great! Have a look at
 ## Thread Safety
 
 *Concurrent Ruby makes one of the strongest thread safety guarantees of any Ruby concurrency 
-library, providing consistent behavior and guarantees on all three of the main Ruby interpreters 
-(MRI/CRuby, JRuby, and Rubinius).*
+library, providing consistent behavior and guarantees on all four of the main Ruby interpreters 
+(MRI/CRuby, JRuby, Rubinius, TruffleRuby).*
 
 Every abstraction in this library is thread safe. Specific thread safety guarantees are documented 
 with each abstraction.
@@ -59,7 +59,7 @@ Concurrent Ruby is also the only Ruby library which provides a full suite of thr
 immutable variable types and data structures.
 
 We've also initiated discussion to document [memory model](docs-source/synchronization.md) of Ruby which 
-would provide consistent behaviour and guarantees on all three of the main Ruby interpreters 
+would provide consistent behaviour and guarantees on all four of the main Ruby interpreters 
 (MRI/CRuby, JRuby, Rubinius, TruffleRuby).
 
 ## Features & Documentation
@@ -224,6 +224,35 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
     *Status: will be moved to core soon.*
 *   [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/LockFreeStack.html)
     *Status: missing documentation and tests.*
+*   [Promises::Channel](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises/Channel.html)
+    A first in first out channel that accepts messages with push family of methods and returns
+    messages with pop family of methods.
+    Pop and push operations can be represented as futures, see `#pop_op` and `#push_op`.
+    The capacity of the channel can be limited to support back pressure, use capacity option in `#initialize`.
+    `#pop` method blocks ans `#pop_op` returns pending future if there is no message in the channel.
+    If the capacity is limited the `#push` method blocks and `#push_op` returns pending future.
+*   [Cancellation](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Cancellation.html)
+    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 
+*   [Throttle](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Throttle.html)
+    A tool managing concurrency level of tasks.
+*   [ErlangActor](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ErlangActor.html)
+    Actor implementation which precisely matches Erlang actor behaviour. 
+    Requires at least Ruby 2.1 otherwise it's not loaded.
 
 ## Supported Ruby versions
 
@@ -339,11 +368,14 @@ and to the past maintainers
 *   [Paweł Obrok](https://github.com/obrok)
 *   [Lucas Allan](https://github.com/lucasallan)
 
+and to [Ruby Association](https://www.ruby.or.jp/en/) for sponsoring a project 
+["Enhancing Ruby’s concurrency tooling"](https://www.ruby.or.jp/en/news/20181106) in 2018. 
+
 ## License and Copyright
 
 *Concurrent Ruby* is free software released under the 
 [MIT License](http://www.opensource.org/licenses/MIT).
 
-The *Concurrent Ruby* [logo](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Logo) was
+The *Concurrent Ruby* [logo](https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/docs-source/logo/concurrent-ruby-logo-300x300.png) was
 designed by [David Jones](https://twitter.com/zombyboy). It is Copyright &copy; 2014 
 [Jerry D'Antonio](https://twitter.com/jerrydantonio). All Rights Reserved.

data/lib-edge/concurrent-edge.rb

@@ -1,5 +1,7 @@
 require 'concurrent'
 
+require 'concurrent/edge/version'
+
 require 'concurrent/actor'
 require 'concurrent/agent'
 require 'concurrent/channel'
@@ -10,5 +12,7 @@ require 'concurrent/edge/lock_free_queue'
 
 require 'concurrent/edge/cancellation'
 require 'concurrent/edge/throttle'
+require 'concurrent/edge/channel'
 
 require 'concurrent/edge/processing_actor'
+require 'concurrent/edge/erlang_actor' if Concurrent.ruby_version :>=, 2, 1, 0

data/lib-edge/concurrent/actor/reference.rb

@@ -55,6 +55,9 @@ 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.
       #

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

@@ -1,139 +1,105 @@
+require 'concurrent/concern/deprecation'
+
 module Concurrent
 
-  # Provides tools for cooperative cancellation.
-  # Inspired by <https://msdn.microsoft.com/en-us/library/dd537607(v=vs.110).aspx>
+  # 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
   #
-  # @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
+  # 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!
 
-    # 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]
+    # 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
 
-    private_class_method :new
+    # 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
 
-    # Returns the token associated with the cancellation.
-    # @return [Token]
-    def token
-      @Token
+    # 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
 
-    # 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)
+    # 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?
-      @Cancel.resolved?
+      @Origin.resolved?
     end
 
-    # Short string representation.
-    # @return [String]
-    def to_s
-      format '%s canceled:%s>', super[0..-2], canceled?
+    # 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
 
-    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
+    # 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
 
-    # 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 ||= -> 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 canceled:%s>', super[0..-2], canceled?
-      end
-
-      alias_method :inspect, :to_s
-
-      private
-
-      def initialize(cancel)
-        @Cancel = cancel
-      end
+    # Short string representation.
+    # @return [String]
+    def to_s
+      format '%s %s>', super[0..-2], canceled? ? 'canceled' : 'pending'
     end
 
-    # 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)
+    alias_method :inspect, :to_s
   end
 end

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

@@ -0,0 +1,450 @@
+# @!macro warn.edge
+module Concurrent
+  module Promises
+
+    # A first in first out channel that accepts messages with push family of methods and returns
+    # messages with pop family of methods.
+    # Pop and push operations can be represented as futures, see {#pop_op} and {#push_op}.
+    # The capacity of the channel can be limited to support back pressure, use capacity option in {#initialize}.
+    # {#pop} method blocks ans {#pop_op} returns pending future if there is no message in the channel.
+    # If the capacity is limited the {#push} method blocks and {#push_op} returns pending future.
+    #
+    # {include:file:docs-source/channel.out.md}
+    # @!macro warn.edge
+    class Channel < Concurrent::Synchronization::Object
+
+      # TODO (pitr-ch 06-Jan-2019): rename to Conduit?, to be able to place it into Concurrent namespace?
+      # TODO (pitr-ch 14-Jan-2019): better documentation, do few examples from go
+      # TODO (pitr-ch 12-Dec-2018): implement channel closing,
+      #   - as a child class? To also have a channel which cannot be closed.
+      # TODO (pitr-ch 26-Dec-2016): replace with lock-free implementation, at least getting a message when available should be lock free same goes for push with space available
+
+      # @!macro channel.warn.blocks
+      #   @note This function potentially blocks current thread until it can continue.
+      #     Be careful it can deadlock.
+      #
+      # @!macro channel.param.timeout
+      #   @param [Numeric] timeout the maximum time in second to wait.
+
+      safe_initialization!
+
+      # Default capacity of the Channel, makes it accept unlimited number of messages.
+      UNLIMITED_CAPACITY = ::Object.new
+      UNLIMITED_CAPACITY.singleton_class.class_eval do
+        include Comparable
+
+        def <=>(other)
+          1
+        end
+
+        def to_s
+          'unlimited'
+        end
+      end
+
+      NOTHING = Object.new
+      private_constant :NOTHING
+
+      # An object which matches anything (with #===)
+      ANY = Object.new.tap do |any|
+        def any.===(other)
+          true
+        end
+
+        def any.to_s
+          'ANY'
+        end
+      end
+
+      # Create channel.
+      # @param [Integer, UNLIMITED_CAPACITY] capacity the maximum number of messages which can be stored in the channel.
+      def initialize(capacity = UNLIMITED_CAPACITY)
+        super()
+        @Capacity = capacity
+        @Mutex    = Mutex.new
+        # TODO (pitr-ch 28-Jan-2019): consider linked lists or other data structures for following attributes, things are being deleted from the middle
+        @Probes      = []
+        @Messages    = []
+        @PendingPush = []
+      end
+
+      # Push the message into the channel if there is space available.
+      # @param [Object] message
+      # @return [true, false]
+      def try_push(message)
+        @Mutex.synchronize { ns_try_push(message) }
+      end
+
+      # Returns future which will fulfill when the message is pushed to the channel.
+      # @!macro chanel.operation_wait
+      #   If it is later waited on the operation with a timeout e.g.`channel.pop_op.wait(1)`
+      #   it will not prevent the channel to fulfill the operation later after the timeout.
+      #   The operation has to be either processed later
+      #   ```ruby
+      #   pop_op = channel.pop_op
+      #   if pop_op.wait(1)
+      #     process_message pop_op.value
+      #   else
+      #     pop_op.then { |message| log_unprocessed_message message }
+      #   end
+      #   ```
+      #   or the operation can be prevented from completion after timing out by using
+      #   `channel.pop_op.wait(1, [true, nil, nil])`.
+      #   It will fulfill the operation on timeout preventing channel from doing the operation,
+      #   e.g. popping a message.
+      #
+      # @param [Object] message
+      # @return [ResolvableFuture(self)]
+      def push_op(message)
+        @Mutex.synchronize do
+          if ns_try_push(message)
+            Promises.fulfilled_future self
+          else
+            pushed = Promises.resolvable_future
+            @PendingPush.push message, pushed
+            return pushed
+          end
+        end
+      end
+
+      # Blocks current thread until the message is pushed into the channel.
+      #
+      # @!macro channel.warn.blocks
+      # @param [Object] message
+      # @!macro channel.param.timeout
+      # @return [self, true, false] self implies timeout was not used, true implies timeout was used
+      #   and it was pushed, false implies it was not pushed within timeout.
+      def push(message, timeout = nil)
+        pushed_op = @Mutex.synchronize do
+          return timeout ? true : self if ns_try_push(message)
+
+          pushed = Promises.resolvable_future
+          # TODO (pitr-ch 06-Jan-2019): clear timed out pushes in @PendingPush, null messages
+          @PendingPush.push message, pushed
+          pushed
+        end
+
+        result = pushed_op.wait!(timeout, [true, self, nil])
+        result == pushed_op ? self : result
+      end
+
+      # @!macro promises.channel.try_pop
+      #   Pop a message from the channel if there is one available.
+      #   @param [Object] no_value returned when there is no message available
+      #   @return [Object, no_value] message or nil when there is no message
+      def try_pop(no_value = nil)
+        try_pop_matching ANY, no_value
+      end
+
+      # @!macro promises.channel.try_pop
+      # @!macro promises.channel.param.matcher
+      #   @param [#===] matcher only consider message which matches `matcher === a_message`
+      def try_pop_matching(matcher, no_value = nil)
+        @Mutex.synchronize do
+          message = ns_shift_message matcher
+          return message if message != NOTHING
+          message = ns_consume_pending_push matcher
+          return message != NOTHING ? message : no_value
+        end
+      end
+
+      # @!macro promises.channel.pop_op
+      #   Returns a future witch will become fulfilled with a value from the channel when one is available.
+      #   @!macro chanel.operation_wait
+      #
+      #   @param [ResolvableFuture] probe the future which will be fulfilled with a channel value
+      #   @return [Future(Object)] the probe, its value will be the message when available.
+      def pop_op(probe = Promises.resolvable_future)
+        @Mutex.synchronize { ns_pop_op(ANY, probe, false) }
+      end
+
+      # @!macro promises.channel.pop_op
+      # @!macro promises.channel.param.matcher
+      def pop_op_matching(matcher, probe = Promises.resolvable_future)
+        @Mutex.synchronize { ns_pop_op(matcher, probe, false) }
+      end
+
+      # @!macro promises.channel.pop
+      #   Blocks current thread until a message is available in the channel for popping.
+      #
+      #   @!macro channel.warn.blocks
+      #   @!macro channel.param.timeout
+      #   @param [Object] timeout_value a value returned by the method when it times out
+      #   @return [Object, nil] message or nil when timed out
+      def pop(timeout = nil, timeout_value = nil)
+        pop_matching ANY, timeout, timeout_value
+      end
+
+      # @!macro promises.channel.pop
+      # @!macro promises.channel.param.matcher
+      def pop_matching(matcher, timeout = nil, timeout_value = nil)
+        # TODO (pitr-ch 27-Jan-2019): should it try to match pending pushes if it fails to match in the buffer? Maybe only if the size is zero. It could be surprising if it's used as a throttle it might be expected that it will not pop if buffer is full of messages which di not match, it might it expected it will block until the message is added to the buffer
+        # that it returns even if the buffer is full. User might expect that it has to be in the buffer first.
+        probe = @Mutex.synchronize do
+          message = ns_shift_message matcher
+          if message == NOTHING
+            message = ns_consume_pending_push matcher
+            return message if message != NOTHING
+          else
+            new_message = ns_consume_pending_push ANY
+            @Messages.push new_message unless new_message == NOTHING
+            return message
+          end
+
+          probe = Promises.resolvable_future
+          @Probes.push probe, false, matcher
+          probe
+        end
+
+        probe.value!(timeout, timeout_value, [true, timeout_value, nil])
+      end
+
+      # @!macro promises.channel.peek
+      #   Behaves as {#try_pop} but it does not remove the message from the channel
+      #   @param [Object] no_value returned when there is no message available
+      #   @return [Object, no_value] message or nil when there is no message
+      def peek(no_value = nil)
+        peek_matching ANY, no_value
+      end
+
+      # @!macro promises.channel.peek
+      # @!macro promises.channel.param.matcher
+      def peek_matching(matcher, no_value = nil)
+        @Mutex.synchronize do
+          message = ns_shift_message matcher, false
+          return message if message != NOTHING
+          message = ns_consume_pending_push matcher, false
+          return message != NOTHING ? message : no_value
+        end
+      end
+
+      # @!macro promises.channel.try_select
+      #   If message is available in the receiver or any of the provided channels
+      #   the channel message pair is returned. If there is no message nil is returned.
+      #   The returned channel is the origin of the message.
+      #
+      #   @param [Channel, ::Array<Channel>] channels
+      #   @return [::Array(Channel, Object), nil]
+      #     pair [channel, message] if one of the channels is available for reading
+      def try_select(channels)
+        try_select_matching ANY, channels
+      end
+
+      # @!macro promises.channel.try_select
+      # @!macro promises.channel.param.matcher
+      def try_select_matching(matcher, channels)
+        message = nil
+        channel = [self, *channels].find do |ch|
+          message = ch.try_pop_matching(matcher, NOTHING)
+          message != NOTHING
+        end
+        channel ? [channel, message] : nil
+      end
+
+      # @!macro promises.channel.select_op
+      #   When message is available in the receiver or any of the provided channels
+      #   the future is fulfilled with a channel message pair.
+      #   The returned channel is the origin of the message.
+      #   @!macro chanel.operation_wait
+      #
+      #   @param [Channel, ::Array<Channel>] channels
+      #   @param [ResolvableFuture] probe the future which will be fulfilled with the message
+      #   @return [ResolvableFuture(::Array(Channel, Object))] a future which is fulfilled with
+      #     pair [channel, message] when one of the channels is available for reading
+      def select_op(channels, probe = Promises.resolvable_future)
+        select_op_matching ANY, channels, probe
+      end
+
+      # @!macro promises.channel.select_op
+      # @!macro promises.channel.param.matcher
+      def select_op_matching(matcher, channels, probe = Promises.resolvable_future)
+        [self, *channels].each { |ch| ch.partial_select_op matcher, probe }
+        probe
+      end
+
+      # @!macro promises.channel.select
+      #   As {#select_op} but does not return future,
+      #   it block current thread instead until there is a message available
+      #   in the receiver or in any of the channels.
+      #
+      #   @!macro channel.warn.blocks
+      #   @param [Channel, ::Array<Channel>] channels
+      #   @!macro channel.param.timeout
+      #   @return [::Array(Channel, Object), nil] message or nil when timed out
+      #   @see #select_op
+      def select(channels, timeout = nil)
+        select_matching ANY, channels, timeout
+      end
+
+      # @!macro promises.channel.select
+      # @!macro promises.channel.param.matcher
+      def select_matching(matcher, channels, timeout = nil)
+        probe = select_op_matching(matcher, channels)
+        probe.value!(timeout, nil, [true, nil, nil])
+      end
+
+      # @return [Integer] The number of messages currently stored in the channel.
+      def size
+        @Mutex.synchronize { @Messages.size }
+      end
+
+      # @return [Integer] Maximum capacity of the Channel.
+      def capacity
+        @Capacity
+      end
+
+      # @return [String] Short string representation.
+      def to_s
+        format '%s capacity taken %s of %s>', super[0..-2], size, @Capacity
+      end
+
+      alias_method :inspect, :to_s
+
+      class << self
+
+        # @see #try_select
+        # @return [::Array(Channel, Object)]
+        def try_select(channels)
+          channels.first.try_select(channels[1..-1])
+        end
+
+        # @see #select_op
+        # @return [Future(::Array(Channel, Object))]
+        def select_op(channels, probe = Promises.resolvable_future)
+          channels.first.select_op(channels[1..-1], probe)
+        end
+
+        # @see #select
+        # @return [::Array(Channel, Object), nil]
+        def select(channels, timeout = nil)
+          channels.first.select(channels[1..-1], timeout)
+        end
+
+        # @see #try_select_matching
+        # @return [::Array(Channel, Object)]
+        def try_select_matching(matcher, channels)
+          channels.first.try_select_matching(matcher, channels[1..-1])
+        end
+
+        # @see #select_op_matching
+        # @return [Future(::Array(Channel, Object))]
+        def select_op_matching(matcher, channels, probe = Promises.resolvable_future)
+          channels.first.select_op_matching(matcher, channels[1..-1], probe)
+        end
+
+        # @see #select_matching
+        # @return [::Array(Channel, Object), nil]
+        def select_matching(matcher, channels, timeout = nil)
+          channels.first.select_matching(matcher, channels[1..-1], timeout)
+        end
+      end
+
+      # @!visibility private
+      def partial_select_op(matcher, probe)
+        @Mutex.synchronize { ns_pop_op(matcher, probe, true) }
+      end
+
+      private
+
+      def ns_pop_op(matcher, probe, include_channel)
+        message = ns_shift_message matcher
+
+        # got message from buffer
+        if message != NOTHING
+          if probe.fulfill(include_channel ? [self, message] : message, false)
+            new_message = ns_consume_pending_push ANY
+            @Messages.push new_message unless new_message == NOTHING
+          else
+            @Messages.unshift message
+          end
+          return probe
+        end
+
+        # no message in buffer, try to pair with a pending push
+        i = 0
+        while true
+          message, pushed = @PendingPush[i, 2]
+          break if pushed.nil?
+
+          if matcher === message
+            value = include_channel ? [self, message] : message
+            if Promises::Resolvable.atomic_resolution(probe  => [true, value, nil],
+                                                      pushed => [true, self, nil])
+              @PendingPush[i, 2] = []
+              return probe
+            end
+
+            if probe.resolved?
+              return probe
+            end
+
+            # so pushed.resolved? has to be true, remove the push
+            @PendingPush[i, 2] = []
+          end
+
+          i += 2
+        end
+
+        # no push to pair with
+        # TODO (pitr-ch 11-Jan-2019): clear up probes when timed out, use callback
+        @Probes.push probe, include_channel, matcher if probe.pending?
+        return probe
+      end
+
+      def ns_consume_pending_push(matcher, remove = true)
+        i = 0
+        while true
+          message, pushed = @PendingPush[i, 2]
+          return NOTHING unless pushed
+
+          if matcher === message
+            resolved           = pushed.resolved?
+            @PendingPush[i, 2] = [] if remove || resolved
+            # can fail if timed-out, so try without error
+            if remove ? pushed.fulfill(self, false) : !resolved
+              # pushed fulfilled so actually push the message
+              return message
+            end
+          end
+
+          i += 2
+        end
+      end
+
+      def ns_try_push(message)
+        i = 0
+        while true
+          probe, include_channel, matcher = @Probes[i, 3]
+          break unless probe
+          if matcher === message && probe.fulfill(include_channel ? [self, message] : message, false)
+            @Probes[i, 3] = []
+            return true
+          end
+          i += 3
+        end
+
+        if @Capacity > @Messages.size
+          @Messages.push message
+          true
+        else
+          false
+        end
+      end
+
+      def ns_shift_message(matcher, remove = true)
+        i = 0
+        while true
+          message = @Messages.fetch(i, NOTHING)
+          return NOTHING if message == NOTHING
+
+          if matcher === message
+            @Messages.delete_at i if remove
+            return message
+          end
+
+          i += 1
+        end
+      end
+    end
+  end
+end