farce 0.3.0-java → 0.4.0-java

data/lib/farce/engine/shared/port.rb

@@ -10,11 +10,19 @@ module Farce
       include MarshalSupport::Reject
       include Freeze::Unfreezable
 
-      def initialize = @queue = Thread::Queue.new
-      def closed?    = @queue.closed?
+      def initialize
+        @queue          = Thread::Queue.new
+        @select_mutex   = Mutex.new
+        @select_waiters = []
+      end
+
+      def closed? = @queue.closed?
 
       def close
-        @queue.close
+        @select_mutex.synchronize do
+          @queue.close
+          @select_waiters.each(&:broadcast)
+        end
         self
       end
 
@@ -29,14 +37,44 @@ module Farce
           raise Ractor::Error, "can not move #{value.class} object" unless value.is_a?(Unshareable::Movable)
         end
         @queue.push(value)
+        notify_selectors
         self
       rescue ::ClosedQueueError
         raise Ractor::ClosedError, "The port was already closed"
       end
 
+      # @api private
+      def register_selector(waiter)
+        @select_mutex.synchronize { @select_waiters << waiter }
+      end
+
+      # @api private
+      def unregister_selector(waiter)
+        @select_mutex.synchronize { @select_waiters.delete(waiter) }
+      end
+
+      # @api private
+      def select_receive
+        @select_mutex.synchronize do
+          raise Ractor::ClosedError, "The port was already closed" if closed?
+          begin
+            value = @queue.pop(true)
+          rescue ThreadError
+            return
+          end
+          [self, value]
+        end
+      end
+
       alias << send
 
       def inspect = "#<#{self.class.name} to:#1 id:#{object_id}>"
+
+      private
+
+      def notify_selectors
+        @select_mutex.synchronize { @select_waiters.each(&:broadcast) }
+      end
     end
 
     BasePort = Port

data/lib/farce/engine/shared/queue.rb

@@ -12,10 +12,10 @@ module Farce
       attr_reader :capacity
 
       def initialize(capacity: 1024, track_age: false)
-        @queue    = capacity ? Thread::SizedQueue.new(capacity) : Thread::Queue.new
-        @capacity = capacity
-        @signal   = Signal.new
-        @tracking = track_age ? { lock: Mutex.new, timestamps: [], generation: 0 } : nil
+        @queue     = capacity ? Thread::SizedQueue.new(capacity) : Thread::Queue.new
+        @capacity  = capacity
+        @signal    = Signal.new
+        @tracking  = track_age ? { lock: Mutex.new, timestamps: [], generation: 0 } : nil
         @lifecycle = { lock: Mutex.new, hard_closed: false }
         Freeze.publish(self)
       end

data/lib/farce/engine/shared/ractor_methods.rb

@@ -63,8 +63,8 @@ module Farce
         with_storage(name) { _1[_2] = value }
       end
 
-      def select(...)
-        raise "TODO: not implemented"
+      def select(*sources, timeout: nil)
+        RactorSelector.new.select(*sources, timeout:)
       end
 
       alias recv receive

data/lib/farce/engine/shared/ractor_selector.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Wait for shim port readiness without consuming messages from losing ports.
+    class RactorSelector
+      def select(*sources, timeout: nil)
+        raise ArgumentError, "specify at least one Ractor::Port or Ractor" if sources.empty?
+        sources.each do |source|
+          next if source.is_a?(Ractor) || source.is_a?(Port)
+          raise ArgumentError, "should be Ractor::Port or Ractor"
+        end
+
+        timeout  = duration(timeout)
+        deadline = Clock.now + timeout if timeout
+        monitors = {}.compare_by_identity
+        ports    = sources.uniq.map do |source|
+          next source unless source.is_a?(Ractor)
+
+          port           = BasePort.new
+          monitors[port] = source
+          source.monitor(port)
+          port
+        end
+
+        result = wait(ports, deadline)
+        return unless result
+
+        port, value = result
+        ractor      = monitors[port]
+        ractor ? [ractor, ractor.value] : [port, value]
+      ensure
+        monitors&.each do |port, ractor|
+          ractor.unmonitor(port)
+          port.close
+        end
+      end
+
+      private
+
+      def duration(value)
+        return if value.nil?
+        raise TypeError, "cannot convert String into time interval" if value.is_a?(String)
+        value = Float(value)
+        raise RangeError, "timeout out of range" unless value.finite?
+        raise ArgumentError, "time interval must not be negative" if value.negative?
+        value
+      end
+
+      def wait(ports, deadline)
+        wakeup = Signal.new
+        ports.each { it.register_selector(wakeup) }
+        while true
+          # Observe before checking readiness so a send during that check
+          # changes the generation and prevents the following wait from parking.
+          generation = wakeup.generation
+          ports.each do |port|
+            result = port.select_receive
+            return result if result
+          end
+          remaining = deadline - Clock.now if deadline
+          return if remaining && !remaining.positive?
+          return unless ReservationWaiting.wait(wakeup, generation, deadline)
+        end
+      ensure
+        ports.each { it.unregister_selector(wakeup) }
+      end
+    end
+  end
+end

data/lib/farce/extension.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Defines a reusable extension for adding methods to target classes.
+  # These methods can either be activated as refinements, or installed globally to extend the target classes.
+  #
+  # ```ruby
+  # DoubleSize = Farce::Extension.define(String) do
+  #   def double_size = size * 2
+  # end
+  #
+  # module Namespace
+  #   using DoubleSize
+  #   "hello".double_size # => 10
+  # end
+  #
+  # "hello".respond_to?(:double_size) # => false
+  #
+  # DoubleSize.install
+  # "hello".respond_to?(:double_size) # => true
+  # ```
+  #
+  # ## Extending multiple classes
+  #
+  # An extension can also modify multiple target classes simultaneously:
+  #
+  # ```ruby
+  # DoubleSize = Farce::Extension.new do
+  #   define(String) { def double_size = size * 2 }
+  #   define(Array) { def double_size = sum(&:double_size) }
+  # end
+  #
+  # using DoubleSize
+  # ["hello", "foo"].double_size # => 16
+  # ```
+  class Extension < Module
+    # @api private
+    class Mixin < Module # :nodoc:
+      attr_reader :extension, :target
+
+      def initialize(extension, target, &)
+        @extension = extension
+        @target    = target
+        super(&)
+      end
+
+      def name = -"#{@extension.name}[#{@target.inspect}]"
+
+      def install
+        return if @target.ancestors.include?(self)
+        @target.prepend(self)
+      end
+    end
+    private_constant :Mixin
+
+    # @overload define(*targets)
+    #   Defines an extension for the given target classes.
+    #   @param targets [Array<Class>] the target classes to define methods for
+    #   @yield the block containing method definitions
+    #   @yieldreceiver [Module, Refinement] the module/refinement used for extending the target class.
+    #   @return [Extension] the newly created extension instance
+    #   @see Extension#define
+    def self.define(...) = new { define(...) }
+
+    # Creates a new extension.
+    # @yield Optional block for `define` calls or adding methods to the extension itself.
+    # @yieldreceiver [Extension] the extension instance itself.
+    def initialize
+      check_state!
+      @definitions = Internal::StrictMap.new
+      @lock        = Lock.new
+      @installed   = Flag.new
+      super
+    end
+
+    # @api private
+    def [](target) = @definitions[target]
+
+    # Defines additional methods for a given target class.
+    #
+    # The given block will be invoked at least twice. Once in the context of a refinement for the target class,
+    # and once in the context of the mixin module that will be prepended to the target class.
+    #
+    # @example
+    #   extension = Farce::Extension.new
+    #   extension.define(String) { def double_size = size * 2 }
+    #
+    #   module Namespace
+    #     using extension
+    #     String.method_defined?(:double_size) # => true
+    #   end
+    #
+    #   String.method_defined?(:double_size) # => false
+    #   extension.install
+    #   String.method_defined?(:double_size) # => true
+    #
+    # @param targets [Array<Class>] the target classes to define methods for
+    # @yield the block containing method definitions
+    # @yieldreceiver [Module, Refinement] the module/refinement used for extending the target class.
+    # @return [self] the extension instance
+    def define(*targets, &)
+      @lock.synchronize do
+        check_state!
+        targets.each do |target|
+          refine(target, &)
+          mixin = @definitions.store_if_absent(target) { Mixin.new(self, target) }
+          mixin.module_eval(&)
+          mixin.install if installed?
+        end
+      end
+      self
+    end
+
+    # Installs the extension globally.
+    # @return [void]
+    def install
+      @lock.synchronize do
+        return false if installed?
+        check_state!(allow_frozen: true)
+        @definitions.each_value(&:install)
+        yield if block_given?
+        @installed.set
+      end
+    end
+
+    # @return [Boolean] whether the extension has been installed
+    def installed? = @installed.set?
+
+    # Freezes the extension.
+    #
+    # No {#define definitions} can be added after freezing the extension.
+    # @return [self] the frozen extension
+    def freeze
+      return self if frozen?
+      @lock.synchronize do
+        @definitions.freeze
+        super
+      end
+    end
+
+    private
+
+    def check_state!(allow_frozen: false)
+      raise Ractor::IsolationError, "must be called from main Ractor" if Internal.native_ractors? && !Ractor.main?
+      Internal::Freeze.check(self) unless allow_frozen
+    end
+  end
+end

data/lib/farce/integrations/ractor_tmvar.rb

@@ -13,7 +13,10 @@ module Farce
     # Take, put, and swap operate on the value staged in this attempt.
     # An empty read, take, or swap, or a put into a full TMVar fails the
     # attempt. Farce.transaction retries these conditions within its retry limit.
-    # The try_* methods return nil or false without failing the attempt.
+    # The try_* methods return nil or false when unavailable without failing
+    # the attempt. Blocks passed to try_read and try_take run only when full,
+    # including for stored nil, and return the block's result.
+    # Create an empty TMVar with Ractor::TMVar.new and a full nil with .new(nil).
     # Assigned values are made shareable, matching Ractor::TVar's setter.
     #
     # Run outside Ractor.atomically, as required by {RactorTVar}.

data/lib/farce/internal/fake_ractor.rb

@@ -21,6 +21,7 @@ module Farce
         INSTANCE     = Freeze.publish(new)
         DEFAULT_PORT = BasePort.new
 
+        def alive?       = true
         def default_port = DEFAULT_PORT
         def inspect      = "#<Farce::Ractor#1 running>"
         def join         = sleep
@@ -78,7 +79,7 @@ module Farce
           ensure
             state.mutex.synchronize do
               state.monitors.each do |monitor|
-                monitor << state.status
+                FakeRactor.send_status(monitor, self, state.status)
               end
               state.monitors = nil
             end
@@ -97,6 +98,8 @@ module Farce
           Farce::Ractor[key] = value
         end
 
+        def alive? = STATES[self].status == :running
+
         def monitor(port) # rubocop:disable Naming/PredicateMethod
           state = STATES[self]
 
@@ -108,7 +111,7 @@ module Farce
             end
           end
 
-          port << state.status
+          FakeRactor.send_status(port, self, state.status)
           false
         end
 
@@ -148,6 +151,11 @@ module Farce
         undef clone
       end
 
+      def self.send_status(port, ractor, status)
+        payload = System.ruby_version >= "4.1" ? [ractor, status].freeze : status
+        port << payload
+      end
+
       def self.current
         # JRuby fibers expose a backing thread with a different thread group.
         thread   = Internal.storage_thread(Thread.current)

data/lib/farce/internal/scheduler_lifecycle.rb

@@ -82,15 +82,13 @@ module Farce
 
       def unblock(_blocker, fiber) # rubocop:disable Naming/PredicateMethod
         return false if @closed || !(token = current_wait(fiber))
-        @mailbox << Completion.new(token, true, nil).freeze
-        wakeup
+        complete_wait(token, true)
         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
+        complete_wait(token, nil, exception)
         true
       end
 
@@ -202,6 +200,11 @@ module Farce
 
       private
 
+      def complete_wait(token, value, error = nil)
+        @mailbox << Completion.new(token, value, error).freeze
+        wakeup
+      end
+
       def finish_close
         return if @closed
         shutdown

data/lib/farce/null_port.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Special, write-only port that discards all messages.
+  # If the Ruby environment supports ports, this will be a real Port object.
+  # It can therefore be passed to any API expecting a `Ractor::Port`, including C code.
+  # Cannot be read from, but does not accumulate messages in memory.
+  # @return [Ractor::Port] Write-only port
+  NULL_PORT = Internal::NullPort.new
+end

data/lib/farce/system.rb

@@ -7,8 +7,16 @@ require "etc"
 module Farce
   # Information about the system running Farce.
   module System
-    WINDOWS = Gem.win_platform?
-    private_constant :WINDOWS
+    ruby_version = Gem.ruby_version.release
+    ruby_version = ::Ractor.make_shareable(ruby_version, copy: true) if defined?(::Ractor)
+    RUBY_VERSION = ruby_version
+    WINDOWS      = Gem.win_platform?
+    private_constant :RUBY_VERSION, :WINDOWS
+
+    # A Version object representing the current Ruby release, without prerelease suffixes.
+    # Safe to call from any Ractor.
+    # @return [#<=>, #to_s]
+    def self.ruby_version = RUBY_VERSION
 
     # Whether the current operating system is Windows.
     # Safe to call from any Ractor.

data/lib/farce/version.rb

@@ -4,5 +4,5 @@
 
 module Farce
   # @return [String] the current version of Farce
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/farce.rb

@@ -46,7 +46,7 @@ require "farce/system"
 # defined?(VERSION) # => false
 # ```
 module Farce
-  include Internal::Autoloads
+  include Internal::Autoloads[null_port: :NULL_PORT]
 
   # The valid storage scopes for local values and collections.
   # @return [::Set<Symbol>]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: farce
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: java
 authors:
 - Konstantin Haase
 bindir: bin
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies: []
 email:
 - konstantin.mailinglists@googlemail.com
@@ -22,11 +22,22 @@ files:
 - README.md
 - SECURITY.md
 - docs/benchmarks.md
+- docs/compatibility.md
+- docs/concurrency.md
+- docs/data-structures.md
 - docs/gems/dry-types.md
 - docs/gems/msgpack.md
 - docs/gems/ractor-shim.md
+- docs/installation.md
+- docs/integrations.md
+- docs/introduction.md
 - docs/modes.md
+- docs/scheduling.md
 - docs/scopes.md
+- docs/sharing.md
+- docs/shims.md
+- docs/utilities.md
+- docs/variants-and-scopes.md
 - docs/variants.md
 - lib/farce.rb
 - lib/farce/_yard/internal.rb
@@ -67,6 +78,7 @@ files:
 - lib/farce/abstract/weak_set.rb
 - lib/farce/abstract/weak_value_map.rb
 - lib/farce/atom.rb
+- lib/farce/backports.rb
 - lib/farce/class_mirror.rb
 - lib/farce/clock.rb
 - lib/farce/config.rb
@@ -79,6 +91,7 @@ files:
 - lib/farce/engine/jruby/lease_waiting.rb
 - lib/farce/engine/jruby/map.rb
 - lib/farce/engine/jruby/mutable_numeric_copy.rb
+- lib/farce/engine/jruby/scheduler_synchronization.rb
 - lib/farce/engine/jruby/signal.rb
 - lib/farce/engine/jvm.rb
 - lib/farce/engine/jvm/concurrent_weak_registry.rb
@@ -91,14 +104,18 @@ files:
 - lib/farce/engine/jvm/types.rb
 - lib/farce/engine/ruby.rb
 - lib/farce/engine/ruby/3.4/fiber_scheduler.rb
+- lib/farce/engine/ruby/3.4/null_port.rb
+- lib/farce/engine/ruby/3.4/patch.rb
 - lib/farce/engine/ruby/3.4/port.rb
 - lib/farce/engine/ruby/3.4/ractor_methods.rb
 - lib/farce/engine/ruby/3.4/ractor_selector.rb
 - lib/farce/engine/ruby/3.4/vault.rb
+- lib/farce/engine/ruby/4.0/null_port.rb
 - lib/farce/engine/ruby/4.0/port.rb
 - lib/farce/engine/ruby/4.0/ractor_methods.rb
 - lib/farce/engine/ruby/4.0/ractor_selector.rb
 - lib/farce/engine/ruby/4.0/vault.rb
+- lib/farce/engine/ruby/4.1/null_port.rb
 - lib/farce/engine/ruby/4.1/port.rb
 - lib/farce/engine/ruby/4.1/ractor_methods.rb
 - lib/farce/engine/ruby/4.1/ractor_selector.rb
@@ -127,12 +144,14 @@ files:
 - lib/farce/engine/shared/lease_pool.rb
 - lib/farce/engine/shared/main_scheduler.rb
 - lib/farce/engine/shared/map_key_coordination.rb
+- lib/farce/engine/shared/null_port.rb
 - lib/farce/engine/shared/parallel_scheduler.rb
 - lib/farce/engine/shared/port.rb
 - lib/farce/engine/shared/portable_bounded_map.rb
 - lib/farce/engine/shared/proxy_owner.rb
 - lib/farce/engine/shared/queue.rb
 - lib/farce/engine/shared/ractor_methods.rb
+- lib/farce/engine/shared/ractor_selector.rb
 - lib/farce/engine/shared/rebindable.rb
 - lib/farce/engine/shared/strict_atom.rb
 - lib/farce/engine/shared/strict_map.rb
@@ -171,6 +190,7 @@ files:
 - lib/farce/envelope.rb
 - lib/farce/error.rb
 - lib/farce/exchanger.rb
+- lib/farce/extension.rb
 - lib/farce/flag.rb
 - lib/farce/integrations.rb
 - lib/farce/integrations/active_support.rb
@@ -299,6 +319,7 @@ files:
 - lib/farce/mode_manager/smart_rule.rb
 - lib/farce/molecule.rb
 - lib/farce/mutable.rb
+- lib/farce/null_port.rb
 - lib/farce/pool.rb
 - lib/farce/port.rb
 - lib/farce/priority_queue.rb