concurrently 1.0.1 → 1.1.0

data/lib/all/concurrently/proc/evaluation/error.rb

@@ -0,0 +1,13 @@
+module Concurrently
+  class Proc::Evaluation
+    class Cancelled < Exception
+      # should not be rescued accidentally and therefore is an exception
+    end
+
+    module RescueableError
+      [ScriptError, StandardError, SystemStackError].each do |error_class|
+        append_features error_class
+      end
+    end
+  end
+end

data/lib/all/concurrently/proc/fiber.rb

@@ -1,10 +1,6 @@
 module Concurrently
   # @private
   class Proc::Fiber < ::Fiber
-    class Cancelled < Exception
-      # should not be rescued accidentally and therefore is an exception
-    end
-
     EMPTY_EVALUATION_BUCKET = [].freeze
 
     def initialize(fiber_pool)
@@ -43,12 +39,13 @@ module Concurrently
               result = proc.__proc_call__ *args
               (evaluation = evaluation_bucket[0]) and evaluation.conclude_to result
               result
-            rescue Cancelled
+            rescue Proc::Evaluation::Cancelled
               # raised in Kernel#await_resume!
               :cancelled
-            rescue *RESCUABLE_ERRORS => error
+            rescue Proc::Evaluation::RescueableError => error
               # Rescue all errors not critical for other concurrent evaluations
               # and don't let them leak to the loop to keep it up and running.
+              STDERR.puts error
               proc.trigger :error, error
               (evaluation = evaluation_bucket[0]) and evaluation.conclude_to error
               error

data/lib/all/concurrently/version.rb

@@ -4,5 +4,5 @@
 # The namespace this library lives in
 module Concurrently
   # The version
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/all/io.rb

@@ -1,14 +1,12 @@
 # @api public
-# @since 1.0.0
 #
 # Concurrently adds a few methods to `IO` which make them available
 # for every IO instance.
 class IO
-  # Suspends the current evaluation until IO is readable. It can be used inside
-  # and outside of concurrent procs.
+  # Suspends the current evaluation until IO is readable.
   #
   # While waiting, the code jumps to the event loop and executes other
-  # concurrent procs that are ready to run in the meantime.
+  # evaluations that are ready to run in the meantime.
   #
   # @param [Hash] opts
   # @option opts [Numeric] :within maximum time to wait *(defaults to: Float::INFINITY)*
@@ -19,17 +17,17 @@ class IO
   # @raise [Concurrently::Evaluation::TimeoutError] if a given maximum waiting time
   #   is exceeded and no custom timeout result is given.
   #
-  # @example Waiting inside a concurrent proc
+  # @example Waiting inside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   r,w = IO.pipe
   #
   #   # (1)
-  #   wait_proc = concurrent_proc do
-  #      # (4)
-  #      r.await_readable
-  #      # (6)
-  #      r.read
+  #   reader = concurrently do
+  #     # (4)
+  #     r.await_readable
+  #     # (6)
+  #     r.read
   #   end
   #
   #   # (2)
@@ -40,12 +38,12 @@ class IO
   #   end
   #
   #   # (3)
-  #   wait_proc.call # => 'Hey from the other proc!'
+  #   reader.await_result # => 'Hey from the other proc!'
   #   # (7)
   #
   #   r.close
   #
-  # @example Waiting outside a concurrent proc
+  # @example Waiting outside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   r,w = IO.pipe
@@ -73,7 +71,9 @@ class IO
   # @example Waiting with a timeout and a timeout result
   #   r,w = IO.pipe
   #   r.await_readable(within: 0.1, timeout_result: false)
-  #   # => returns false after 0.1 second
+  #   # => returns false after 0.1 seconds
+  #
+  # @since 1.0.0
   def await_readable(opts = {})
     io_selector = Concurrently::EventLoop.current.io_selector
     io_selector.await_reader(self, Concurrently::Evaluation.current)
@@ -82,7 +82,7 @@ class IO
     io_selector.cancel_reader(self)
   end
 
-  # Reads from IO concurrently.
+  # Waits until successfully read from IO with blocking other evaluations.
   #
   # If IO is not readable right now it blocks the current concurrent evaluation
   # and tries again after it became readable.
@@ -91,9 +91,9 @@ class IO
   #
   # ```
   # begin
-  #   read_nonblock(maxlen, buf)
+  #   io.read_nonblock(maxlen, outbuf)
   # rescue IO::WaitReadable
-  #   await_readable
+  #   io.await_readable
   #   retry
   # end
   # ```
@@ -103,33 +103,75 @@ class IO
   #
   # @example
   #   r,w = IO.pipe
-  #   w.concurrently_write "Hello!"
-  #   r.concurrently_read 1024 # => "Hello!"
+  #   w.write "Hello!"
+  #   r.await_read 1024 # => "Hello!"
   #
-  # @overload concurrently_read(maxlen)
+  # @overload await_read(maxlen)
   #   Reads maxlen bytes from IO and returns it as new string
   #
   #   @param [Integer] maxlen
   #   @return [String] read string
   #
-  # @overload concurrently_read(maxlen, outbuf)
+  # @overload await_read(maxlen, outbuf)
   #   Reads maxlen bytes from IO and fills the given buffer with them.
   #
   #   @param [Integer] maxlen
   #   @param [String] outbuf
   #   @return [outbuf] outbuf filled with read string
-  def concurrently_read(maxlen, outbuf = nil)
+  #
+  # @since 1.1.0
+  def await_read(maxlen, outbuf = nil)
     read_nonblock(maxlen, outbuf)
   rescue IO::WaitReadable
     await_readable
     retry
   end
 
-  # Suspends the current evaluation until IO is writable. It can be used inside
-  # and outside of concurrent procs.
+  # Reads from IO concurrently.
+  #
+  # Reading is done in a concurrent evaluation in the background.
+  #
+  # This method is a shortcut for:
+  #
+  # ```
+  # concurrently{ io.await_read(maxlen, outbuf) }
+  # ```
+  #
+  # @see https://ruby-doc.org/core/IO.html#method-i-read_nonblock
+  #   Ruby documentation for `IO#read_nonblock` for details about parameters and return values.
+  #
+  # @example
+  #   r,w = IO.pipe
+  #   w.write "Hello!"
+  #   r.concurrently_read 1024 # => "Hello!"
+  #
+  # @overload concurrently_read(maxlen)
+  #   Reads maxlen bytes from IO and returns it as new string
+  #
+  #   @param [Integer] maxlen
+  #   @return [String] read string
+  #
+  # @overload concurrently_read(maxlen, outbuf)
+  #   Reads maxlen bytes from IO and fills the given buffer with them.
+  #
+  #   @param [Integer] maxlen
+  #   @param [String] outbuf
+  #   @return [outbuf] outbuf filled with read string
+  #
+  # @since 1.0.0
+  def concurrently_read(maxlen, outbuf = nil)
+    READ_PROC.call_detached(self, maxlen, outbuf)
+  end
+
+  # @private
+  READ_PROC = Concurrently::Proc.new do |io, maxlen, outbuf|
+    io.await_read(maxlen, outbuf)
+  end
+
+  # Suspends the current evaluation until IO is writable.
   #
   # While waiting, the code jumps to the event loop and executes other
-  # concurrent procs that are ready to run in the meantime.
+  # evaluations that are ready to run in the meantime.
   #
   # @param [Hash] opts
   # @option opts [Numeric] :within maximum time to wait *(defaults to: Float::INFINITY)*
@@ -140,7 +182,7 @@ class IO
   # @raise [Concurrently::Evaluation::TimeoutError] if a given maximum waiting time
   #   is exceeded and no custom timeout result is given.
   #
-  # @example Waiting inside a concurrent proc
+  # @example Waiting inside a evaluation
   #   # Control flow is indicated by (N)
   #
   #   r,w = IO.pipe
@@ -149,12 +191,12 @@ class IO
   #   w.write 'x'*65536
   #
   #   # (1)
-  #   wait_proc = concurrent_proc do
-  #      # (4)
-  #      w.await_writable
-  #      # (6)
-  #      w.write 'I can write again!'
-  #      :written
+  #   writer = concurrently do
+  #     # (4)
+  #     w.await_writable
+  #     # (6)
+  #     w.write 'I can write again!'
+  #     :written
   #   end
   #
   #   # (2)
@@ -164,12 +206,12 @@ class IO
   #   end
   #
   #   # (3)
-  #   wait_proc.call # => :written
+  #   writer.await_result # => :written
   #   # (7)
   #
   #   r.close; w.close
   #
-  # @example Waiting outside a concurrent proc
+  # @example Waiting outside a evaluation
   #   # Control flow is indicated by (N)
   #
   #   r,w = IO.pipe
@@ -204,7 +246,9 @@ class IO
   #   w.write 'x'*65536
   #
   #   w.await_writable(within: 0.1, timeout_result: false)
-  #   # => returns false after 0.1 second
+  #   # => returns false after 0.1 seconds
+  #
+  # @since 1.0.0
   def await_writable(opts = {})
     io_selector = Concurrently::EventLoop.current.io_selector
     io_selector.await_writer(self, Concurrently::Evaluation.current)
@@ -213,18 +257,18 @@ class IO
     io_selector.cancel_writer(self)
   end
 
-  # Writes to IO concurrently.
+  # Waits until successfully written to IO with blocking other evaluations.
   #
-  # If IO is not writable right now it blocks the current concurrent proc
+  # If IO is not writable right now it blocks the current evaluation
   # and tries again after it became writable.
   #
   # This methods is a shortcut for:
   #
   # ```
   # begin
-  #   write_nonblock(string)
+  #   io.write_nonblock(string)
   # rescue IO::WaitWritable
-  #   await_writable
+  #   io.await_writable
   #   retry
   # end
   # ```
@@ -237,12 +281,45 @@ class IO
   #
   # @example
   #   r,w = IO.pipe
-  #   w.concurrently_write "Hello!"
-  #   r.concurrently_read 1024 # => "Hello!"
-  def concurrently_write(string)
+  #   w.await_written "Hello!"
+  #   r.read 1024 # => "Hello!"
+  #
+  # @since 1.1.0
+  def await_written(string)
     write_nonblock(string)
   rescue IO::WaitWritable
     await_writable
     retry
   end
+
+  # Writes to IO concurrently.
+  #
+  # Writing is done in a concurrent evaluation in the background.
+  #
+  # This method is a shortcut for:
+  #
+  # ```
+  # concurrently{ io.await_written(string) }
+  # ```
+  #
+  # @param [String] string to write
+  # @return [Integer] bytes written
+  #
+  # @see https://ruby-doc.org/core/IO.html#method-i-write_nonblock
+  #   Ruby documentation for `IO#write_nonblock` for details about parameters and return values.
+  #
+  # @example
+  #   r,w = IO.pipe
+  #   w.concurrently_write "Hello!"
+  #   r.read 1024 # => "Hello!"
+  #
+  # @since 1.0.0
+  def concurrently_write(string)
+    WRITE_PROC.call_detached(self, string)
+  end
+
+  # @private
+  WRITE_PROC = Concurrently::Proc.new do |io, string|
+    io.await_written(string)
+  end
 end

data/lib/all/kernel.rb

@@ -1,5 +1,4 @@
 # @api public
-# @since 1.0.0
 #
 # Concurrently adds a few methods to `Kernel` which makes them available
 # for every object.
@@ -8,7 +7,7 @@ module Kernel
   #
   # Executes code concurrently in the background.
   #
-  # This is a shortcut for {Concurrently::Proc#call_and_forget}.
+  # This is a shortcut for {Concurrently::Proc#call_detached}.
   #
   # @return [nil]
   #
@@ -16,9 +15,11 @@ module Kernel
   #   concurrently(a,b,c) do |a,b,c|
   #     # ...
   #   end
+  #
+  # @since 1.0.0
   private def concurrently(*args)
     # Concurrently::Proc.new claims the method's block just like Proc.new does
-    Concurrently::Proc.new.call_and_forget *args
+    Concurrently::Proc.new.call_detached *args
   end
 
   # @!method concurrent_proc(&block)
@@ -32,10 +33,12 @@ module Kernel
   #
   # @example
   #   wait_proc = concurrent_proc do |seconds|
-  #      wait seconds
+  #     wait seconds
   #   end
   #
   #   wait_proc.call 2 # waits 2 seconds and then resumes
+  #
+  # @since 1.0.0
   private def concurrent_proc(evaluation_class = Concurrently::Proc::Evaluation)
     # Concurrently::Proc.new claims the method's block just like Proc.new does
     Concurrently::Proc.new(evaluation_class)
@@ -45,8 +48,7 @@ module Kernel
   #   This method needs to be complemented with a later call to
   #   {Concurrently::Evaluation#resume!}.
   #
-  # Suspends the current evaluation until it is resumed manually. It can be
-  # used inside and outside of concurrent procs.
+  # Suspends the current evaluation until it is resumed manually.
   #
   # It needs to be complemented with a later call of {Concurrently::Evaluation#resume!}.
   #
@@ -60,15 +62,15 @@ module Kernel
   # @raise [Concurrently::Evaluation::TimeoutError] if a given maximum waiting time
   #   is exceeded and no custom timeout result is given.
   #
-  # @example Waiting inside a concurrent proc
+  # @example Waiting inside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   # (1)
-  #   evaluation = concurrent_proc do
-  #      # (4)
-  #      await_resume!
-  #      # (7)
-  #   end.call_nonblock
+  #   evaluation = concurrently do
+  #     # (4)
+  #     await_resume!
+  #     # (7)
+  #   end
   #
   #   # (2)
   #   concurrently do
@@ -82,7 +84,7 @@ module Kernel
   #   evaluation.await_result # => :result
   #   # (8)
   #
-  # @example Waiting outside a concurrent proc
+  # @example Waiting outside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   evaluation = Concurrently::Evaluation.current
@@ -105,7 +107,9 @@ module Kernel
   #
   # @example Waiting with a timeout and a timeout result
   #   await_resume! within: 0.1, timeout_result: false
-  #   # => returns false after 0.1 second
+  #   # => returns false after 0.1 seconds
+  #
+  # @since 1.0.0
   private def await_resume!(opts = {})
     event_loop = Concurrently::EventLoop.current
     run_queue = event_loop.run_queue
@@ -131,13 +135,7 @@ module Kernel
     # prematurely.
     if evaluation.fiber == result
       run_queue.cancel evaluation # in case the evaluation has already been scheduled to resume
-
-      # Generally, throw-catch is faster than raise-rescue if the code needs to
-      # play back the call stack, i.e. the throw resp. raise is invoked. If not
-      # playing back the call stack, a begin block is faster than a catch
-      # block. Since we won't jump out of the proc above most of the time, we
-      # go with raise. It is rescued in the proc fiber.
-      raise Concurrently::Proc::Fiber::Cancelled, '', []
+      raise Concurrently::Proc::Evaluation::Cancelled, ''
     elsif Concurrently::Evaluation::TimeoutError == result
       raise result, "evaluation timed out after #{seconds} second(s)"
     else
@@ -149,21 +147,20 @@ module Kernel
     end
   end
 
-  # Suspends the current evaluation for the given number of seconds. It can be
-  # used inside and outside of concurrent procs.
+  # Suspends the current evaluation for the given number of seconds.
   #
   # While waiting, the code jumps to the event loop and executes other
-  # concurrent procs that are ready to run in the meantime.
+  # evaluations that are ready to run in the meantime.
   #
   # @return [true]
   #
-  # @example Waiting inside a concurrent proc
+  # @example Waiting inside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   # (1)
-  #   wait_proc = concurrent_proc do |seconds|
+  #   wait_eval = concurrently do
   #     # (4)
-  #     wait seconds
+  #     wait 1
   #     # (6)
   #     :waited
   #   end
@@ -175,10 +172,10 @@ module Kernel
   #   end
   #
   #   # (3)
-  #   wait_proc.call 1 # => :waited
+  #   wait_eval.await_result # => :waited
   #   # (7)
   #
-  # @example Waiting outside a concurrent proc
+  # @example Waiting outside a concurrent evaluation
   #   # Control flow is indicated by (N)
   #
   #   # (1)
@@ -190,6 +187,8 @@ module Kernel
   #   # (2)
   #   wait 1
   #   # (4)
+  #
+  # @since 1.0.0
   private def wait(seconds)
     run_queue = Concurrently::EventLoop.current.run_queue
     evaluation = run_queue.current_evaluation
@@ -198,4 +197,58 @@ module Kernel
   ensure
     run_queue.cancel evaluation
   end
+
+  # Waits for the first in a list of evaluations to be concluded.
+  #
+  # @overload await_fastest(evaluation0, evaluation1, *more_evaluations, opts = {})
+  #
+  #   @param [Concurrently::Proc::Evaluation] evaluation0
+  #   @param [Concurrently::Proc::Evaluation] evaluation1
+  #   @param [Concurrently::Proc::Evaluation] *more_evaluations
+  #   @param [Hash] opts
+  #   @option opts [Numeric] :within maximum time to wait *(defaults to: Float::INFINITY)*
+  #   @option opts [Object] :timeout_result result to return in case of an exceeded
+  #     waiting time *(defaults to raising {Concurrently::Evaluation::TimeoutError})*
+  #
+  # @return [Concurrently::Proc::Evaluation] the evaluation been concluded first
+  # @raise [Concurrently::Evaluation::TimeoutError] if a given maximum waiting time
+  #   is exceeded and no custom timeout result is given.
+  #
+  # @example
+  #   evaluation0 = concurrently{ wait 2 }
+  #   evaluation1 = concurrently{ wait 1 }
+  #
+  #   await_fastest(evaluation0, evaluation1) # => evaluation1
+  #
+  # @example Waiting with a timeout
+  #   evaluation0 = concurrently{ wait 2 }
+  #   evaluation1 = concurrently{ wait 1 }
+  #
+  #   await_fastest(evaluation0, evaluation1, within: 0.1)
+  #   # => raises a TimeoutError after 0.1 seconds
+  #
+  # @example Waiting with a timeout and a timeout result
+  #   evaluation0 = concurrently{ wait 2 }
+  #   evaluation1 = concurrently{ wait 1 }
+  #
+  #   await_fastest(evaluation0, evaluation1, within: 0.1, timeout_result: false)
+  #   # => returns false after 0.1 seconds
+  #
+  # @since 1.1.0
+  private def await_fastest(eval0, eval1, *evaluations)
+    opts = (evaluations.last.is_a? Hash) ? evaluations.pop : {}
+    evaluations.unshift eval0, eval1
+
+    if concluded = evaluations.find(&:concluded?)
+      concluded
+    else
+      begin
+        curr_eval = Concurrently::Evaluation.current
+        evaluations.each{ |e| e.instance_eval{ @awaiting_result.store curr_eval, self } }
+        await_resume! opts
+      ensure
+        evaluations.each{ |e| e.instance_eval{ @awaiting_result.delete curr_eval } }
+      end
+    end
+  end
 end