farce 0.4.1-java → 0.5.0-java

data/lib/farce/local/scheduler.rb

@@ -56,6 +56,7 @@ module Farce
       def initialize(capacity: 1024, backend: Internal::FROZEN_CONFIG.io_backend, scope: :ractor,
                      worker: nil, &constructor)
         @constructor        = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @capacity           = capacity && Integer(capacity)
         @backend            = backend
         @worker             = worker
         @schedulers         = Strict::Map.new
@@ -65,15 +66,26 @@ module Farce
         super(scope:, capacity: capacity && Integer(capacity), backend:)
       end
 
+      # Pending-task capacity in this scope. New scopes retain the constructor value.
+      def capacity = (scheduler = current_scheduler) ? scheduler.capacity : @capacity
+
+      # Resize the queue in this scope without starting a worker.
+      def capacity=(value)
+        raise SchedulerClosedError, "cannot configure a closed scheduler" if @closed_all.value
+        scoped_value.capacity = value
+      end
+
       # Enqueue a task in the current scope, preserving its block and arguments.
       # `mode` is ignored when `auto_local` is true. Otherwise, only local and smart modes are accepted.
-      # @overload schedule(*args, mode: :smart, auto_local: true)
+      # @overload schedule(*args, mode: :smart, auto_local: true, timeout: nil)
       #   @param (see Farce::Abstract::Executor#schedule)
-      #   @return [self]
+      #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
       def schedule(...) = enqueue_task(false, ...)
 
       # (see Abstract::Scheduler#try_schedule)
-      def try_schedule(...) = enqueue_task(true, ...)
+      def try_schedule(*, mode: :smart, auto_local: true, &)
+        enqueue_task(true, *, mode:, auto_local:, &)
+      end
 
       # Starts a worker for the current scope. Other scopes retain their creation behavior.
       # @param executor [Class, nil] Thread or a custom executor that stays in this Ractor.
@@ -147,12 +159,13 @@ module Farce
 
       private
 
-      def enqueue_task(non_block, *, mode: :smart, auto_local: true, &block)
+      def enqueue_task(non_block, *, mode: :smart, auto_local: true, timeout: nil, &block)
         raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if @closed_all.value
         scheduler = scoped_value
         raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if scheduler.closed?
         raise LocalJumpError, "Cannot schedule without a block" unless block
 
+        deadline = scheduling_deadline(timeout)
         validate_local_mode(mode, auto_local)
         register_scheduler(scheduler)
 
@@ -160,7 +173,7 @@ module Farce
           if non_block
             scheduler.try_schedule(*, mode:, auto_local:, &block)
           else
-            scheduler.schedule(*, mode:, auto_local:, &block)
+            scheduler.schedule(*, mode:, auto_local:, timeout: Clock.remaining(deadline), &block)
           end
 
         submitted && self

data/lib/farce/local/vector.rb

@@ -8,10 +8,11 @@ module Farce
     #
     # @!method initialize(source = nil, compare_by_identity: false, scope: :ractor)
     #   @!macro scopes
-    #   @param source [Array, nil] the initial values
+    #   @param source [Array, Integer, nil] Initial values or a size filled with nil.
     #   @param compare_by_identity [Boolean] whether values are compared by identity
     #   @param scope [Symbol] the scope of the vector
     #   @return [Vector]
+    #   @raise [ArgumentError] If the size is negative.
     class Vector < Abstract::Vector
       include Shareable::Tracked
       include Scoped::Tracked
@@ -24,7 +25,7 @@ module Farce
         self.class.new(values, compare_by_identity: compare_by_identity?, scope:)
       end
 
-      private def new_scoped_value(...) = Internal::UnsharedVector.new(...)
+      private def new_scoped_value(source = nil, **) = Internal::UnsharedVector.new(normalize_vector_source(source), **)
     end
   end
 end

data/lib/farce/memoize.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Ractor-friendly memoization module.
+  #
+  # Replaces the following pattern:
+  #
+  # ```ruby
+  # class MyClass
+  #   def time
+  #     @time ||= Time.now
+  #   end
+  # end
+  # ```
+  #
+  # Using `Farce::Memoize` instead gives you:
+  #
+  # * Allows memoization after freezing
+  # * Is Ractor-safe (with optional scoping or transfer modes) and thread-safe
+  # * Adds one instance variable per memoized method (avoids hash lookup and doesn't bust Ruby's data structures)
+  # * Is Marshal-dump/load friendly
+  # * Allows weak memoization, where the memoized value is kept until it is garbage collected
+  # * Does not need to run code on the main Ractor for memoization
+  #
+  # Methods with arguments cannot be memoized. Explicitly use a {Farce::Abstract::Map map} instead.
+  #
+  # @example Using `memoize` method
+  #   class MyClass
+  #     include Farce::Memoize
+  #     memoize def time = Time.now
+  #   end
+  #
+  #   instance    = MyClass.new
+  #   first_time  = instance.time
+  #   second_time = instance.time
+  #
+  #   first_time == second_time      # => true
+  #   first_time == MyClass.new.time # => false
+  #
+  # @example Scope-specific memoization
+  #   class MyClass
+  #     include Farce::Memoize
+  #
+  #     def first = expensive_computation(0)
+  #     def last  = expensive_computation(-1)
+  #
+  #     # Memoize separately per Ractor
+  #     memoize :first, :last, scope: :ractor
+  #   end
+  #
+  # @example Setting a mode
+  #   class MyClass
+  #     include Farce::Memoize
+  #     memoize :expensive, mode: :make_shareable
+  #     def expensive = expensive_computation
+  #   end
+  #
+  # @example Without `memoize` extension
+  #   class MyClass
+  #     include Farce::Memoize[:time]
+  #     def time = Time.now
+  #   end
+  #
+  # @see Farce::Lazy
+  # @see Farce::LazyRef
+  #
+  # @!macro memoize_params
+  #   @overload $0(*methods, scope: :global, mode: :smart, weak: false, visibility: nil)
+  #     @param methods [Array<Symbol>]
+  #       The methods to memoize
+  #
+  #     @param scope [Symbol]
+  #       The scope of the memoization.
+  #       In addition to the {Farce::SCOPES normal scopes} it may also be set to `:global` or `:unshared`.
+  #
+  #     @param mode [Symbol]
+  #       The mode of the memoization. Ignored for any scope other than `:global`.
+  #       Defaults to `:raise` with `weak: true`, which supports only `:raise`, `:make_shareable`, and `:dedup`.
+  #
+  #     @param weak [Boolean]
+  #       Whether to use weak memoization.
+  #       If enabled, memoized values may be garbage collected when no longer referenced.
+  #       In this case, next access to the memoized method may recompute the value.
+  #
+  #     @param visibility [Symbol, nil]
+  #       The visibility of the memoized methods.
+  #       May be one of `:public`, `:protected`, or `:private`.
+  #       If set to `nil`, {Farce::Memoize#memoize} will attempt to infer the visibility based on the context.
+  #       Other methods will default to `:public`.
+  module Memoize
+    # A named module preserves the nil marker's identity across Marshal round trips.
+    NIL_VALUE = Module.new.freeze
+    private_constant :NIL_VALUE
+
+    # Mixins used to implement memoization for different methods, scopes, and modes
+    # @see Farce::Memoize
+    class Mixin < Module
+      KNOWN = Strict::Map.new
+      private_constant :KNOWN
+
+      # @!macro memoize_params
+      # Creates or retrieves a memoization mixin for the given methods and options.
+      # @return [Mixin] the memoization mixin
+      def self.new(*methods, **options)
+        return super unless self == Mixin
+        methods = Farce.dedup(methods.map(&:to_sym).uniq.sort)
+        options = Farce.dedup(normalize_options(options))
+        map     = KNOWN.store_if_absent(options) { Strict::Map.new }
+        map.store_if_absent(methods) { super(methods, **options) }
+      end
+
+      # @api private
+      def self.normalize_options(options)
+        options[:visibility] &&= options[:visibility].to_sym
+
+        options[:scope]      ||= :global
+        options[:visibility] ||= :public
+        options[:weak]       ||= false
+
+        if options[:scope] == :global
+          options[:mode] ||= options[:weak] ? :raise : :smart
+        else
+          options.delete(:mode)
+        end
+
+        options
+      end
+      private_class_method :normalize_options
+
+      # @return [Array<Symbol>] the memoized methods
+      attr_reader :memoized_methods
+
+      # @return [Symbol] the scope of the memoization
+      attr_reader :scope
+
+      # @return [Symbol, nil] the transfer mode, or nil for a scoped cache
+      attr_reader :mode
+
+      # @return [Symbol] the visibility of the memoized methods
+      attr_reader :visibility
+
+      # @api private
+      def initialize(methods, scope:, weak:, mode: nil, visibility: :public)
+        @memoized_methods = methods
+        @scope            = scope
+        @mode             = mode
+        @weak             = !!weak # rubocop:disable Style/DoubleNegation
+        @visibility       = visibility
+
+        super()
+
+        unless %i[public protected private].include?(visibility)
+          raise ArgumentError, "unsupported visibility: #{visibility.inspect}"
+        end
+
+        atom_class = weak ? "WeakAtom" : "Atom"
+
+        case scope
+        when :global
+          modes = weak ? Internal::WeakModeManager::MODES : MODES
+          raise ArgumentError, "unsupported mode: #{mode.inspect}" unless modes.include?(mode)
+          init = "::Farce::#{atom_class}.new(mode: #{mode.inspect})"
+          args = methods.join(", ")
+          args += ", mode: #{mode.inspect}" unless mode == :smart
+        when :unshared
+          init = "::Farce::Unshared::#{atom_class}.new"
+          args = "#{methods.join(", ")}, scope: :unshared"
+        when *SCOPES
+          init = "::Farce::Local::#{atom_class}.new(scope: #{scope.inspect})"
+          args = "#{methods.join(", ")}, scope: #{scope.inspect}"
+        else
+          raise ArgumentError, "unsupported scope: #{scope.inspect}"
+        end
+
+        set_temporary_name(-"Farce::Memoize[#{args}]") if instance_of?(Mixin)
+        initializer = +""
+        # Overlapping mixins need separate slots. Stable names also survive Marshal across processes.
+        slot = "#{methods.join(",").unpack1("H*")}_#{scope}_#{mode}_#{@weak}_#{visibility}"
+
+        methods.each do |method|
+          unless method =~ /\A[a-z_]\w*[!?]?\z/i && method != :initialize
+            raise ArgumentError, "unsuitable method name: #{method.inspect}"
+          end
+          ivar = "@_#{method.to_s.unpack1("H*")}_memoize_#{slot}_atom"
+          initializer << "  #{ivar} = #{init}\n"
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            #{visibility} def #{method}
+              value = #{ivar}.store_if_absent do
+                result = super()
+                nil.equal?(result) ? NIL_VALUE : result
+              end
+              value unless NIL_VALUE.equal?(value)
+            end
+          RUBY
+        end
+
+        # Explicit forwarding preserves nested constructor keywords on JRuby.
+        module_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def initialize(*, **, &)
+            #{initializer}
+            super
+          end
+        RUBY
+      end
+
+      # @return [Boolean] whether the memoization is weak
+      def weak? = @weak
+
+      # allow `include Farce::Memoize[...]` to work like `prepend`
+      private def append_features(base) = base.prepend(self)
+    end
+
+    # @api private
+    def self.append_features(base) = base.extend(self)
+    private_class_method :append_features
+
+    # Creates or retrieves the memoization mixin for the given methods, scope, and mode
+    # @!macro memoize_params
+    # @return [Mixin] memoization mixin for the given methods, scope, and mode
+    def self.[](...) = Mixin.new(...)
+
+    # @!macro memoize_params
+    # Creates a memoization mixin for the given arguments and adds it to the current class.
+    #
+    # Can be used as a prefix to `def`:
+    #
+    # ```ruby
+    # memoize def some_method = expensive_computation
+    # ```
+    #
+    # Or called separately with the method names, useful for passing additional options:
+    #
+    # ```ruby
+    # def some_method = expensive_computation
+    #
+    # # memoize some_method per thread
+    # memoize :some_method, scope: :thread
+    # ```
+    #
+    # ## Visibility of Memoized Methods
+    #
+    # If no visibility is provided, it will determine the visibility based on the existing method definitions.
+    # If none exist, it will default to public. This happens when `memoize` is called.
+    # Make sure you set the visibility before calling this method.
+    #
+    # This works:
+    #
+    # ```ruby
+    # memoize private def some_method = expensive_computation
+    # ```
+    #
+    # As does this:
+    #
+    # ```ruby
+    # private
+    # memoize def some_method = expensive_computation
+    # ```
+    #
+    # Or this:
+    #
+    # ```ruby
+    # private def some_method = expensive_computation
+    # memoize :some_method
+    # ```
+    #
+    # But this doesn't, as the mixin's method will end up public:
+    #
+    # ```ruby
+    # private memoize def some_method = expensive_computation
+    # ```
+    #
+    # Same for this one, as the mixin's method will also end up public:
+    #
+    # ```ruby
+    # memoize :some_method
+    # private def some_method = expensive_computation
+    # ```
+    #
+    # You can of course set visibility explicitly when calling `memoize`:
+    #
+    # ```ruby
+    # memoize :some_method, visibility: :private
+    # ```
+    #
+    # @return [Array<Symbol>] the list of memoized methods
+    def memoize(*methods, visibility: nil, warn: true, **)
+      if visibility.nil?
+        groups = methods.group_by do |method|
+          next :protected if protected_method_defined?(method)
+          next :private   if private_method_defined?(method)
+          :public
+        end
+        return groups.flat_map { memoize(*_2, visibility: _1, warn:, **) }
+      end
+
+      if warn
+        methods.each do |name|
+          method = instance_method(name)
+          next if method.parameters.empty?
+          warn "#{method.owner}##{name} expects parameters and may be unsuitable for memoization"
+        rescue NameError => e
+          raise e unless e.name == name.to_sym
+        end
+      end
+
+      mixin = Farce::Memoize[*methods, visibility:, **]
+      prepend mixin
+
+      mixin.memoized_methods
+    end
+  end
+end

data/lib/farce/pool.rb

@@ -11,6 +11,11 @@ module Farce
   # `min_size` retire after `shrink_after` without queued or running work.
   # By default, the pool starts with no workers and can shrink back to zero.
   #
+  # Worker limits, task limits, scaling delays, and queue capacity can change while
+  # the pool runs. Lowering `max_size` retires extra workers as they become idle.
+  # Busy workers keep queued work runnable. Raising `min_size` starts workers
+  # immediately. Queued tasks are retained.
+  #
   # Most importantly, it exposes a {#schedule} method compatible with {Scheduler#schedule}.
   #
   # @example

data/lib/farce/priority_queue.rb

@@ -42,7 +42,7 @@ module Farce
         result = @reverse_order ? @queue.pop_last { empty = true } : @queue.pop { empty = true }
 
         return @manager.unwrap(result) unless empty
-        remaining = remaining_timeout(deadline)
+        remaining = Clock.remaining(deadline)
         return block_given? ? yield : nil unless wait_pop(timeout: remaining)
       end
     end

data/lib/farce/publisher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A message multiplexer.
+  # Implements the publisher-subscriber protocol.
+  #
+  # @example
+  #   publisher = Farce::Publisher.new
+  #
+  #   # Count how many messages have been received
+  #   counter = Farce::Counter.new
+  #   publisher.subscribe(counter)
+  #
+  #   # Trigger a callback whenever a message is published
+  #   publisher.subscribe do |message|
+  #     puts "Received message: #{message}"
+  #   end
+  #
+  #   # Send messages to a queue
+  #   queue = Farce::Queue.new
+  #   publisher.subscribe(queue)
+  #
+  #   # Keep track of the last published value
+  #   atom = Farce::Atom.new
+  #   publisher.subscribe(atom)
+  #
+  #   # Send messages to a Ractor
+  #   ractor = Ractor.new do
+  #     while message = Ractor.receive
+  #       puts "Received message in Ractor: #{message}"
+  #     end
+  #   end
+  #   publisher.subscribe(ractor)
+  #
+  #   # Publish some messages
+  #   publisher.publish("Hello, world!")
+  #   publisher.publish("Another message")
+  #
+  #   queue.pop     # => "Hello, world!"
+  #   atom.value    # => "Another message"
+  #   counter.value # => 2
+  class Publisher < Farce::Abstract::Publisher
+    include Shareable::Unfreezable
+
+    # @overload initialize(*subscribers)
+    #   (see Farce::Abstract#initialize)
+    def initialize(*subscribers)
+      @map = Strict::Map.new
+      super()
+      subscribers.each { subscribe(it) }
+    end
+
+    private attr_reader :map
+  end
+end

data/lib/farce/signal.rb

@@ -80,7 +80,7 @@ module Farce
         result   = yield
         return result if result
 
-        remaining = deadline - Clock.now if deadline
+        remaining = Clock.remaining(deadline)
         return if remaining && !remaining.positive?
         return unless wait(observed, timeout: remaining)
       end

data/lib/farce/strict/publisher.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # Strict variant of {Farce::Publisher}.
+    class Publisher < Farce::Abstract::Publisher
+      include Shareable::Unfreezable
+
+      # @overload initialize(*subscribers)
+      #   (see Farce::Abstract#initialize)
+      def initialize(*subscribers)
+        @map = Strict::Map.new
+        super()
+        subscribers.each { subscribe(it) }
+      end
+
+      # (see Farce::Abstract::Publisher#publish)
+      def publish(message = nil)
+        return super if Ractor.shareable?(message)
+        raise Ractor::IsolationError, "value must be Ractor-shareable"
+      end
+      alias send      publish
+      alias <<        publish
+      alias broadcast publish
+
+      private attr_reader :map
+    end
+  end
+end

data/lib/farce/strict/vector.rb

@@ -8,10 +8,11 @@ module Farce
     class Vector < Abstract::Vector
       include Shareable::Delegated
 
-      # @param source [Array, nil] Initial values. The source array is not retained.
+      # @param source [Array, Integer, nil] Initial values or a size filled with nil. The source array is not retained.
       # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      # @raise [ArgumentError] If the size is negative.
       def initialize(source = nil, compare_by_identity: false)
-        @vector = Internal::Vector.new(source, compare_by_identity:)
+        @vector = Internal::Vector.new(normalize_vector_source(source), compare_by_identity:)
         super()
       end
 

data/lib/farce/subscription/definitions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Subscription
+    Farce.on_main do
+      ractors = Internal.native_ractors? ? [::Ractor] : [Internal::FakeRactor::Main, Internal::FakeRactor::NotMain]
+
+      define(Internal::BasePort, *ractors)      { subscriber.send(it)      }
+      define(Abstract::Publisher)               { subscriber.publish(it)   }
+      define(Abstract::Queue)                   { subscriber.try_push(it)  }
+      define(Internal::Counter, Local::Counter) { |_| subscriber.increment }
+      define(Internal::Flag, Local::Flag)       { |_| subscriber.set       }
+      define(Abstract::Atom)                    { subscriber.value = it    }
+      define(Abstract::Set, Abstract::Vector)   { subscriber << it         }
+      define(Signal)                            { |_| subscriber.broadcast }
+
+      define(::Thread::Queue) { subscriber.push(it) }
+      define(::Thread::SizedQueue) do |payload|
+        subscriber.push(payload, true)
+      rescue ThreadError
+        false
+      end
+    end
+  end
+end

data/lib/farce/subscription.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A publisher subscription that can be paused or permanently canceled.
+  # Disabling skips new messages. Unsubscribing drains an existing callback queue before stopping it.
+  class Subscription
+    include Internal::Freeze::Unfreezable
+    include Internal::Noncopyable
+
+    # Raised when an operation is attempted on an unsubscribed subscription.
+    UnsubscribedError = Class.new(StandardError)
+
+    REGISTER = ClassMirror.new(self)
+    private_constant :REGISTER
+
+    class << self
+      protected :new
+    end
+
+    # Register delivery behavior for subscriber classes from the main Ractor.
+    # Subclasses inherit the nearest registered delivery method.
+    #
+    # @example
+    #   Farce::Subscription.define(MyInbox) { |payload| subscriber.push(payload) }
+    #
+    # @param classes [Array<Class>] the subscriber classes to support
+    # @yieldparam payload [BasicObject] the published payload
+    # @yieldreceiver [Subscription] the subscription whose {#subscriber} receives the payload
+    # @note The block must be convertible to a shareable proc.
+    # @return [void]
+    def self.define(*classes, &)
+      raise LocalJumpError, "no block given" unless block_given?
+      definition = Internal.prepare_method_definition(&)
+      classes.each do |klass|
+        REGISTER.define(klass) do
+          define_method(:deliver, definition)
+          private :deliver
+        end
+      end
+    end
+
+    # @api private
+    def self.build(publisher, subscriber, ...)
+      handler = REGISTER[subscriber.class]
+      unless handler.private_method_defined?(:deliver)
+        raise ArgumentError, "Unsupported subscriber type: #{subscriber.class}"
+      end
+      handler.new(publisher, subscriber, ...)
+    end
+
+    # @return [BasicObject] the subscriber associated with this subscription
+    attr_reader :subscriber
+
+    # @return [Farce::Abstract::Publisher] the publisher associated with this subscription
+    attr_reader :publisher
+
+    # @api private
+    attr_reader :key
+
+    # @!visibility private
+    def initialize(publisher, subscriber, map, callback: false, source: nil)
+      # Keep Proc identities alive without making their captured state shareable.
+      @source     = source && Envelope.new(source, mode: :local)
+      @callback   = callback
+      @enabled    = Flag.new(true)
+      @key        = (source || subscriber).__id__
+      @map        = map
+      @publisher  = publisher
+      @subscribed = Flag.new(true)
+      @subscriber = subscriber
+      super()
+      __freeze__
+    end
+
+    # @api private
+    def publish(payload)
+      return unless enabled?
+      deliver(payload)
+      true
+    rescue ::ClosedQueueError, Ractor::ClosedError, FrozenError
+      unsubscribe
+      false
+    end
+
+    # @return [Boolean] whether the subscription is currently enabled
+    def enabled? = @subscribed.value && @enabled.value
+
+    # @return [Boolean] whether the subscription has not been permanently canceled
+    def subscribed? = @subscribed.value
+
+    # Enables the subscription, allowing it to receive published payloads.
+    # @raise [UnsubscribedError] if the subscription has been unsubscribed
+    # @return [void]
+    def enable
+      raise UnsubscribedError, "Cannot enable a subscription that has been unsubscribed" unless @subscribed.value
+      @enabled.value = true
+    end
+
+    # Disables the subscription, preventing it from receiving published payloads.
+    # @return [void]
+    def disable = @enabled.value = false
+
+    # Removes the subscription permanently, allowing it and the subscriber to be garbage collected.
+    # @return [BasicObject, nil] the subscriber, or nil if already unsubscribed
+    def unsubscribe
+      return unless @subscribed.compare_and_set(true, false)
+      @map.delete_pair(key, self)
+      subscriber.seal if @callback
+      subscriber
+    end
+    alias cancel unsubscribe
+
+    private
+
+    define_method(:__freeze__, Kernel.instance_method(:freeze))
+
+    require "farce/subscription/definitions"
+  end
+end