farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/internal/scheduler_lifecycle.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# Load worker dependencies before a scheduler is used from another Ractor.
+# Some concurrent autoload can lead to stalls on Windows with Ruby 3.4.
+require "farce/clock"
+require "farce/internal/thread_pool"
+require "farce/resolv"
+require "farce/resolv/dns"
+
+module Farce
+  module Internal
+    # Task admission, timers and shutdown shared by the scheduler implementations.
+    module SchedulerLifecycle
+      include Farce::Unshareable
+
+      # Prepending bypasses Unshareable's include hook, so remove freeze here.
+      def self.prepended(scheduler)
+        scheduler.undef_method(:freeze)
+      end
+
+      class Cancelled < Exception # rubocop:disable Lint/InheritException
+      end
+
+      Timer      = Struct.new(:deadline, :token, :fiber, :error, :active)
+      Completion = Struct.new(:token, :value, :error)
+      SLOT_COUNT = 64
+      private_constant :Timer, :Completion, :SLOT_COUNT
+
+      def initialize(backend: FROZEN_CONFIG.io_backend, thread_pool: ThreadPool.current)
+        super(backend: backend)
+        @owner           = owner_thread
+        @root            = Fiber.current
+        @fibers          = {}.compare_by_identity
+        @timers          = Internal::UnsharedPriorityQueue.new
+        @mailbox         = Thread::Queue.new
+        @thread_pool     = thread_pool
+        @closed          = @closing = @running = @stopping = false
+        @suspensions     = @immediate = 0
+        @dispatch_budget = dispatch_budget
+      rescue Exception # rubocop:disable Lint/RescueException
+        destroy
+        raise
+      end
+
+      def fiber(*, **, &work)
+        check_owner
+        raise IOError, "scheduler is closed" if @closed || @stopping
+        raise FiberError, "scheduler must be installed" unless Fiber.scheduler.equal?(self)
+        raise ArgumentError, "no block given" unless work
+        admitting = true
+        failure = nil
+        task = Fiber.new(blocking: false, storage: nil) do
+          work.call(*, **)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          raise unless admitting
+          failure = e
+        ensure
+          @fibers.delete(Fiber.current)
+          finish_fiber
+        end
+        @fibers[task] = true
+        start_fiber(task)
+        admitting = false
+        raise failure if failure
+        task
+      rescue Exception # rubocop:disable Lint/RescueException
+        shutdown if task && !@running && Fiber.current.equal?(@root)
+        raise
+      ensure
+        admitting = false
+      end
+
+      def block(_blocker, timeout = nil)
+        timeout = duration_value(timeout)
+        token = arm_wait
+        wait_with_timeout(token, timeout, false)
+      ensure
+        retire_wait(token) if token
+      end
+
+      def unblock(_blocker, fiber) # rubocop:disable Naming/PredicateMethod
+        return false if @closed || !(token = current_wait(fiber))
+        @mailbox << Completion.new(token, true, nil).freeze
+        wakeup
+        true
+      end
+
+      def fiber_interrupt(fiber, exception) # rubocop:disable Naming/PredicateMethod
+        return false if @closed || !(token = current_wait(fiber))
+        @mailbox << Completion.new(token, nil, exception).freeze
+        wakeup
+        true
+      end
+
+      def kernel_sleep(duration = nil)
+        started = Clock.now
+        block(nil, duration)
+        Clock.now - started
+      end
+
+      def timeout_after(duration, klass = Timeout::Error, *)
+        check_fiber
+        duration = duration_value(duration)
+        return yield(duration) unless duration
+        timer = Timer.new(Clock.now + duration, nil, Fiber.current, klass.exception(*), true)
+        @timers.push(timer.deadline, timer)
+        policy_changed
+        yield duration
+      ensure
+        remove_timer(timer) if timer
+      end
+
+      def yield
+        token = arm_wait
+        resume_wait(token, nil)
+        suspend(token)
+      end
+      alias cooperate yield
+
+      def address_resolve(hostname)
+        check_fiber
+        Resolv.getaddresses(hostname)
+      end
+
+      def process_wait(pid, flags)
+        background { Process::Status.wait(pid, flags) }
+      end
+
+      def blocking_operation_wait(operation)
+        # CRuby also invokes this hook from finalizers, where parking is illegal.
+        # Keep the opaque runtime operation on its original stack. Explicit file
+        # fallbacks use the thread pool. Process waits use separate threads.
+        Fiber.blocking { operation.call }
+      end
+
+      def run
+        check_root
+
+        raise IOError,    "scheduler is closed"     if @closed || @stopping
+        raise FiberError, "recursive scheduler run" if @running
+        entered = @running = true
+
+        Internal.prepare_thread if defined?(Internal.prepare_thread)
+
+        until idle?
+          service_policy
+          break if idle?
+          deadline = @timers.peek_priority
+          timeout = deadline ? deadline - Clock.now : nil
+          timeout = 0 if timeout&.negative? || ready? || !@mailbox.empty?
+          dispatch(timeout, @timers.empty? ? @dispatch_budget : 256)
+        end
+
+        true
+      rescue Exception # rubocop:disable Lint/RescueException
+        shutdown if entered
+        raise
+      ensure
+        if entered
+          @running = false
+          finish_close if @closing
+        end
+      end
+
+      def idle?       = @fibers.empty? && !pending? && @timers.empty? && @mailbox.empty?
+      def closed?     = @closed
+
+      # Return a lower bound for fibers that can resume immediately.
+      def farce_runnable_count = scheduler_ready_count + @mailbox.size
+
+      # Stop admission immediately. An active driver owns the drain and releases
+      # resources after returning from dispatch. Destroying them here would leave
+      # its native stack referring to freed state.
+      def close # rubocop:disable Naming/PredicateMethod
+        check_owner
+        return true if @closed
+        begin_close
+        @closing = true
+        return true if @running || !Fiber.current.equal?(@root)
+        begin
+          run unless @stopping
+        ensure
+          finish_close
+        end
+        true
+      end
+
+      # Ruby 3.4+ invokes this hook on scheduler replacement and thread exit.
+      def scheduler_close(error = $!) # rubocop:disable Style/SpecialGlobalVars
+        check_root
+        raise FiberError, "recursive scheduler close" if @running
+        return close unless error
+        # The root is already unwinding: run task ensures without waiting for
+        # ordinary completion, and preserve the exception that caused shutdown.
+        begin_close
+        @closing = true
+        finish_close
+        true
+      end
+
+      private
+
+      def finish_close
+        return if @closed
+        shutdown
+        destroy
+        @timers.clear
+        @mailbox.clear
+        @closed = true
+        @closing = false
+      end
+
+      def initialize_copy(*) = raise(TypeError, "fiber schedulers cannot be copied")
+      def marshal_dump = raise(TypeError, "fiber schedulers cannot be marshaled")
+
+      def check_owner
+        raise ThreadError, "scheduler belongs to another thread" unless owner_thread.equal?(@owner)
+      end
+
+      def check_root
+        check_owner
+        raise FiberError, "operation requires the root fiber" unless Fiber.current.equal?(@root)
+      end
+
+      def check_fiber
+        check_owner
+        raise IOError, "scheduler is closed" if @closed || @stopping
+        raise FiberError, "operation requires an admitted fiber" unless @fibers.key?(Fiber.current)
+        raise FiberError, "scheduler must be installed" unless @closing || Fiber.scheduler.equal?(self)
+      end
+
+      def duration_value(value)
+        return if value.nil?
+        seconds = Float(value)
+        raise ArgumentError, "invalid timeout" if seconds.nan? || seconds.negative?
+        seconds.finite? ? seconds : nil
+      end
+
+      def suspend(token)
+        @suspensions += 1
+        park_current(token)
+      end
+
+      def wait_with_timeout(token, timeout, value)
+        if timeout
+          timer = Timer.new(Clock.now + timeout, token, nil, nil, true)
+          @timers.push(timer.deadline, timer)
+          policy_changed
+        end
+        result = suspend(token)
+        result.nil? ? value : result
+      ensure
+        remove_timer(timer) if timer
+      end
+
+      def remove_timer(timer)
+        timer.active = false
+        @timers.delete_identity(timer.deadline, timer)
+      end
+
+      def with_io_timeout(duration, &)
+        timeout_after(duration, IO::TimeoutError, "IO timed out", &)
+      end
+
+      def checkpoint_result(value)
+        @immediate += 1
+        if @immediate >= SLOT_COUNT
+          @immediate = 0
+          self.yield
+        end
+        value
+      end
+
+      def service_policy
+        SLOT_COUNT.times do
+          break if @mailbox.empty?
+          item = @mailbox.pop(true)
+          break unless item
+          item.error ? interrupt_wait(item.token, item.error) : resume_wait(item.token, item.value)
+        end
+        return if @timers.empty?
+        SLOT_COUNT.times do
+          timer = @timers.pop_before(Clock.now)
+          break unless timer
+          next unless timer.active
+          timer.active = false
+          token = timer.token || current_wait(timer.fiber)
+          next unless token
+          timer.error ? interrupt_wait(token, timer.error) : resume_wait(token, nil)
+        end
+      end
+
+      def background(&)
+        check_fiber
+        @thread_pool.call(&)
+      end
+
+      def shutdown
+        begin_shutdown
+        @stopping = true
+        @fibers.keys.each do |task| # rubocop:disable Style/HashEachMethods
+          next unless task.alive?
+          begin
+            task.raise(Cancelled.new("scheduler aborted"))
+          rescue Exception # rubocop:disable Lint/RescueException
+            # Preserve the initiating failure, while running other tasks' ensures.
+          end
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/select_scheduler.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Ruby scheduler built around IO.select. Engine implementations can override its IO helpers.
+    module SelectScheduler
+      include SchedulerIO
+
+      Wait = Struct.new(:fiber, :status, :value, :error, :groups, :ios)
+      private_constant :Wait
+
+      attr_reader :backend, :fallback_reason
+
+      def initialize(backend: :auto)
+        raise ArgumentError, "unavailable select driver: #{backend}" unless %i[auto select].include?(backend)
+        @backend = :select
+        @wait_mutex = Thread::Mutex.new
+        @waits = {}
+        @waiting = {}.compare_by_identity
+        @ready = []
+        @serial = 0
+        @wake_reader, @wake_writer = IO.pipe
+      end
+
+      def io_wait(io, events, timeout = nil)
+        check_fiber
+        events = Integer(events)
+        raise ArgumentError, "invalid IO event mask" unless events.positive? && events.nobits?(~7)
+        readiness(io_select(events.nobits?(IO::READABLE) ? nil : [io],
+          events.nobits?(IO::WRITABLE) ? nil : [io], events.nobits?(IO::PRIORITY) ? nil : [io], timeout))
+      end
+
+      if SINGLE_TRANSFER
+        def io_read(io, buffer, offset, length)
+          transfer_io(false, io, buffer, length, offset, single_transfer: true)
+        end
+
+        def io_write(io, buffer, offset, length)
+          transfer_io(true, io, buffer, length, offset, single_transfer: true)
+        end
+      else
+        def io_read(io, buffer, minimum, offset = 0)
+          transfer_io(false, io, buffer, minimum, offset)
+        end
+
+        def io_write(io, buffer, minimum, offset = 0)
+          transfer_io(true, io, buffer, minimum, offset)
+        end
+      end
+
+      def io_close(descriptor) # rubocop:disable Naming/PredicateMethod
+        check_owner
+        cancel_descriptor(descriptor)
+        Fiber.blocking { IO.for_fd(descriptor).close }
+        true
+      end
+
+      private
+
+      def arm_wait
+        check_fiber
+        @wait_mutex.synchronize do
+          token = @serial += 1
+          @waits[token] = Wait.new(Fiber.current, :pending)
+          @waiting[Fiber.current] = token
+          token
+        end
+      end
+
+      def current_wait(fiber)
+        @wait_mutex.synchronize { @waiting[fiber] }
+      end
+
+      def register_select(token, groups, ios)
+        wait = @waits.fetch(token)
+        wait.groups, wait.ios = groups, ios
+      end
+
+      def park_current(token)
+        Fiber.yield
+        wait = @waits.fetch(token)
+        raise wait.error if wait.error
+        wait.value
+      ensure
+        retire_wait(token)
+      end
+
+      def resume_wait(token, value, error = nil)
+        @wait_mutex.synchronize do
+          wait = @waits[token]
+          return false unless wait && wait.status == :pending
+          wait.status, wait.value, wait.error = :ready, value, error
+          @ready << token
+          true
+        end
+      end
+
+      def interrupt_wait(token, error)
+        # An interrupt may replace an undispatched result, but never a later wait.
+        @wait_mutex.synchronize do
+          wait = @waits[token]
+          return false unless wait
+          @ready << token if wait.status == :pending
+          wait.status, wait.error = :ready, error
+          true
+        end
+      end
+
+      def retire_wait(token)
+        @wait_mutex.synchronize do
+          wait = @waits.delete(token)
+          @waiting.delete(wait.fiber) if wait && @waiting[wait.fiber] == token
+        end
+      end
+
+      def ready? = !@ready.empty?
+      def scheduler_ready_count = @ready.size
+      def pending? = !@waits.empty?
+      def pending_count = @wait_mutex.synchronize { @waits.size }
+
+      def write_wakeup = @wake_writer.write_nonblock(".", exception: false)
+      def read_wakeup = @wake_reader.read_nonblock(4096, exception: false)
+
+      def wakeup
+        write_wakeup
+        true
+      rescue IOError, SystemCallError
+        false
+      end
+
+      def dispatch(timeout, budget)
+        check_root
+        snapshot = @waits.to_a.select { |_, wait| wait.status == :pending && wait.groups }
+        groups = [[@wake_reader], [], []]
+        snapshot.each do |token, wait|
+          if wait.ios.flatten.any?(&:closed?)
+            interrupt_wait(token, IOError.new("stream closed while waiting"))
+          else
+            3.times { |i| groups[i].concat(wait.ios[i]) }
+          end
+        end
+        # Linux select may keep sleeping after another thread closes an IO.
+        timeout = [timeout || 0.05, 0.05].min unless snapshot.empty?
+        begin
+          found = select_snapshot(groups.map(&:uniq), ready? ? 0 : timeout)
+        rescue IOError, Errno::EBADF, Errno::ENOTSOCK
+          closed = snapshot.select { |_, wait| wait.ios.flatten.any?(&:closed?) }
+          raise if closed.empty?
+          closed.each { |token, _| interrupt_wait(token, IOError.new("stream closed while waiting")) } # rubocop:disable Style/HashEachMethods -- snapshot is an Array
+        end
+        if found
+          if found[0].delete(@wake_reader)
+            loop { break unless read_wakeup.is_a?(String) }
+          end
+          sets = found.map { |list| list.each_with_object({}.compare_by_identity) { |io, set| set[io] = true } }
+          snapshot.each do |token, wait|
+            next unless @waits[token].equal?(wait) && wait.status == :pending
+            result = wait.groups.each_with_index.map do |list, i|
+              list.each_with_index.filter_map { |object, j| object if sets[i][wait.ios[i][j]] }
+            end
+            resume_wait(token, result) if result.any? { |list| !list.empty? }
+          end
+        end
+        count = 0
+        budget.times do
+          token = @ready.shift
+          break unless token
+          wait = @waits[token]
+          next unless wait && wait.status == :ready
+          wait.status = :delivered
+          wait.fiber.resume
+          count += 1
+        end
+        count
+      rescue Errno::EINTR
+        0
+      end
+
+      def cancel_descriptor(descriptor)
+        @waits.each do |token, wait|
+          next unless wait.ios&.flatten&.any? { |io| !io.closed? && io.fileno == descriptor }
+          interrupt_wait(token, IOError.new("stream closed while waiting"))
+        end
+      end
+
+      def destroy
+        @wake_reader.close if @wake_reader && !@wake_reader.closed?
+        @wake_writer.close if @wake_writer && !@wake_writer.closed?
+        @waits&.clear
+        @waiting&.clear
+        @ready&.clear
+      end
+
+      def transfer_nonblock(writing, io, buffer, offset, capacity)
+        writing ? io.write_nonblock(buffer.get_string(offset, capacity), exception: false) :
+          io.read_nonblock(capacity, exception: false)
+      end
+
+      def transfer_io(writing, io, buffer, minimum, offset, single_transfer: false)
+        io, minimum, offset = transfer_arguments(io, buffer, minimum, offset, writing)
+        limit = single_transfer ? minimum : buffer.size - offset
+        minimum = limit.zero? ? 0 : 1 if single_transfer
+        serial = @suspensions
+        result = locked_buffer(buffer) do
+          operation = lambda do |*_ignored|
+            next file_transfer(writing, io, buffer, minimum, offset, limit) if io.stat.file?
+            total = 0
+            loop do
+              capacity = limit - total
+              break total if capacity.zero?
+              value = Fiber.blocking do
+                transfer_nonblock(writing, io, buffer, offset + total, capacity)
+              end
+              if value == :wait_readable || value == :wait_writable
+                io_wait(io, value == :wait_readable ? IO::READABLE : IO::WRITABLE)
+                next
+              end
+              break total if value.nil? || value == 0 # rubocop:disable Style/NumericPredicate -- reads return strings, writes integers
+              buffer.set_string(value, offset + total) unless writing
+              total += writing ? value : value.bytesize
+              break total if total >= minimum
+            end
+          rescue SystemCallError => e
+            total&.positive? ? total : -e.errno
+          end
+          io.respond_to?(:timeout) && io.timeout ? with_io_timeout(io.timeout, &operation) : operation.call
+        end
+        checkpoint_result(result) if serial == @suspensions
+        result
+      end
+    end
+  end
+end

data/lib/farce/internal/storage.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Storage
+      # Protect shared map access, including reads on engines with unsafe weak maps.
+      # Per-key locks let initializers for unrelated keys run independently.
+      class ThreadSafe < Storage
+        def initialize
+          @strong_locks = {}
+          @weak_locks   = ObjectSpace::WeakKeyMap.new
+          super
+        end
+
+        def [](key, positional_mode = nil, mode: :auto)
+          map = map_for(key, positional_mode || mode, create: false)
+          @mutex.synchronize { map[key] } if map
+        end
+
+        def []=(key, mode = :auto, value) # rubocop:disable Style/OptionalArguments
+          map = map_for(key, mode)
+          @mutex.synchronize { map[key] = value }
+        end
+
+        def key?(key, mode = :auto)
+          map = map_for(key, mode, create: false)
+          map ? @mutex.synchronize { map.key?(key) } : false
+        end
+
+        def store_if_absent(key, mode: :auto)
+          value = self[key, mode]
+          return value unless value.nil?
+
+          mutex_map = Internal.garbage_collectable?(key) ? @weak_locks : @strong_locks
+          mutex     = @mutex.synchronize { mutex_map[key] ||= Mutex.new }
+
+          mutex.synchronize do
+            self[key, mode] = yield unless key?(key, mode)
+            self[key, mode]
+          end
+        end
+      end
+
+      def self.[](key, scope: :ractor, **) = scope(scope)[key, **]
+
+      def self.[]=(key, scope = :ractor, mode = :auto, value) # rubocop:disable Style/OptionalArguments
+        scope(scope)[key, mode] = value
+      end
+
+      def self.dig(*, scope: :ractor, **) = scope(scope).dig(*, **)
+
+      def self.store_if_absent(key, scope: :ractor, **, &) = scope(scope).store_if_absent(key, **, &)
+
+      def self.scope(scope, raise_exception: true)
+        case scope
+        when :global
+          raise ArgumentError, "global scope is not supported" if raise_exception
+        when Symbol
+          return __send__(scope) if Farce::SCOPES.include?(scope)
+          return unless raise_exception
+          raise ArgumentError, "Invalid scope: #{scope.inspect}"
+        when Class
+          storage = scope(scope.name.downcase.to_sym, raise_exception: false)
+          return storage if storage
+          raise ArgumentError, "Invalid scope: #{scope.inspect}" if raise_exception
+        when Storage
+          scope
+        else
+          raise ArgumentError, "Invalid scope: #{scope.inspect}" if raise_exception
+        end
+      end
+
+      def self.ractor
+        return MAIN_STORAGE if Ractor.main?
+        Ractor.store_if_absent(name) { ThreadSafe.new }
+      end
+
+      def self.thread_group(thread = Thread.current)
+        group    = thread.is_a?(ThreadGroup) ? thread : thread.group
+        by_group = ractor.store_if_absent(:thread_groups) { ThreadSafe.new }
+        by_group.store_if_absent(group) { ThreadSafe.new }
+      end
+
+      def self.thread(thread = Thread.current)
+        thread    = Internal.storage_thread(thread)
+        root      = Internal.native_ractors? ? ractor : MAIN_STORAGE
+        by_thread = root.store_if_absent(:threads) { ThreadSafe.new }
+        by_thread.store_if_absent(thread) { Storage.new }
+      end
+
+      def self.fiber_storage = Fiber[name] ||= Storage.new
+
+      def self.fiber(fiber = Fiber.current)
+        by_fiber = ractor.store_if_absent(:fibers) { ThreadSafe.new }
+        by_fiber.store_if_absent(fiber) { Storage.new }
+      end
+
+      def initialize
+        @mutex  = Mutex.new
+        @strong = nil
+        @weak   = nil
+      end
+
+      def [](key, positional_mode = nil, mode: :auto)
+        map = map_for(key, positional_mode || mode, create: false)
+        map[key] if map
+      end
+
+      def []=(key, mode = :auto, value) # rubocop:disable Style/OptionalArguments
+        map_for(key, mode)[key] = value
+      end
+
+      def key?(key, mode = :auto) = map_for(key, mode, create: false)&.key?(key)
+
+      def store_if_absent(key, mode: :auto)
+        map = map_for(key, mode)
+        map[key] = yield unless map.key?(key)
+        map[key]
+      end
+
+      def dig(key, *keys, mode: :auto)
+        value = self[key, mode]
+        keys.empty? ? value : value&.dig(*keys)
+      end
+
+      def clear
+        @mutex.synchronize do
+          @strong&.clear
+          @weak&.clear
+        end
+      end
+
+      private
+
+      def strong(create: true)
+        return @strong unless create && !@strong
+        @mutex.synchronize { @strong ||= {} }
+      end
+
+      def weak(create: true)
+        return @weak unless create && !@weak
+        @mutex.synchronize { @weak ||= ObjectSpace::WeakKeyMap.new }
+      end
+
+      def map_for(key, mode, **)
+        case mode
+        when :auto   then return strong(**) if key.instance_of?(String)
+        when :strong then return strong(**)
+        when :weak # no-op
+        else raise ArgumentError, "Invalid mode: #{mode.inspect}"
+        end
+        Internal.garbage_collectable?(key) ? weak(**) : strong(**)
+      end
+    end
+
+    # shareable_constant_value: none
+    MAIN_STORAGE = Storage::ThreadSafe.new
+  end
+end