concurrently 1.0.1

data/lib/all/concurrently/error.rb

@@ -0,0 +1,10 @@
+module Concurrently
+  # @api public
+  # @since 1.0.0
+  #
+  # The general error of this gem.
+  class Error < StandardError; end
+
+  # @private
+  RESCUABLE_ERRORS = [ScriptError, StandardError, SystemStackError]
+end

data/lib/all/concurrently/evaluation.rb

@@ -0,0 +1,109 @@
+module Concurrently
+  # @api public
+  # @since 1.0.0
+  #
+  # `Concurrently::Evaluation` represents the evaluation of the main thread
+  # outside of any concurrent procs.
+  #
+  # @note Evaluations are **not thread safe**. They are operating on a fiber.
+  #   Fibers cannot be resumed inside a thread they were not created in.
+  #
+  # An instance will be returned by {current} if called outside of any
+  # concurrent procs.
+  class Evaluation
+    # The evaluation that is currently running in the current thread.
+    #
+    # This method is thread safe. Each thread returns its own currently running
+    # evaluation.
+    #
+    # @return [Evaluation]
+    #
+    # @example
+    #   concurrent_proc do
+    #     Concurrently::Evaluation.current # => #<Concurrently::Proc::Evaluation:0x00000000e56910>
+    #   end.call_nonblock
+    #
+    #   Concurrently::Evaluation.current # => #<Concurrently::Evaluation0x00000000e5be10>
+    def self.current
+      EventLoop.current.run_queue.current_evaluation
+    end
+
+    # @private
+    def initialize(fiber)
+      @fiber = fiber
+    end
+
+    # @private
+    #
+    # The fiber the evaluation runs inside.
+    attr_reader :fiber
+
+    # @!attribute [r] waiting?
+    #
+    # Checks if the evaluation is waiting
+    #
+    # @return [Boolean]
+    def waiting?
+      @waiting
+    end
+
+    # @private
+    DEFAULT_RESUME_OPTS = { deferred_only: true }.freeze
+    
+    # @note The exclamation mark in its name stands for: Watch out!
+    #   This method is potentially dangerous and can break stuff. It also
+    #   needs to be complemented by an earlier call of {Kernel#await_resume!}.
+    #
+    # Schedules the evaluation to be resumed
+    #
+    # It needs to be complemented by an earlier call of {Kernel#await_resume!}.
+    #
+    # This method is potentially dangerous. {Kernel#wait}, {IO#await_readable},
+    # {IO#await_writable} and {Proc::Evaluation#await_result} are implemented
+    # with {Kernel#await_resume!}. Concurrent evaluations waiting because of
+    # them are resumed when calling {#resume!} although the event they are
+    # actually awaiting has not happened yet:
+    #
+    # ```ruby
+    # conproc = concurrent_proc do
+    #   wait 1
+    #   await_resume!
+    # end
+    #
+    # conproc.resume! # resumes the wait call prematurely
+    # ```
+    #
+    # To use this method safely, make sure the evaluation to resume is waiting
+    # because of a manual call of {Kernel#await_resume!}.
+    #
+    # @return [:resumed]
+    # @raise [Error] if the evaluation is not waiting
+    #
+    # @example
+    #   # Control flow is indicated by (N)
+    #
+    #   # (1)
+    #   evaluation = concurrent_proc do
+    #     # (2)
+    #     await_resume!
+    #     # (4)
+    #   end.call_nonblock
+    #
+    #   # (3)
+    #   evaluation.resume! :result
+    #   # (5)
+    #   evaluation.await_result # => :result
+    def resume!(result = nil)
+      run_queue = Concurrently::EventLoop.current.run_queue
+
+      # Cancel running the fiber if it has already been scheduled to run; but
+      # only if it was scheduled with a time offset. This is used to cancel the
+      # timeout of a wait operation if the waiting fiber is resume before the
+      # timeout is triggered.
+      run_queue.cancel(self, DEFAULT_RESUME_OPTS)
+
+      run_queue.schedule_immediately(self, result)
+      :resumed
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Concurrently
+  class Evaluation
+    # @api public
+    # @since 1.0.0
+    #
+    # A general error for a failed evaluation. It is only used if the error
+    # can not be attributed to an error in the executed block of code of the
+    # proc itself.
+    class Error < Concurrently::Error; end
+
+    # @api public
+    # @since 1.0.0
+    #
+    # An error indicating an evaluation could not be concluded in a given
+    # time frame
+    class TimeoutError < Error; end
+  end
+end

data/lib/all/concurrently/event_loop.rb

@@ -0,0 +1,101 @@
+module Concurrently
+  # @api public
+  # @since 1.0.0
+  #
+  # @note Although you probably won't need to interact with the event loop
+  #   directly (unless you call `Kernel#fork`, see {#reinitialize!}), you need
+  #   to understand that it's there.
+  #
+  # @note Event loops are **not thread safe**. But since each thread has its
+  #   own event loop they are not shared anyway.
+  #
+  # `Concurrently::EventLoop`, like any event loop, is the heart of your
+  # application and **must never be interrupted, blocked or overloaded.** A
+  # healthy event loop is one that can respond to new events immediately.
+  #
+  # The loop runs in the background and you won't interact with it directly.
+  # Instead, when you call `#wait` or one of the `#await_*` methods the
+  # bookkeeping of selecting IOs for readiness or waiting a given amount of
+  # time is done for you.
+  class EventLoop
+    # The event loop of the current thread.
+    #
+    # This method is thread safe. Each thread returns its own event loop.
+    #
+    # @example
+    #   Concurrently::EventLoop.current
+    def self.current
+      @current ||= new
+    end
+
+    # @private
+    #
+    # A new instance
+    #
+    # An event loop is created for every thread automatically. It should not
+    # be instantiated manually.
+    def initialize
+      reinitialize!
+    end
+
+    # @note The exclamation mark in its name stands for: Watch out!
+    #   This method will break stuff if not used in the right place.
+    #
+    # Resets the inner state of the event loop.
+    #
+    # In detail, calling this method for the event loop:
+    #
+    # * resets its {#lifetime},
+    # * clears its internal run queue,
+    # * clears its internal list of watched IOs,
+    # * clears its internal pool of fibers.
+    #
+    # While this method clears the list of IOs watched for readiness, the IOs
+    # themselves are left untouched. You are responsible for managing IOs (e.g.
+    # closing them).
+    #
+    # @example
+    #   fork do
+    #     Concurrently::EventLoop.current.reinitialize!
+    #     # ...
+    #   end
+    #
+    #   # ...
+    def reinitialize!
+      @start_time = Time.now.to_f
+      @run_queue = RunQueue.new self
+      @io_selector = IOSelector.new self
+      @proc_fiber_pool = ProcFiberPool.new self
+      @fiber = Fiber.new @run_queue, @io_selector, @proc_fiber_pool
+      self
+    end
+
+    # @private
+    #
+    # Its run queue keeping track of and scheduling all concurrent procs
+    attr_reader :run_queue
+
+    # @private
+    #
+    # Its selector to watch IOs.
+    attr_reader :io_selector
+
+    # @private
+    #
+    # Its fiber running the actual loop
+    attr_reader :fiber
+
+    # @private
+    #
+    # Its pool of reusable fibers to run the code of concurrent procs in.
+    attr_reader :proc_fiber_pool
+
+    # The lifetime of this event loop in seconds
+    #
+    # @example
+    #   Concurrently::EventLoop.current.lifetime # => 2.3364
+    def lifetime
+      Time.now.to_f - @start_time
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Concurrently
+  # @private
+  class EventLoop::Fiber < ::Fiber
+    def initialize(run_queue, io_selector, proc_fiber_pool)
+      super() do
+        begin
+          while true
+            if (waiting_time = run_queue.waiting_time) == 0
+              # Check ready IOs although fibers are ready to run to not neglect
+              # IO operations. Otherwise, IOs might become jammed since they
+              # are constantly written to but not read from.
+              # This behavior is not covered in the test suite. It becomes
+              # apparent only in situations of heavy load where this event loop
+              # has not much time to breathe.
+              io_selector.process_ready_in waiting_time if io_selector.awaiting?
+
+              run_queue.process_pending
+            elsif io_selector.awaiting? or waiting_time
+              io_selector.process_ready_in waiting_time
+            else
+              # Having no pending timeouts or IO events would make run this loop
+              # forever. But, since we always start the loop from one of the
+              # *await* methods, it is also always returning to them after waiting
+              # is complete. Therefore, we never reach this part of the code unless
+              # there is a bug or it is messed around with the internals of this gem.
+              raise Error, "Infinitely running event loop detected: There " <<
+                "are no concurrent procs or fibers scheduled and no IOs to await."
+            end
+          end
+        rescue Exception => e
+          Concurrently::EventLoop.current.reinitialize!
+          raise Error, "Event loop teared down by #{e.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/all/concurrently/event_loop/io_selector.rb

@@ -0,0 +1,42 @@
+module Concurrently
+  # @private
+  class EventLoop::IOSelector
+    def initialize(event_loop)
+      @run_queue = event_loop.run_queue
+      @readers = {}
+      @writers = {}
+      @evaluations = {}
+    end
+
+    def awaiting?
+      @evaluations.any?
+    end
+
+    def await_reader(io, evaluation)
+      @readers[evaluation] = io
+      @evaluations[io] = evaluation
+    end
+
+    def await_writer(io, evaluation)
+      @writers[evaluation] = io
+      @evaluations[io] = evaluation
+    end
+
+    def cancel_reader(io)
+      @readers.delete @evaluations.delete io
+    end
+
+    def cancel_writer(io)
+      @writers.delete @evaluations.delete io
+    end
+
+    def process_ready_in(waiting_time)
+      waiting_time = nil if waiting_time == Float::INFINITY
+      if selected = IO.select(@readers.values, @writers.values, nil, waiting_time)
+        selected.each do |ios|
+          ios.each{ |io| @run_queue.resume_evaluation! @evaluations[io], true }
+        end
+      end
+    end
+  end
+end

data/lib/all/concurrently/event_loop/proc_fiber_pool.rb

@@ -0,0 +1,18 @@
+module Concurrently
+  # @private
+  # The fiber pool grows dynamically if its internal store of fibers is empty.
+  class EventLoop::ProcFiberPool
+    def initialize(event_loop)
+      @event_loop = event_loop
+      @fibers = []
+    end
+
+    def take_fiber
+      @fibers.pop or Proc::Fiber.new self
+    end
+
+    def return(fiber)
+      @fibers << fiber
+    end
+  end
+end

data/lib/all/concurrently/event_loop/run_queue.rb

@@ -0,0 +1,111 @@
+module Concurrently
+  # @private
+  class EventLoop::RunQueue
+    # The items of the run queue are called carts. Carts are simple arrays
+    # with the following layout: [evaluation, time, result]
+    EVALUATION = 0; TIME = 1; RESULT = 2
+
+    # There are two tracks. The fast track and the regular cart track. The
+    # fast track exists for evaluations to be scheduled immediately. Having a
+    # dedicated track lets us just push carts to the track in the order they
+    # appear. This saves us the rather expensive #bisect_left computation where
+    # on the regular cart track to insert the cart.
+
+    # The additional cart index exists so carts can be cancelled by their
+    # evaluation. Cancelled carts have their evaluation set to false.
+
+    DEFAULT_CANCEL_OPTS = { deferred_only: false }.freeze
+
+    class Track < Array
+      def bisect_left
+        bsearch_index{ |item| yield item } || length
+      end
+    end
+
+    def initialize(loop)
+      @loop = loop
+      @cart_index = {}
+      @deferred_track = Track.new
+      @immediate_track = Track.new
+    end
+
+    def schedule_immediately(evaluation, result = nil)
+      cart = [evaluation, false, result]
+      @cart_index[evaluation.hash] = cart
+      @immediate_track << cart
+    end
+
+    def schedule_deferred(evaluation, seconds, result = nil)
+      cart = [evaluation, @loop.lifetime+seconds, result]
+      @cart_index[evaluation.hash] = cart
+      index = @deferred_track.bisect_left{ |tcart| tcart[TIME] <= cart[TIME] }
+      @deferred_track.insert(index, cart)
+    end
+
+    def cancel(evaluation, opts = DEFAULT_CANCEL_OPTS)
+      if (cart = @cart_index[evaluation.hash]) and (not opts[:deferred_only] or cart[TIME])
+        cart[EVALUATION] = false
+      end
+    end
+
+    def process_pending
+      # Clear the fast track in the beginning so that carts added to it while
+      # processing pending carts will be processed during the next iteration.
+      processing = @immediate_track
+      @immediate_track = []
+
+      if @deferred_track.any?
+        now = @loop.lifetime
+        index = @deferred_track.bisect_left{ |cart| cart[TIME] <= now }
+        @deferred_track.pop(@deferred_track.length-index).reverse_each do |cart|
+          processing << cart
+        end
+      end
+
+      processing.each do |cart|
+        @cart_index.delete cart[EVALUATION].hash
+        resume_evaluation! cart[EVALUATION], cart[RESULT] if cart[EVALUATION]
+      end
+    end
+
+    def waiting_time
+      if @immediate_track.any?
+        0
+      elsif next_cart = @deferred_track.reverse_each.find{ |cart| cart[EVALUATION] }
+        waiting_time = next_cart[TIME] - @loop.lifetime
+        waiting_time < 0 ? 0 : waiting_time
+      end
+    end
+
+    def resume_evaluation!(evaluation, result)
+      previous_evaluation = @current_evaluation
+
+      case evaluation
+      when Proc::Fiber # this will only happen when calling Concurrently::Proc#call_and_forget
+        @current_evaluation = nil
+        evaluation.resume result
+      when Proc::Evaluation
+        @current_evaluation = evaluation
+        evaluation.fiber.resume result
+      else
+        @current_evaluation = nil
+        Fiber.yield result
+      end
+    ensure
+      @current_evaluation = previous_evaluation
+    end
+
+    # only needed in Concurrently::Proc#call_nonblock
+    attr_accessor :current_evaluation
+    attr_writer :evaluation_class
+
+    def current_evaluation
+      @current_evaluation ||= case fiber = Fiber.current
+      when Proc::Fiber
+        (@evaluation_class || Proc::Evaluation).new fiber
+      else
+        Evaluation.new fiber
+      end
+    end
+  end
+end