farce 0 → 0.1.0

data/lib/farce/queue.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A shareable FIFO queue with transfer modes for unshareable values.
+  class Queue < Farce::Abstract::Queue
+    include Internal::ManagedQueue
+    include Shareable::Unfreezable
+
+    # (see Farce::Abstract::Queue#initialize)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def initialize(capacity: 1024, mode: :copy, track_age: false)
+      @manager = ModeManager.new(mode:)
+      @queue = Internal::Queue.new(capacity:, track_age:)
+      super()
+    end
+
+    # (see Farce::Abstract::Queue#push)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def push(value, non_block = false, timeout: nil, mode: nil) # rubocop:disable Style/OptionalBooleanParameter
+      value = @manager.wrap(value, mode:)
+
+      if non_block
+        return true if @queue.try_push(value)
+        raise ThreadError, "queue full"
+      end
+
+      timeout.nil? ? @queue.push(value) : @queue.push(value, timeout:)
+    end
+
+    # (see Farce::Abstract::Queue#try_push)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def try_push(value, mode: nil)
+      return true if @queue.try_push(@manager.wrap(value, mode:))
+      block_given? ? yield : false
+    end
+
+    # (see Farce::Abstract::Queue#pop)
+    def pop(non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+      return try_pop { raise ThreadError, "queue empty" } if non_block
+
+      empty = false
+      result = timeout.nil? ? @queue.pop { empty = true } : @queue.pop(timeout:) { empty = true }
+      return @manager.unwrap(result) unless empty
+      yield if block_given?
+    end
+
+    # (see Farce::Abstract::Queue#try_pop)
+    def try_pop
+      empty = false
+      result = @queue.try_pop { empty = true }
+      return @manager.unwrap(result) unless empty
+      yield if block_given?
+    end
+  end
+end

data/lib/farce/ractor.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Entry point for Ractor support.
+  #
+  # This is always a module, but if native Ractor support is available:
+  # * It gets mixed into Ractor. This has no effect beyond another entry in the inheritance chain,
+  #   so `is_a?(Farce::Ractor)` and `Farce::Ractor === ractor` work as expected.
+  # * It delegates, wraps, or backports known Ractor class methods.
+  #
+  # If not, then this module provides a polyfill for Ractors. With the following caveats:
+  # * It uses thread groups to keep track of Thread-to-Ractor associations.
+  # * All objects are considered shareable.
+  # * It does not monkey-patch `Thread`. This means in particular:
+  #   * `Thread.list` will include all threads from all Ractors.
+  #     Use {.threads Farce::Ractor.threads} instead.
+  #   * `Thread.main` will return the main thread of the main Ractor, even if called from a different Ractor.
+  #     Use {.main_thread Farce::Ractor.main_thread} instead.
+  #
+  # @!method [](key)
+  #   @!scope class
+  #   Retrieves a value from the current Ractor's storage by key.
+  #   @param key [Symbol] The key to retrieve.
+  #   @return [BasicObject, nil] The value associated with the key, or `nil` if not found.
+  #
+  # @!method []=(key, value)
+  #   @!scope class
+  #   Stores a value in the current Ractor's storage by key.
+  #   @param key [Symbol] The key to store the value under.
+  #   @param value [BasicObject] The value to store.
+  #
+  # @!method builtin?
+  #   @!scope class
+  #   @note This method isn't part of the official Ractor API, but is compatible with the `ractor-shim` gem.
+  #   @return [Boolean] `true` if native Ractors are available, `false` otherwise.
+  #
+  # @!method count
+  #   @!scope class
+  #   Returns the number of Ractors.
+  #   @return [Integer] The number of Ractors.
+  #
+  # @!method current
+  #   @!scope class
+  #   Returns the current Ractor instance.
+  #   @return [Ractor] The current Ractor instance.
+  #
+  # @!method main
+  #   @!scope class
+  #   Returns the main Ractor instance.
+  #   @return [Ractor] The main Ractor instance.
+  #
+  # @!method make_shareable(object, copy: false)
+  #   @!scope class
+  #   @note If native Ractors aren't available, this method simply returns the object, as all objects are shareable.
+  #   Makes an object shareable between Ractors.
+  #   @param object [BasicObject] The object to make shareable.
+  #   @param copy [Boolean] Whether to create a copy of the object.
+  #   @return [BasicObject] The shareable object.
+  #
+  # @!method main?
+  #   @!scope class
+  #   Checks if the current Ractor is the main Ractor.
+  #   @return [Boolean] `true` if the current Ractor is the main Ractor, `false` otherwise.
+  #
+  # @!method main_thread
+  #   @!scope class
+  #   @note This method is not part of the official Ractor API, but is a replacement for a Ractor-unaware `Thread.main`.
+  #   Returns the main thread of the current Ractor.
+  #   @return [Thread] The main thread of the current Ractor.
+  #
+  # @!method new(*args, name: nil)
+  #   @!scope class
+  #   Creates a new Ractor instance.
+  #   @param args [Array] The arguments to pass to the Ractor's block. Will be copied if not {.shareable? shareable}.
+  #   @param name [String, nil] The name of the Ractor, or `nil` for no name.
+  #   @yield [*args] The block to execute in the new Ractor.
+  #   @yieldparam args [Array] The arguments passed to the Ractor.
+  #   @yieldreturn [BasicObject] The {#value value} returned by the Ractor's block.
+  #   @yieldreceiver [Ractor] The new Ractor instance.
+  #   @return [Ractor] The new Ractor instance.
+  #
+  # @!method receive(timeout: nil)
+  #   @!scope class
+  #   Receives a message on the current Ractor's {#default_port default port}.
+  #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+  #   @return [BasicObject, nil] The received message, or `nil` if the timeout has been reached.
+  #
+  # @!method select(*ractors_or_ports, timeout: nil)
+  #   @!scope class
+  #   Blocks the current Thread until one of the given Ractors or Ports produces a value, or until the timeout
+  #   has been reached.
+  #
+  #   Returns an array containing the Ractor or Port that produced the value, and the value itself.
+  #   Or `nil` if the timeout has been reached.
+  #
+  #   @param ractors_or_ports [Array<Ractor, Farce::Abstract::Port>] The Ractors or Ports to select from.
+  #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+  #   @return [Array(Object, BasicObject), nil]
+  #     An array containing the Ractor or Port that produced the value, and the value itself,
+  #     or `nil` if the timeout has been reached.
+  #
+  # @!method shareable?(object)
+  #   @!scope class
+  #   @note If native Ractors aren't available, this method always returns `true`, as all objects are shareable.
+  #   Checks if an object is shareable between Ractors.
+  #   @param object [BasicObject] The object to check.
+  #   @return [Boolean] `true` if the object is shareable, `false` otherwise.
+  #
+  # @!method shareable_lambda(self: nil)
+  #   @!scope class
+  #   {Farce.rebind Binds} a lambda to the given `self` and {.make_shareable makes it shareable} between Ractors.
+  #   @yield The block to convert into a shareable lambda.
+  #   @yieldreceiver [BasicObject] The object passed as `self` (or `nil`)
+  #   @param self [BasicObject] The object to bind as `self`.
+  #   @return [Proc] The shareable lambda.
+  #   @see .shareable_proc
+  #
+  # @!method shareable_proc(self: nil)
+  #   @!scope class
+  #   {Farce.rebind Binds} a proc to the given `self` and {.make_shareable makes it shareable} between Ractors.
+  #   @yield The block to convert into a shareable proc.
+  #   @yieldreceiver [BasicObject] The object passed as `self` (or `nil`)
+  #   @param self [BasicObject] The object to bind as `self`.
+  #   @return [Proc] The shareable proc.
+  #   @see .shareable_lambda
+  #
+  # @!method shim?
+  #   @!scope class
+  #   @note This method isn't part of the official Ractor API, but is compatible with the `ractor-shim` gem.
+  #   @return [Boolean] `false` if native Ractors are available, `true` otherwise.
+  #
+  # @!method store_if_absent(key)
+  #   @!scope class
+  #   Stores a value in the current Ractor's storage by key if it is not already present. This method is thread-safe.
+  #   @param key [Symbol] The key to store the value under.
+  #   @yield Block that computes the value to store if the key is absent.
+  #   @yieldreturn [BasicObject] The value to store if the key is absent.
+  #   @return [BasicObject] The existing or newly stored value.
+  #
+  # @!method threads
+  #   @!scope class
+  #   @note This method isn't part of the official Ractor API, but is a replacement for a Ractor-unaware `Thread.list`.
+  #   Returns the list of threads in the current Ractor.
+  #   @return [Array<Thread>] The list of threads in the current Ractor.
+  #
+  # @!method default_port
+  #   @return [Ractor::Port] The default port for the Ractor.
+  #
+  # @!method join
+  #   Blocks the current Thread until the Ractor has terminated.
+  #   @return [self]
+  #
+  # @!method main?
+  #   @return [Boolean] `true` if the Ractor is the main Ractor
+  #
+  # @!method monitor(port)
+  #   Monitors the given port for termination of the Ractor. If the Ractor is already terminated, the port will receive
+  #   the Ractor's status immediately. The port will receive wither `:exited` or `:aborted` depending on whether the
+  #   Ractor terminated normally or with an unhandled exception.
+  #   @ruby CRuby 4.0+, JRuby, TruffleRuby
+  #   @param port [Ractor::Port] The port to monitor.
+  #   @return [Boolean]
+  #     `true` if the Ractor is running and the port was successfully monitored,
+  #     `false` if the Ractor is already terminated and the port received the Ractor's status.
+  #   @see #unmonitor
+  #
+  # @!method unmonitor(port)
+  #   Stops monitoring the given port for termination of the Ractor. If the port was not being monitored, this method
+  #   has no effect.
+  #   @ruby CRuby 4.0+, JRuby, TruffleRuby
+  #   @return [self]
+  #   @see #monitor
+  #
+  # @!method name
+  #   @return [String, nil] The name of the Ractor, or `nil` if it has no name.
+  #
+  # @!method receive(timeout: nil)
+  #   Receives a message on the Ractor's {#default_port default port}.
+  #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+  #   @return [BasicObject, nil] The received message, or `nil` if the timeout has been reached.
+  #
+  # @!method send(message, move: false)
+  #   Sends a message to the Ractor's {#default_port default port}.
+  #   @param message [BasicObject] The message to send.
+  #   @param move [Boolean] Whether to move the message to the Ractor if it isn't sharable.
+  #   @return [self]
+  #
+  # @!method name
+  #   @return [String, nil] The name of the Ractor, or `nil` if it has no name.
+  #
+  # @!method receive(timeout: nil)
+  #   Receives a message on the Ractor's {#default_port default port}.
+  #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+  #   @return [BasicObject, nil] The received message, or `nil` if the timeout has been reached.
+  #
+  # @!method send(message, move: false)
+  #   Sends a message to the Ractor's {#default_port default port}.
+  #   @param message [BasicObject] The message to send.
+  #   @param move [Boolean] Whether to move the message to the Ractor if it isn't sharable.
+  #   @return [self]
+  #
+  # @!method value
+  #   Blocks the current Thread until the Ractor has terminated, and returns the value returned by the
+  #   Ractor's block. Will re-raise any unhandled exception raised in the Ractor's block.
+  #   @ruby CRuby 4.0+, JRuby, TruffleRuby
+  #   @return [BasicObject] The value returned by the Ractor's block.
+  #
+  # @!method take
+  #   @deprecated
+  #     This method only exists on CRuby 3.x (outdated Ractor API). Use {#value} if you don't have to support
+  #     CRuby 3.x, or use {Farce::Port}.
+  #   Receives a message from the Ractor. This may be the ractor's return value.
+  #   @ruby CRuby 3.x
+  #   @return [BasicObject] The received message.
+  module Ractor
+    include Internal::MarshalSupport::Reject
+    ::Ractor.include(self) if Internal.native_ractors?
+
+    # @!parse
+    #   # @!scope class
+    #   alias recv receive
+    #   alias recv receive
+    #   alias << send
+
+    # Either `Ractor::Error` or a subclass of `RuntimeError` if native Ractors are not available.
+    # @!macro RactorError_note
+    #   Will pick up an error class defined by a shim/polyfill if one is loaded,
+    #   like [ractor-shim](https://github.com/eregon/ractor-shim).
+    Error = defined?(::Ractor::Error) ? ::Ractor::Error : Class.new(RuntimeError)
+
+    # Either `Ractor::ClosedError` or a subclass of `StopIteration` if native Ractors are not available.
+    # @!macro RactorError_note
+    ClosedError = defined?(::Ractor::ClosedError) ? ::Ractor::ClosedError : Class.new(StopIteration)
+
+    # Either `Ractor::IsolationError` or a subclass of {Error} if native Ractors are not available.
+    # @!macro RactorError_note
+    IsolationError = defined?(::Ractor::IsolationError) ? ::Ractor::IsolationError : Class.new(Error)
+
+    # Either `Ractor::MovedError` or a subclass of {Error} if native Ractors are not available.
+    # @!macro RactorError_note
+    MovedError = defined?(::Ractor::MovedError) ? ::Ractor::MovedError : Class.new(Error)
+
+    # Either `Ractor::RemoteError` or a subclass of {Error} if native Ractors are not available.
+    # @!macro RactorError_note
+    RemoteError = defined?(::Ractor::RemoteError) ? ::Ractor::RemoteError : Class.new(Error)
+
+    # Either `Ractor::UnsafeError` or a subclass of {Error} if native Ractors are not available.
+    # @!macro RactorError_note
+    UnsafeError = defined?(::Ractor::UnsafeError) ? ::Ractor::UnsafeError : Class.new(Error)
+
+    # Either `Ractor::MovedObject` or a subclass of `BasicObject` if native Ractors are not available.
+    # Cannot be instantiated directly, but can be used to check if an object has been moved to another Ractor.
+    MovedObject = defined?(::Ractor::MovedObject) ? ::Ractor::MovedObject :
+      Class.new(BasicObject) { def self.new(...) = raise TypeError, "allocator undefined for #{inspect}" }
+
+    extend Internal::RactorMethods
+
+    def self.const_missing(name) = name == :Port ? Internal::BasePort : super
+    private_class_method :const_missing
+
+    # @!visibility private
+    def self.included(base)
+      return if base.const_defined?(:Port, false)
+      base.const_set(:Port, Internal::BasePort)
+    end
+  end
+end

data/lib/farce/read_write_lock.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable read/write lock with fiber-scheduler-aware waiting.
+  #
+  # Multiple execution contexts may hold the read lock concurrently. The write
+  # lock is exclusive and may be acquired while the current context holds a
+  # read lock. One concurrent upgrader retains its read lock continuously.
+  # Additional upgraders yield their read slot to avoid deadlock and restore it
+  # before returning to the outer read-lock block.
+  class ReadWriteLock
+    include Internal::MarshalSupport::Reject
+    include Internal::Copyable
+    include Shareable::Unfreezable
+
+    READER_BITS   = 30
+    READER_MASK   = (1 << READER_BITS) - 1
+    WRITER_BIT    = 1 << READER_BITS
+    UPGRADER_BIT  = 1 << (READER_BITS + 1)
+    WAITER_UNIT   = 1 << (READER_BITS + 2)
+    MAX_WAITERS   = ((1 << 63) - 1) / WAITER_UNIT
+    READ_DEPTH    = 0
+    WRITE_DEPTH   = 1
+    LOCAL_STATES  = :__farce_read_write_lock_states__
+    INTERRUPTS_IMMEDIATE = { Exception => :immediate }.freeze
+    private_constant :READER_BITS, :READER_MASK, :WRITER_BIT, :UPGRADER_BIT,
+      :WAITER_UNIT, :MAX_WAITERS, :READ_DEPTH, :WRITE_DEPTH, :LOCAL_STATES,
+      :INTERRUPTS_IMMEDIATE
+
+    def initialize
+      @state  = Internal::Vector.new([0])
+      @signal = Internal::Signal.new
+      super
+    end
+
+    # Runs the block while holding a shared read lock.
+    #
+    # @yield the block to run while holding the read lock
+    # @return [Object] the block result
+    def with_read_lock
+      raise LocalJumpError, "no block given" unless block_given?
+
+      local = local_state
+      Thread.handle_interrupt(Internal::INTERRUPT_MASK) do
+        global = local[READ_DEPTH].zero? && local[WRITE_DEPTH].zero?
+        acquire_read_lock if global
+        local[READ_DEPTH] += 1
+
+        begin
+          # Block capture allocates on every lock operation.
+          # rubocop:disable-next Style/ExplicitBlockArgument
+          Thread.handle_interrupt(INTERRUPTS_IMMEDIATE) { yield }
+        ensure
+          local[READ_DEPTH] -= 1
+          release_read_lock if global
+          clear_local_state(local)
+        end
+      end
+    end
+
+    # Runs the block while holding an exclusive write lock.
+    #
+    # Calling this method from inside {#with_read_lock} upgrades the read lock.
+    #
+    # @yield the block to run while holding the write lock
+    # @return [Object] the block result
+    def with_write_lock
+      raise LocalJumpError, "no block given" unless block_given?
+
+      local = local_state
+      Thread.handle_interrupt(Internal::INTERRUPT_MASK) do
+        reentrant = local[WRITE_DEPTH].positive?
+        upgraded  = !reentrant && local[READ_DEPTH].positive?
+        acquire_write_lock(upgraded) unless reentrant
+        local[WRITE_DEPTH] += 1
+
+        begin
+          # Block capture allocates on every lock operation.
+          # rubocop:disable-next Style/ExplicitBlockArgument
+          Thread.handle_interrupt(INTERRUPTS_IMMEDIATE) { yield }
+        ensure
+          local[WRITE_DEPTH] -= 1
+          unless reentrant
+            upgraded ? downgrade_write_lock : release_write_lock
+          end
+          clear_local_state(local)
+        end
+      end
+    end
+
+    private
+
+    def initialize_copy(other)
+      super
+      @state  = Internal::Vector.new([0])
+      @signal = Internal::Signal.new
+    end
+
+    def local_state
+      states = Thread.current[LOCAL_STATES] ||= {}
+      states[self] ||= [0, 0]
+    end
+
+    def clear_local_state(local)
+      return unless local[READ_DEPTH].zero? && local[WRITE_DEPTH].zero?
+
+      states = Thread.current[LOCAL_STATES]
+      states.delete(self)
+      Thread.current[LOCAL_STATES] = nil if states.empty?
+    end
+
+    def acquire_read_lock
+      return if try_acquire_read_lock
+
+      # Kernel.loop allocates on every acquisition.
+      while true
+        generation = @signal.generation
+        return if try_acquire_read_lock
+
+        wait_for_change(generation)
+      end
+    end
+
+    def try_acquire_read_lock
+      change_state do |current|
+        if readers_allowed?(current)
+          raise ThreadError, "maximum reader count exceeded" if reader_count(current) == READER_MASK
+          [current + 1, true]
+        else
+          [current, false]
+        end
+      end
+    end
+
+    def release_read_lock
+      change_state do |current|
+        raise ThreadError, "read lock is not held" if reader_count(current).zero?
+        [current - 1, nil]
+      end
+      @signal.broadcast
+    end
+
+    def acquire_write_lock(upgrade)
+      mode = upgrade ? register_upgrade : register_writer
+      acquired = false
+
+      begin
+        acquired = try_acquire_write_lock(mode)
+        return if acquired
+
+        # Kernel.loop allocates on every acquisition.
+        while true
+          generation = @signal.generation
+          acquired = try_acquire_write_lock(mode)
+          return if acquired
+
+          wait_for_change(generation)
+        end
+      ensure
+        cancel_write_request(mode) unless acquired
+      end
+    end
+
+    def try_acquire_write_lock(mode)
+      change_state do |current|
+        retained = mode == :retained
+        target_readers = retained ? 1 : 0
+        available = !writer_locked?(current) && reader_count(current) == target_readers
+        available &&= upgrader?(current) if retained
+
+        if available
+          replacement = current - WAITER_UNIT + WRITER_BIT
+          replacement -= UPGRADER_BIT + 1 if retained
+          [replacement, true]
+        else
+          [current, false]
+        end
+      end
+    end
+
+    def register_writer
+      change_state { |current| [add_waiter(current), :writer] }
+    end
+
+    def register_upgrade
+      mode = change_state do |current|
+        raise ThreadError, "read lock is not held" if reader_count(current).zero?
+
+        if upgrader?(current)
+          [add_waiter(current) - 1, :released]
+        else
+          [add_waiter(current) + UPGRADER_BIT, :retained]
+        end
+      end
+      @signal.broadcast if mode == :released
+      mode
+    end
+
+    def cancel_write_request(mode)
+      case mode
+      when :retained
+        change_state { |current| [current - WAITER_UNIT - UPGRADER_BIT, nil] }
+      when :released, :writer
+        change_state { |current| [current - WAITER_UNIT, nil] }
+      end
+      @signal.broadcast
+      acquire_read_lock if mode == :released
+    end
+
+    def release_write_lock
+      change_state do |current|
+        raise ThreadError, "write lock is not held" unless writer_locked?(current)
+        [current - WRITER_BIT, nil]
+      end
+      @signal.broadcast
+    end
+
+    def downgrade_write_lock
+      change_state do |current|
+        raise ThreadError, "write lock is not held" unless writer_locked?(current)
+        [current - WRITER_BIT + 1, nil]
+      end
+      @signal.broadcast
+    end
+
+    def change_state
+      result = nil
+      @state.update(0) do |current|
+        replacement, result = yield(current)
+        replacement
+      end
+      result
+    end
+
+    def wait_for_change(generation)
+      Thread.handle_interrupt(INTERRUPTS_IMMEDIATE) { @signal.wait(generation) }
+    end
+
+    def add_waiter(current)
+      raise ThreadError, "maximum writer count exceeded" if waiting_writers(current) == MAX_WAITERS
+      current + WAITER_UNIT
+    end
+
+    def readers_allowed?(current)
+      !writer_locked?(current) && waiting_writers(current).zero?
+    end
+
+    def reader_count(current)         = current & READER_MASK
+    def waiting_writers(current)      = current / WAITER_UNIT
+    def writer_locked?(current)       = current.anybits?(WRITER_BIT)
+    def upgrader?(current)            = current.anybits?(UPGRADER_BIT)
+    def instance_variables_to_inspect = Internal::EMPTY_ARRAY
+  end
+end