backports 3.18.1 → 3.20.2

data/lib/backports/3.0.0/ractor.rb

@@ -0,0 +1,19 @@
+if RUBY_VERSION < '2'
+  warn 'Ractor not backported to Ruby 1.x'
+elsif defined?(Ractor.current)
+  # all good
+else
+  # Cloner:
+  require_relative '../2.4.0/hash/transform_values'
+  require_relative '../2.5.0/hash/transform_keys'
+  # Queues & FilteredQueue
+  require_relative '../2.3.0/queue/close'
+
+  class Ractor
+  end
+
+  module Backports
+    Ractor = ::Ractor
+  end
+  require_relative '../ractor/ractor'
+end

data/lib/backports/3.0.0/symbol.rb

@@ -0,0 +1,3 @@
+require 'backports/tools/require_relative_dir'
+
+Backports.require_relative_dir

data/lib/backports/3.0.0/symbol/name.rb

@@ -0,0 +1,11 @@
+unless Symbol.method_defined? :name
+  def Backports.symbol_names
+    @symbol_names ||= ObjectSpace::WeakMap.new
+  end
+
+  class Symbol
+    def name
+      Backports.symbol_names[self] ||= to_s.freeze
+    end
+  end
+end

data/lib/backports/3.0.rb

@@ -0,0 +1 @@
+require 'backports/3.0.0'

data/lib/backports/ractor/cloner.rb

@@ -0,0 +1,94 @@
+# shareable_constant_value: literal
+
+using ::RubyNext if defined?(::RubyNext)
+
+module Backports
+  class Ractor
+    module Cloner
+      extend self
+
+      def deep_clone(obj)
+        return obj if Ractor.ractor_shareable_self?(obj, false) { false }
+
+        @processed = {}.compare_by_identity
+        @changed = nil
+        result = process(obj) do |r|
+          copy_contents(r)
+        end
+        return result if result
+
+        Ractor.ractor_mark_set_shareable(@processed)
+        obj
+      end
+
+      # Yields a deep copy.
+      # If no deep copy is needed, `obj` is returned and
+      # nothing is yielded
+      private def clone_deeper(obj)
+        return obj if Ractor.ractor_shareable_self?(obj, false) { false }
+
+        result = process(obj) do |r|
+          copy_contents(r)
+        end
+        return obj unless result
+
+        yield result if block_given?
+        result
+      end
+
+      # Yields if `obj` is a new structure
+      # Returns the deep copy, or `false` if no deep copy is needed
+      private def process(obj)
+        @processed.fetch(obj) do
+          # For recursive structures, assume that we'll need a duplicate.
+          # If that's not the case, we will have duplicated the whole structure
+          # for nothing...
+          @processed[obj] = result = obj.dup
+          changed = track_change { yield result }
+          return false if obj.frozen? && !changed
+
+          @changed = true
+          result.freeze if obj.frozen?
+
+          result
+        end
+      end
+
+      # returns if the block called `deep clone` and that the deep copy was needed
+      private def track_change
+        prev = @changed
+        @changed = false
+        yield
+        @changed
+      ensure
+        @changed = prev
+      end
+
+      # modifies in place `obj` by calling `deep clone` on its contents
+      private def copy_contents(obj)
+        case obj
+        when ::Hash
+          if obj.default
+            clone_deeper(obj.default) do |copy|
+              obj.default = copy
+            end
+          end
+          obj.transform_keys! { |key| clone_deeper(key) }
+          obj.transform_values! { |value| clone_deeper(value) }
+        when ::Array
+          obj.map! { |item| clone_deeper(item) }
+        when ::Struct
+          obj.each_pair do |key, item|
+            clone_deeper(item) { |copy| obj[key] = copy }
+          end
+        end
+        obj.instance_variables.each do |var|
+          clone_deeper(obj.instance_variable_get(var)) do |copy|
+            obj.instance_variable_set(var, copy)
+          end
+        end
+      end
+    end
+    private_constant :Cloner
+  end
+end

data/lib/backports/ractor/errors.rb

@@ -0,0 +1,20 @@
+# shareable_constant_value: literal
+
+module Backports
+  class Ractor
+    class ClosedError < ::StopIteration
+    end
+
+    class Error < ::StandardError
+    end
+
+    class RemoteError < Error
+      attr_reader :ractor
+
+      def initialize(message = nil)
+        @ractor = Ractor.current
+        super
+      end
+    end
+  end
+end

data/lib/backports/ractor/filtered_queue.rb

@@ -0,0 +1,205 @@
+# shareable_constant_value: literal
+
+module Backports
+  # Like ::Queue, but with
+  # - filtering
+  # - timeout
+  # - raises on closed queues
+  #
+  # Independent from other Ractor related backports.
+  class FilteredQueue
+    CONSUME_ON_ESCAPE = true
+
+    class ClosedQueueError < ::ClosedQueueError
+    end
+
+    class TimeoutError < ::ThreadError
+    end
+
+    class Message
+      # Not using Struct as we want comparision by identity
+      attr_reader :value
+      attr_accessor :reserved
+
+      def initialize(value)
+        @value = value
+        @reserved = false
+      end
+    end
+    private_constant :Message
+
+    attr_reader :num_waiting
+
+    # Timeout processing based on https://spin.atomicobject.com/2017/06/28/queue-pop-with-timeout-fixed/
+    def initialize
+      @mutex = ::Mutex.new
+      @queue = []
+      @closed = false
+      @received = ::ConditionVariable.new
+      @num_waiting = 0
+    end
+
+    def close
+      @mutex.synchronize do
+        @closed = true
+        @received.broadcast
+      end
+      self
+    end
+
+    def closed?
+      @closed
+    end
+
+    def <<(x)
+      @mutex.synchronize do
+        ensure_open
+        @queue << Message.new(x)
+        @received.signal
+      end
+      self
+    end
+    alias_method :push, :<<
+
+    def clear
+      @mutex.synchronize do
+        @queue.clear
+      end
+      self
+    end
+
+    def pop(timeout: nil, &block)
+      msg = nil
+      exclude = [] if block # exclusion list of messages rejected by this call
+      timeout_time = timeout + Time.now.to_f if timeout
+      while true do # rubocop:disable Style/InfiniteLoop, Style/WhileUntilDo
+        @mutex.synchronize do
+          reenter if reentrant?
+          msg = acquire!(timeout_time, exclude)
+          return consume!(msg).value unless block
+        end
+        return msg.value if filter?(msg, &block)
+      end
+    end
+
+    def empty?
+      avail = @mutex.synchronize do
+        available!
+      end
+
+      !avail
+    end
+
+    protected def timeout_value
+      raise self.class::TimeoutError, "timeout elapsed"
+    end
+
+    protected def closed_queue_value
+      ensure_open
+    end
+
+    # @return if outer message should be consumed or not
+    protected def reenter
+      true
+    end
+
+    ### private section
+    #
+    # bang methods require synchronization
+
+    # @returns:
+    # * true if message consumed (block result truthy or due to reentrant call)
+    # * false if rejected
+    private def filter?(msg)
+      consume = self.class::CONSUME_ON_ESCAPE
+      begin
+        reentered = consume_on_reentry(msg) do
+          consume = !!(yield msg.value)
+        end
+        reentered ? reenter : consume
+      ensure
+        commit(msg, consume) unless reentered
+      end
+    end
+
+    # @returns msg
+    private def consume!(msg)
+      @queue.delete(msg)
+    end
+
+    private def reject!(msg)
+      msg.reserved = false
+      @received.broadcast
+    end
+
+    private def commit(msg, consume)
+      @mutex.synchronize do
+        if consume
+          consume!(msg)
+        else
+          reject!(msg)
+        end
+      end
+    end
+
+    private def consume_on_reentry(msg)
+      q_map = current_filtered_queues
+      if (outer_msg = q_map[self])
+        commit(outer_msg, reenter)
+      end
+      q_map[self] = msg
+      begin
+        yield
+      ensure
+        reentered = !q_map.delete(self)
+      end
+      reentered
+    end
+
+    private def reentrant?
+      !!current_filtered_queues[self]
+    end
+
+    # @returns Hash { FilteredQueue => Message }
+    private def current_filtered_queues
+      t = Thread.current
+      t.thread_variable_get(:backports_currently_filtered_queues) or
+        t.thread_variable_set(:backports_currently_filtered_queues, {}.compare_by_identity)
+    end
+
+    # private methods assume @mutex synchonized
+    # adds to exclude list
+    private def acquire!(timeout_time, exclude = nil)
+      while true do # rubocop:disable Style/InfiniteLoop, Style/WhileUntilDo
+        if (msg = available!(exclude))
+          msg.reserved = true
+          exclude << msg if exclude
+          return msg
+        end
+        return closed_queue_value if @closed
+        # wait for element or timeout
+        if timeout_time
+          remaining_time = timeout_time - ::Time.now.to_f
+          return timeout_value if remaining_time <= 0
+        end
+        begin
+          @num_waiting += 1
+          @received.wait(@mutex, remaining_time)
+        ensure
+          @num_waiting -= 1
+        end
+      end
+    end
+
+    private def available!(exclude = nil)
+      @queue.find do |msg|
+        next if exclude && exclude.include?(msg)
+        !msg.reserved
+      end
+    end
+
+    private def ensure_open
+      raise self.class::ClosedQueueError, 'queue closed' if @closed
+    end
+  end
+end

data/lib/backports/ractor/queues.rb

@@ -0,0 +1,66 @@
+# shareable_constant_value: literal
+
+require_relative 'filtered_queue'
+
+module Backports
+  class Ractor
+    # Standard ::Queue but raises if popping and closed
+    class BaseQueue < FilteredQueue
+      ClosedQueueError = Ractor::ClosedError
+
+      # yields message (if any)
+      def pop_non_blocking
+        yield pop(timeout: 0)
+      rescue TimeoutError
+        nil
+      end
+    end
+
+    class IncomingQueue < BaseQueue
+      TYPE = :incoming
+
+      protected def reenter
+        raise Ractor::Error, 'Can not reenter'
+      end
+    end
+
+    # * Wraps exception
+    # * Add `ack: ` to push (blocking)
+    class OutgoingQueue < BaseQueue
+      TYPE = :outgoing
+
+      WrappedException = ::Struct.new(:exception, :ractor)
+
+      def initialize
+        @ack_queue = ::Queue.new
+        super
+      end
+
+      def pop(timeout: nil, ack: true)
+        r = super(timeout: timeout)
+        @ack_queue << :done if ack
+        raise r.exception if WrappedException === r
+
+        r
+      end
+
+      def close(how = :hard)
+        super()
+        return if how == :soft
+
+        clear
+        @ack_queue.close
+      end
+
+      def push(obj, ack:)
+        super(obj)
+        if ack
+          r = @ack_queue.pop # block until popped
+          raise ClosedError, "The #{self.class::TYPE}-port is already closed" unless r == :done
+        end
+        self
+      end
+    end
+    private_constant :BaseQueue, :OutgoingQueue, :IncomingQueue
+  end
+end

data/lib/backports/ractor/ractor.rb

@@ -0,0 +1,272 @@
+# shareable_constant_value: literal
+
+# Ruby 2.0+ backport of `Ractor` class
+# Extra private methods and instance variables all start with `ractor_`
+module Backports
+  class Ractor
+    require_relative '../tools/arguments'
+
+    require_relative 'cloner'
+    require_relative 'errors'
+    require_relative 'queues'
+    require_relative 'sharing'
+
+    RactorThreadGroups = ::ObjectSpace::WeakMap.new # ThreadGroup => Ractor
+    private_constant :RactorThreadGroups
+    # Implementation notes
+    #
+    # Uses one `Thread` for each `Ractor`, as well as queues for communication
+    #
+    # The incoming queue is strict: contrary to standard queue, you can't pop from an empty closed queue.
+    # Since standard queues return `nil` is those conditions, we wrap/unwrap `nil` values and consider
+    # all `nil` values to be results of closed queues. `ClosedQueueError` are re-raised as `Ractor::ClosedError`
+    #
+    # The outgoing queue is strict and blocking. Same wrapping / raising as incoming,
+    # with an extra queue to acknowledge when a value has been read (or if the port is closed while waiting).
+    #
+    # The last result is a bit tricky as it needs to be pushed on the outgoing queue but can not be blocking.
+    # For this, we "soft close" the outgoing port.
+
+    def initialize(*args, &block)
+      @ractor_incoming_queue = IncomingQueue.new
+      @ractor_outgoing_queue = OutgoingQueue.new
+      raise ::ArgumentError, 'must be called with a block' unless block
+
+      kw = args.last
+      if kw.is_a?(::Hash) && kw.size == 1 && kw.key?(:name)
+        args.pop
+        name = kw[:name]
+      end
+      @ractor_name = name && Backports.coerce_to_str(name)
+
+      @id = Ractor.ractor_next_id
+      if Ractor.main == nil # then initializing main Ractor
+        @ractor_thread = ::Thread.current
+        @ractor_origin = nil
+        @ractor_thread.thread_variable_set(:backports_ractor, self)
+      else
+        @ractor_origin = caller(1, 1).first.split(':in `').first
+
+        args.map! { |a| Ractor.ractor_isolate(a, false) }
+        ractor_thread_start(args, block)
+      end
+    end
+
+    private def ractor_thread_start(args, block)
+      ::Thread.new do
+        @ractor_thread = ::Thread.current
+        @ractor_thread_group = ::ThreadGroup.new
+        RactorThreadGroups[@ractor_thread_group] = self
+        @ractor_thread_group.add(@ractor_thread)
+        ::Thread.current.thread_variable_set(:backports_ractor, self)
+        result = nil
+        begin
+          result = instance_exec(*args, &block)
+        rescue ::Exception => err # rubocop:disable Lint/RescueException
+          begin
+            raise RemoteError, "thrown by remote Ractor: #{err.message}"
+          rescue RemoteError => e # Hack to create exception with `cause`
+            result = OutgoingQueue::WrappedException.new(e)
+          end
+        ensure
+          ractor_thread_terminate(result)
+        end
+      end
+    end
+
+    private def ractor_thread_terminate(result)
+      begin
+        ractor_outgoing_queue.push(result, ack: false) unless ractor_outgoing_queue.closed?
+      rescue ::ClosedQueueError
+        return # ignore
+      end
+      ractor_incoming_queue.close
+      ractor_outgoing_queue.close(:soft)
+    ensure
+      # TODO: synchronize?
+      @ractor_thread_group.list.each do |thread|
+        thread.kill unless thread == Thread.current
+      end
+    end
+
+    def send(obj, move: false)
+      ractor_incoming_queue << Ractor.ractor_isolate(obj, move)
+      self
+    rescue ::ClosedQueueError
+      raise ClosedError, 'The incoming-port is already closed'
+    end
+    alias_method :<<, :send
+
+    def take
+      ractor_outgoing_queue.pop(ack: true)
+    end
+
+    def name
+      @ractor_name
+    end
+
+    RACTOR_STATE = {
+      'sleep' => 'blocking',
+      'run' => 'running',
+      'aborting' => 'aborting',
+      false => 'terminated',
+      nil => 'terminated',
+    }.freeze
+    private_constant :RACTOR_STATE
+
+    def inspect
+      state = RACTOR_STATE[@ractor_thread ? @ractor_thread.status : 'run']
+      info = [
+        "Ractor:##{@id}",
+        name,
+        @ractor_origin,
+        state,
+      ].compact.join(' ')
+
+      "#<#{info}>"
+    end
+
+    def close_incoming
+      r = ractor_incoming_queue.closed?
+      ractor_incoming_queue.close
+      r
+    end
+
+    def close_outgoing
+      r = ractor_outgoing_queue.closed?
+      ractor_outgoing_queue.close
+      r
+    end
+
+    private def receive
+      ractor_incoming_queue.pop
+    end
+
+    private def receive_if(&block)
+      raise ::ArgumentError, 'no block given' unless block
+      ractor_incoming_queue.pop(&block)
+    end
+
+    def [](key)
+      Ractor.current.ractor_locals[key]
+    end
+
+    def []=(key, value)
+      Ractor.current.ractor_locals[key] = value
+    end
+
+    # @api private
+    def ractor_locals
+      @ractor_locals ||= {}.compare_by_identity
+    end
+
+    class << self
+      def yield(value, move: false)
+        value = ractor_isolate(value, move)
+        current.ractor_outgoing_queue.push(value, ack: true)
+      rescue ::ClosedQueueError
+        raise ClosedError, 'The outgoing-port is already closed'
+      end
+
+      def receive
+        current.__send__(:receive)
+      end
+      alias_method :recv, :receive
+
+      def receive_if(&block)
+        current.__send__(:receive_if, &block)
+      end
+
+      def select(*ractors, yield_value: not_given = true, move: false)
+        cur = Ractor.current
+        queues = ractors.map do |r|
+          r == cur ? r.ractor_incoming_queue : r.ractor_outgoing_queue
+        end
+        if !not_given
+          out = current.ractor_outgoing_queue
+          yield_value = ractor_isolate(yield_value, move)
+        elsif ractors.empty?
+          raise ::ArgumentError, 'specify at least one ractor or `yield_value`'
+        end
+
+        while true # rubocop:disable Style/InfiniteLoop
+                    # Don't `loop`, in case of `ClosedError` (not that there should be any)
+          queues.each_with_index do |q, i|
+            q.pop_non_blocking do |val|
+              r = ractors[i]
+              return [r == cur ? :receive : r, val]
+            end
+          end
+
+          if out && out.num_waiting > 0
+            # Not quite atomic...
+            out.push(yield_value, ack: true)
+            return [:yield, nil]
+          end
+
+          sleep(0.001)
+        end
+      end
+
+      def make_shareable(obj)
+        return obj if ractor_check_shareability?(obj, true)
+
+        raise Ractor::Error, '#freeze does not freeze object correctly'
+      end
+
+      def shareable?(obj)
+        ractor_check_shareability?(obj, false)
+      end
+
+      def current
+        ::Thread.current.thread_variable_get(:backports_ractor) ||
+          ::Thread.current.thread_variable_set(:backports_ractor, ractor_find_current)
+      end
+
+      def count
+        ::ObjectSpace.each_object(Ractor).count(&:ractor_live?)
+      end
+
+      # @api private
+      def ractor_reset
+        ::ObjectSpace.each_object(Ractor).each do |r|
+          next if r == Ractor.current
+          next unless (th = r.ractor_thread)
+
+          th.kill
+          th.join
+        end
+        Ractor.current.ractor_incoming_queue.clear
+      end
+
+      # @api private
+      def ractor_next_id
+        @id ||= 0
+        @id += 1
+      end
+
+      attr_reader :main
+
+      private def ractor_init
+        @ractor_shareable = ::ObjectSpace::WeakMap.new
+        @main = Ractor.new { nil }
+        RactorThreadGroups[::ThreadGroup::Default] = @main
+      end
+
+      private def ractor_find_current
+        RactorThreadGroups[Thread.current.group]
+      end
+    end
+
+    # @api private
+    def ractor_live?
+      !defined?(@ractor_thread) || # May happen if `count` is called from another thread before `initialize` has completed
+        @ractor_thread.status
+    end
+
+    # @api private
+    attr_reader :ractor_outgoing_queue, :ractor_incoming_queue, :ractor_thread
+
+    ractor_init
+  end
+end