concurrently 1.0.1

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

@@ -0,0 +1,67 @@
+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)
+      # Creation of fibers is quite expensive. To reduce the cost we make
+      # them reusable:
+      # - Each concurrent proc is executed during one iteration of the loop
+      #   inside a fiber.
+      # - At the end of each iteration we put the fiber back into the fiber
+      #   pool of the event loop.
+      # - Taking a fiber out of the pool and resuming it will enter the
+      #   next iteration.
+      super() do |proc, args, evaluation_bucket|
+        # The fiber's proc, arguments to call the proc with and evaluation
+        # are passed when scheduled right after creation or taking it out of
+        # the pool.
+
+        while true
+          evaluation_bucket ||= EMPTY_EVALUATION_BUCKET
+
+          result = if proc == self
+            # If we are given this very fiber when starting itself it means it
+            # has been evaluated right before its start. In this case just
+            # yield back to the evaluating fiber.
+            Fiber.yield
+
+            # When this fiber is started because it is next on schedule it will
+            # just finish without running the proc.
+
+            :cancelled
+          elsif not Proc === proc
+            # This should never happen. If it does it means something with code
+            # of this library is not right.
+            raise Concurrently::Error, "concurrent proc not started properly."
+          else
+            begin
+              result = proc.__proc_call__ *args
+              (evaluation = evaluation_bucket[0]) and evaluation.conclude_to result
+              result
+            rescue Cancelled
+              # raised in Kernel#await_resume!
+              :cancelled
+            rescue *RESCUABLE_ERRORS => 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.
+              proc.trigger :error, error
+              (evaluation = evaluation_bucket[0]) and evaluation.conclude_to error
+              error
+            end
+          end
+
+          fiber_pool.return self
+
+          # Yield back to the event loop fiber or the fiber evaluating this one
+          # and wait for the next proc to evaluate.
+          proc, args, evaluation_bucket = Fiber.yield result
+        end
+      end
+    end
+  end
+end

data/lib/all/concurrently/version.rb

@@ -0,0 +1,8 @@
+# @api public
+# @since 1.0.0
+#
+# The namespace this library lives in
+module Concurrently
+  # The version
+  VERSION = "1.0.1"
+end

data/lib/all/io.rb

@@ -0,0 +1,248 @@
+# @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.
+  #
+  # While waiting, the code jumps to the event loop and executes other
+  # concurrent procs that are ready to run in the meantime.
+  #
+  # @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 [true]
+  # @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
+  #   # Control flow is indicated by (N)
+  #
+  #   r,w = IO.pipe
+  #
+  #   # (1)
+  #   wait_proc = concurrent_proc do
+  #      # (4)
+  #      r.await_readable
+  #      # (6)
+  #      r.read
+  #   end
+  #
+  #   # (2)
+  #   concurrently do
+  #     # (5)
+  #     w.write 'Hey from the other proc!'
+  #     w.close
+  #   end
+  #
+  #   # (3)
+  #   wait_proc.call # => 'Hey from the other proc!'
+  #   # (7)
+  #
+  #   r.close
+  #
+  # @example Waiting outside a concurrent proc
+  #   # Control flow is indicated by (N)
+  #
+  #   r,w = IO.pipe
+  #
+  #   # (1)
+  #   concurrently do
+  #     # (3)
+  #     puts "I'm running while the outside is waiting!"
+  #     w.write "Continue!"
+  #     w.close
+  #   end
+  #
+  #   # (2)
+  #   r.await_readable
+  #   # (4)
+  #   r.read # => "Continue!"
+  #
+  #   r.close
+  #
+  # @example Waiting with a timeout
+  #   r,w = IO.pipe
+  #   r.await_readable(within: 1)
+  #   # => raises a TimeoutError after 1 second
+  #
+  # @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
+  def await_readable(opts = {})
+    io_selector = Concurrently::EventLoop.current.io_selector
+    io_selector.await_reader(self, Concurrently::Evaluation.current)
+    await_resume! opts
+  ensure
+    io_selector.cancel_reader(self)
+  end
+
+  # Reads from IO concurrently.
+  #
+  # If IO is not readable right now it blocks the current concurrent evaluation
+  # and tries again after it became readable.
+  #
+  # This method is a shortcut for:
+  #
+  # ```
+  # begin
+  #   read_nonblock(maxlen, buf)
+  # rescue IO::WaitReadable
+  #   await_readable
+  #   retry
+  # end
+  # ```
+  #
+  # @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.concurrently_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
+  def concurrently_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.
+  #
+  # While waiting, the code jumps to the event loop and executes other
+  # concurrent procs that are ready to run in the meantime.
+  #
+  # @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 [true]
+  # @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
+  #   # Control flow is indicated by (N)
+  #
+  #   r,w = IO.pipe
+  #
+  #   # jam the pipe with x's, assuming the pipe's max capacity is 2^16 bytes
+  #   w.write 'x'*65536
+  #
+  #   # (1)
+  #   wait_proc = concurrent_proc do
+  #      # (4)
+  #      w.await_writable
+  #      # (6)
+  #      w.write 'I can write again!'
+  #      :written
+  #   end
+  #
+  #   # (2)
+  #   concurrently do
+  #     # (5)
+  #     r.read 65536 # clear the pipe
+  #   end
+  #
+  #   # (3)
+  #   wait_proc.call # => :written
+  #   # (7)
+  #
+  #   r.close; w.close
+  #
+  # @example Waiting outside a concurrent proc
+  #   # Control flow is indicated by (N)
+  #
+  #   r,w = IO.pipe
+  #
+  #   # jam the pipe with x's, assuming the pipe's max capacity is 2^16 bytes
+  #   w.write 'x'*65536
+  #
+  #   # (1)
+  #   concurrently do
+  #     # (3)
+  #     puts "I'm running while the outside is waiting!"
+  #     r.read 65536 # clear the pipe
+  #   end
+  #
+  #   # (2)
+  #   w.await_writable
+  #   # (4)
+  #
+  #   r.close; w.close
+  #
+  # @example Waiting with a timeout
+  #   r,w = IO.pipe
+  #   # jam the pipe with x's, assuming the pipe's max capacity is 2^16 bytes
+  #   w.write 'x'*65536
+  #
+  #   w.await_writable(within: 1)
+  #   # => raises a TimeoutError after 1 second
+  #
+  # @example Waiting with a timeout and a timeout result
+  #   r,w = IO.pipe
+  #   # jam the pipe with x's, assuming the pipe's max capacity is 2^16 bytes
+  #   w.write 'x'*65536
+  #
+  #   w.await_writable(within: 0.1, timeout_result: false)
+  #   # => returns false after 0.1 second
+  def await_writable(opts = {})
+    io_selector = Concurrently::EventLoop.current.io_selector
+    io_selector.await_writer(self, Concurrently::Evaluation.current)
+    await_resume! opts
+  ensure
+    io_selector.cancel_writer(self)
+  end
+
+  # Writes to IO concurrently.
+  #
+  # If IO is not writable right now it blocks the current concurrent proc
+  # and tries again after it became writable.
+  #
+  # This methods is a shortcut for:
+  #
+  # ```
+  # begin
+  #   write_nonblock(string)
+  # rescue IO::WaitWritable
+  #   await_writable
+  #   retry
+  # end
+  # ```
+  #
+  # @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.concurrently_read 1024 # => "Hello!"
+  def concurrently_write(string)
+    write_nonblock(string)
+  rescue IO::WaitWritable
+    await_writable
+    retry
+  end
+end

data/lib/all/kernel.rb

@@ -0,0 +1,201 @@
+# @api public
+# @since 1.0.0
+#
+# Concurrently adds a few methods to `Kernel` which makes them available
+# for every object.
+module Kernel
+  # @!method concurrently(*args, &block)
+  #
+  # Executes code concurrently in the background.
+  #
+  # This is a shortcut for {Concurrently::Proc#call_and_forget}.
+  #
+  # @return [nil]
+  #
+  # @example
+  #   concurrently(a,b,c) do |a,b,c|
+  #     # ...
+  #   end
+  private def concurrently(*args)
+    # Concurrently::Proc.new claims the method's block just like Proc.new does
+    Concurrently::Proc.new.call_and_forget *args
+  end
+
+  # @!method concurrent_proc(&block)
+  #
+  # Creates a concurrent proc to execute code concurrently.
+  #
+  # This a shortcut for {Concurrently::Proc}.new(&block) like `proc(&block)`
+  # is a shortcut for `Proc.new(&block)`.
+  #
+  # @return [Concurrently::Proc]
+  #
+  # @example
+  #   wait_proc = concurrent_proc do |seconds|
+  #      wait seconds
+  #   end
+  #
+  #   wait_proc.call 2 # waits 2 seconds and then resumes
+  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)
+  end
+
+  # @note The exclamation mark in its name stands for: Watch out!
+  #   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.
+  #
+  # It needs to be complemented with a later call of {Concurrently::Evaluation#resume!}.
+  #
+  # @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 [Object] the result {Concurrently::Evaluation#resume!} is called
+  #   with.
+  # @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
+  #   # Control flow is indicated by (N)
+  #
+  #   # (1)
+  #   evaluation = concurrent_proc do
+  #      # (4)
+  #      await_resume!
+  #      # (7)
+  #   end.call_nonblock
+  #
+  #   # (2)
+  #   concurrently do
+  #     # (5)
+  #     puts "I'm running while the outside is waiting!"
+  #     evaluation.resume! :result
+  #     # (6)
+  #   end
+  #
+  #   # (3)
+  #   evaluation.await_result # => :result
+  #   # (8)
+  #
+  # @example Waiting outside a concurrent proc
+  #   # Control flow is indicated by (N)
+  #
+  #   evaluation = Concurrently::Evaluation.current
+  #
+  #   # (1)
+  #   concurrently do
+  #     # (3)
+  #     puts "I'm running while the outside is waiting!"
+  #     evaluation.resume! :result
+  #     # (4)
+  #   end
+  #
+  #   # (2)
+  #   await_resume! # => :result
+  #   # (5)
+  #
+  # @example Waiting with a timeout
+  #   await_resume! within: 1
+  #   # => raises a TimeoutError after 1 second
+  #
+  # @example Waiting with a timeout and a timeout result
+  #   await_resume! within: 0.1, timeout_result: false
+  #   # => returns false after 0.1 second
+  private def await_resume!(opts = {})
+    event_loop = Concurrently::EventLoop.current
+    run_queue = event_loop.run_queue
+    evaluation = run_queue.current_evaluation
+
+    if seconds = opts[:within]
+      timeout_result = opts.fetch(:timeout_result, Concurrently::Evaluation::TimeoutError)
+      run_queue.schedule_deferred(evaluation, seconds, timeout_result)
+    end
+
+    evaluation.instance_variable_set :@waiting, true
+    result = case evaluation
+    when Concurrently::Proc::Evaluation
+      # Yield back to the event loop fiber or the evaluation evaluating this one.
+      # Pass along itself to indicate it is not yet fully evaluated.
+      Fiber.yield evaluation
+    else
+      event_loop.fiber.resume
+    end
+    evaluation.instance_variable_set :@waiting, false
+
+    # If result is this very evaluation it means this evaluation has been evaluated
+    # 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, '', []
+    elsif Concurrently::Evaluation::TimeoutError == result
+      raise result, "evaluation timed out after #{seconds} second(s)"
+    else
+      result
+    end
+  ensure
+    if seconds
+      run_queue.cancel evaluation
+    end
+  end
+
+  # Suspends the current evaluation for the given number of seconds. It can be
+  # used inside and outside of concurrent procs.
+  #
+  # While waiting, the code jumps to the event loop and executes other
+  # concurrent procs that are ready to run in the meantime.
+  #
+  # @return [true]
+  #
+  # @example Waiting inside a concurrent proc
+  #   # Control flow is indicated by (N)
+  #
+  #   # (1)
+  #   wait_proc = concurrent_proc do |seconds|
+  #     # (4)
+  #     wait seconds
+  #     # (6)
+  #     :waited
+  #   end
+  #
+  #   # (2)
+  #   concurrently do
+  #     # (5)
+  #     puts "I'm running while the other proc is waiting!"
+  #   end
+  #
+  #   # (3)
+  #   wait_proc.call 1 # => :waited
+  #   # (7)
+  #
+  # @example Waiting outside a concurrent proc
+  #   # Control flow is indicated by (N)
+  #
+  #   # (1)
+  #   concurrently do
+  #     # (3)
+  #     puts "I'm running while the outside is waiting!"
+  #   end
+  #
+  #   # (2)
+  #   wait 1
+  #   # (4)
+  private def wait(seconds)
+    run_queue = Concurrently::EventLoop.current.run_queue
+    evaluation = run_queue.current_evaluation
+    run_queue.schedule_deferred(evaluation, seconds, true)
+    await_resume!
+  ensure
+    run_queue.cancel evaluation
+  end
+end