farce 0 → 0.1.0

data/lib/farce/strict/priority_queue.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A priority queue that stores and returns values directly.
+    class PriorityQueue < Abstract::PriorityQueue
+      include Internal::StrictQueueValues unless Internal.native_ractors?
+      include Shareable::Unfreezable
+
+      def initialize(capacity: nil, default_priority: 0, order: :ascending, track_age: false)
+        unless Ractor.shareable?(default_priority)
+          raise Ractor::IsolationError, "default priority is not Ractor-shareable"
+        end
+        super
+      end
+    end
+  end
+end

data/lib/farce/strict/queue.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A FIFO queue that stores and returns values directly.
+    class Queue < Abstract::Queue
+      include Shareable::Unfreezable
+
+      def initialize(capacity: 1024, track_age: false)
+        @queue = Internal::Queue.new(capacity:, track_age:)
+        super()
+      end
+    end
+  end
+end

data/lib/farce/strict/set.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent set of shareable elements.
+    class Set < Farce::Abstract::Set
+      include Shareable::Delegated
+
+      private def new_map(...) = Farce::Strict::Map.new(...)
+    end
+  end
+end

data/lib/farce/strict/sorted_set.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent set maintained in ascending order.
+    class SortedSet < Farce::Abstract::SortedSet
+      include Shareable::Delegated
+
+      private
+
+      def new_map(entries = nil, compare_keys_by_identity: false, **)
+        raise ArgumentError, "sorted sets do not support identity comparison" if compare_keys_by_identity
+        Farce::Strict::TreeMap.new(entries)
+      end
+    end
+  end
+end

data/lib/farce/strict/timer_queue.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A timer queue that stores and returns values directly.
+    class TimerQueue < Abstract::TimerQueue
+      include Internal::StrictQueueValues unless Internal.native_ractors?
+      include Shareable::Unfreezable
+    end
+  end
+end

data/lib/farce/strict/tree_map.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable map that keeps shareable entries sorted by key.
+    # Mutable string keys become immutable. Other keys and all values must already be Ractor-shareable.
+    #
+    # @example Keeping direct values in key order
+    #   map = Farce::Strict::TreeMap.new(2 => "two".freeze, 1 => "one".freeze)
+    #
+    #   map.to_a # => [[1, "one"], [2, "two"]]
+    class TreeMap < Abstract::TreeMap
+      include Shareable::Delegated
+
+      # Values must already be Ractor-shareable.
+      # @return [true]
+      def shareable_values? = true
+
+      private
+
+      def new_tree_map(...) = Internal::StrictTreeMap.new(...)
+      def freeze_backend    = internal_map
+    end
+  end
+end

data/lib/farce/strict/vector.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable vector that stores and returns shareable values directly.
+    class Vector < Abstract::Vector
+      include Shareable::Delegated
+
+      # @param source [Array, nil] Initial values. The source array is not retained.
+      # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      def initialize(source = nil, compare_by_identity: false)
+        @vector = Internal::Vector.new(source, compare_by_identity:)
+        super()
+      end
+
+      # (see Farce::Abstract::Vector#shareable_values?)
+      def shareable_values? = true
+
+      private def freeze_backend = @vector
+    end
+  end
+end

data/lib/farce/strict/weak_atom.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable weak atomic reference that stores shareable values directly.
+    #
+    # @example Referencing a shareable object without keeping it alive
+    #   resource = Object.new.freeze
+    #   atom     = Farce::Strict::WeakAtom.new(resource, compare_by_identity: true)
+    #   atom.value.equal?(resource) # => true
+    #
+    #   resource = nil
+    #   # Once the object is collected, atom.value returns nil.
+    #
+    # @example Lazily storing a shareable value
+    #   atom  = Farce::Strict::WeakAtom.new
+    #   value = atom.store_if_absent { [1, 2, 3].freeze }
+    #   atom.value.equal?(value) # => true
+    #   # Keeping value referenced also keeps the atom's referent alive.
+    class WeakAtom < Abstract::WeakAtom
+      include Shareable::Delegated
+
+      private
+
+      def internal_atom_class = Internal::WeakAtom
+      def freeze_backend      = @atom
+    end
+  end
+end

data/lib/farce/strict/weak_key_map.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent map with weak shareable keys and strong shareable values.
+    #
+    # @example Associating metadata without retaining its owner
+    #   owner      = Object.new.freeze
+    #   map        = Farce::Strict::WeakKeyMap.new
+    #   map[owner] = :active
+    #   map[owner] # => :active
+    #
+    #   # The entry can disappear once its key is collected.
+    #   owner = nil
+    class WeakKeyMap < Abstract::WeakKeyMap
+      include Shareable::Delegated
+
+      def initialize(
+        initial_mapping = nil,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        initial_mapping = convert_entries(initial_mapping)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: true)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::StrictWeakKeyMap.new(
+          populate ? nil : initial_mapping,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        initial_mapping.each { |key, value| self[key] = value } if populate
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+
+      def shareable_keys? = true
+      def shareable_values? = true
+
+      private def freeze_backend = internal_map
+    end
+  end
+end

data/lib/farce/strict/weak_map.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent map that retains shareable keys and values weakly.
+    #
+    # @example Keeping a relationship while both objects remain alive
+    #   key   = Object.new.freeze
+    #   value = Object.new.freeze
+    #   map   = Farce::Strict::WeakMap.new({ key => value })
+    #   map[key].equal?(value) # => true
+    #
+    #   # The entry can disappear once its key or value is collected.
+    #   value = nil
+    class WeakMap < Abstract::WeakMap
+      include Shareable::Delegated
+
+      def initialize(
+        initial_mapping = nil,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        initial_mapping = convert_entries(initial_mapping)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: true)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::StrictWeakMap.new(
+          populate ? nil : initial_mapping,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        initial_mapping.each { |key, value| self[key] = value } if populate
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+
+      def shareable_keys? = true
+      def shareable_values? = true
+
+      private def freeze_backend = internal_map
+    end
+  end
+end

data/lib/farce/strict/weak_set.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent set that retains shareable elements weakly.
+    class WeakSet < Farce::Abstract::WeakSet
+      include Shareable::Delegated
+
+      private def new_map(...) = Farce::Strict::WeakMap.new(...)
+    end
+  end
+end

data/lib/farce/strict/weak_value_map.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A Ractor-shareable concurrent map with strong shareable keys and weak shareable values.
+    #
+    # @example Caching a value without keeping it alive
+    #   value = Object.new.freeze
+    #   map   = Farce::Strict::WeakValueMap.new({ result: value })
+    #   map[:result].equal?(value) # => true
+    #
+    #   # The entry can disappear once its value is collected.
+    #   value = nil
+    class WeakValueMap < Abstract::WeakValueMap
+      include Shareable::Delegated
+
+      def initialize(
+        initial_mapping = nil,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        initial_mapping = convert_entries(initial_mapping)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: true)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::StrictWeakValueMap.new(
+          populate ? nil : initial_mapping,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        initial_mapping.each { |key, value| self[key] = value } if populate
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+
+      def shareable_keys? = true
+      def shareable_values? = true
+
+      private def freeze_backend = internal_map
+    end
+  end
+end

data/lib/farce/strict.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Shareable containers that store shareable values directly.
+  module Strict
+    include Internal::Autoloads
+
+    # @overload enfarce(object, freeze: nil)
+    #   Converts vanilla Ruby objects into their {Farce::Strict} equivalents.
+    #
+    #   @example
+    #     Farce::Strict.enfarce({ foo: ["bar"] }) { Ractor.make_shareable(it) }
+    #     # =>  #<Farce::Strict::Map {foo: #<Farce::Strict::Vector ["bar"]>}>
+    #
+    #   @yield [object] Optional block, called with any object that doesn't have a specific conversion defined.
+    #   @yieldparam object [BasicObject] the object to convert
+    #   @yieldreturn [BasicObject] the converted object
+    #   @param object [BasicObject] The root object to convert
+    #   @param freeze [Boolean, nil]
+    #     Whether to freeze the converted objects.
+    #     If set to `nil` (default), the freezing behavior will depend on the original object's frozen state.
+    #   @return [BasicObject] the converted object
+    #   @see Farce.enfarce
+    def self.enfarce(object, **, &) = Internal::Converter.new(self, **, &).convert(object)
+  end
+end

data/lib/farce/system.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "etc"
+
+module Farce
+  # Information about the system running Farce.
+  module System
+    WINDOWS = Gem.win_platform?
+    private_constant :WINDOWS
+
+    # Whether the current operating system is Windows.
+    # Safe to call from any Ractor.
+    # @return [Boolean]
+    def self.windows? = WINDOWS
+
+    # Number of logical CPUs, optionally limited to a CPU type.
+    # Returns nil when the platform cannot report the requested CPU type.
+    # Safe to call from any Ractor.
+    # @param type [nil, Symbol] nil for all CPUs, :performance, or :efficiency
+    # @return [Integer, nil]
+    # @raise [ArgumentError] if the CPU type is invalid
+    def self.cpu_count(type = nil)
+      case type
+      when nil
+        if defined?(Internal::Darwin) && Internal::Darwin.respond_to?(:cpu_count)
+          Internal::Darwin.cpu_count
+        else
+          Etc.nprocessors
+        end
+      when :performance, :efficiency
+        method = :"#{type}_cpu_count"
+        Internal::Darwin.public_send(method) if defined?(Internal::Darwin) && Internal::Darwin.respond_to?(method)
+      else
+        raise ArgumentError, "invalid CPU type: #{type.inspect}"
+      end
+    end
+  end
+end

data/lib/farce/thread_scheduler.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A scheduler that starts a new thread for each scheduled task. Executes synchronous tasks inline.
+  # Creating an instance starts no threads. Blocks and arguments stay local to the caller.
+  # Tasks are not tracked, and closing this stateless scheduler has no effect.
+  # Default instances support Marshal. Instances with a custom thread factory reject dumping.
+  class ThreadScheduler < Farce::Abstract::Scheduler
+    include Shareable::Immutable
+    include Internal::Inspect
+
+    def initialize(&factory)
+      @factory = factory
+      super()
+    end
+
+    # @api private
+    def marshal_dump
+      raise TypeError, "scheduler factories cannot be marshaled" if @factory
+      [1]
+    end
+
+    # @api private
+    def marshal_load(data)
+      Internal::MarshalSupport.payload(data, 0)
+      initialize
+    end
+
+    # Starts a thread in the caller's Ractor, preserving the block and arguments.
+    #
+    # @overload schedule(*args, **options)
+    #   @param args [Array<Object>] Arguments passed to the block.
+    #   @param options [Hash] Scheduler options are ignored. All tasks use local arguments.
+    #   @yield [*args] The task to run.
+    #   @return [self]
+    def schedule(*, **, &)
+      raise LocalJumpError, "Cannot schedule without a block" unless block_given?
+      @factory ? @factory.call(*, &) : Thread.new(*, &)
+      self
+    end
+
+    # Runs the block on the caller's thread and fiber. Exceptions propagate to the caller.
+    #
+    # @overload execute(*args, **options)
+    #   @param args [Array<Object>] Arguments passed to the block.
+    #   @param options [Hash] Scheduler options are ignored. All tasks use local arguments.
+    #   @yield [*args] The task to run.
+    #   @return [self]
+    def execute(*, **)
+      raise LocalJumpError, "Cannot yield without a block" unless block_given?
+      yield(*)
+      self
+    end
+
+    # @return [self] Does not wait for or stop task threads.
+    def close = self
+
+    # @return [false] This stateless scheduler is always available.
+    def closed? = false
+
+    # @return [Symbol] Always `:running`.
+    def state = :running
+
+    # @param wait [Boolean] Ignored because tasks always run in the caller's Ractor.
+    # @return [true]
+    def local?(wait: true) = true # rubocop:disable Lint/UnusedMethodArgument
+  end
+end

data/lib/farce/timer_queue.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A shareable timer queue with transfer modes for unshareable values.
+  class TimerQueue < Abstract::TimerQueue
+    include Internal::ManagedQueue
+    include Shareable::Unfreezable
+
+    # (see Farce::Abstract::TimerQueue#initialize)
+    # @!macro modes
+    # @param mode [Symbol] the transfer mode for unshareable values
+    def initialize(capacity: nil, mode: :copy, track_age: false)
+      @manager = ModeManager.new(mode:)
+      super(capacity:, track_age:)
+    end
+
+    # (see Farce::Abstract::TimerQueue#push)
+    # @!macro modes
+    # @param mode [Symbol] the transfer mode for unshareable values
+    def push(value, non_block = false, mode: nil, timeout: nil, **time_options) # rubocop:disable Style/OptionalBooleanParameter
+      at = Clock.parse(time_options)
+      push_to_storage(at, non_block, @manager.wrap(value, mode:), timeout:)
+    end
+
+    # (see Farce::Abstract::TimerQueue#try_push)
+    # @!macro modes
+    # @param mode [Symbol] the transfer mode for unshareable values
+    def try_push(value, mode: nil, **time_options)
+      at = Clock.parse(time_options)
+      return true if @queue.push(at, @manager.wrap(value, mode:))
+      block_given? ? yield : false
+    end
+
+    # (see Farce::Abstract::TimerQueue#pop)
+    def pop(non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+      return try_pop { raise ThreadError, "queue empty" } if non_block
+      deadline = timeout_at(timeout) unless timeout.nil?
+
+      while true
+        empty = false
+        value = @queue.pop_before(Clock.now) { empty = true }
+        return @manager.unwrap(value) unless empty
+        return block_given? ? yield : nil if UNDEFINED.equal?(wait_for_timestamp(deadline))
+      end
+    end
+
+    # (see Farce::Abstract::TimerQueue#try_pop)
+    def try_pop
+      empty = false
+      value = @queue.pop_before(Clock.now) { empty = true }
+      return @manager.unwrap(value) unless empty
+      yield if block_given?
+    end
+
+    # (see Farce::Abstract::TimerQueue#peek)
+    # @note Peeking at a moved value claims it for this Ractor while leaving it queued.
+    def peek
+      empty = false
+      value = @queue.peek { empty = true }
+      return @manager.unwrap(value) unless empty
+      yield if block_given?
+    end
+  end
+end

data/lib/farce/transaction/atom.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # An {Abstract::Atom Atom} that is part of a transaction.
+    class Atom < Abstract::Atom
+      include Wrapper
+
+      # (see Abstract::Atom#compare_by_identity?)
+      # @see Abstract::Atom#compare_by_identity?
+      def compare_by_identity? = access { @object.compare_by_identity? }
+
+      # (see Abstract::Atom#value)
+      # @see Abstract::Atom#value
+      def value = access { unwrap_stored(@working.value) }
+      alias get value
+
+      # (see Abstract::Atom#value=)
+      # @see Abstract::Atom#value=
+      def value=(value)
+        store(value)
+      end
+
+      # (see Abstract::Atom#store)
+      # @see Abstract::Atom#store
+      def store(value, mode: nil)
+        write { unwrap_stored(@working.store(wrap(value, mode:))) }
+      end
+
+      # (see Abstract::Atom#swap)
+      # @see Abstract::Atom#swap
+      def swap(value, mode: nil)
+        write { unwrap_stored(@working.swap(wrap(value, mode:))) }
+      end
+
+      # (see Abstract::Atom#update)
+      # @see Abstract::Atom#update
+      def update(mode: nil)
+        require_block!(block_given?)
+        write { unwrap_stored(@working.store(wrap(yield(unwrap_stored(@working.value)), mode:))) }
+      end
+
+      # (see Abstract::Atom#store_if_absent)
+      # @see Abstract::Atom#store_if_absent
+      def store_if_absent(mode: nil)
+        require_block!(block_given?)
+        write { value.nil? ? store(yield, mode:) : value }
+      end
+
+      # (see Abstract::Atom#upsert)
+      # @see Abstract::Atom#upsert
+      def upsert(initial, mode: nil)
+        require_block!(block_given?)
+        write { store(value.nil? ? initial : yield(value), mode:) }
+      end
+
+      # (see Abstract::Atom#compare_and_set)
+      # @see Abstract::Atom#compare_and_set
+      def compare_and_set(expected, replacement, mode: nil)
+        write do
+          next compared(@working.compare_and_set(expected, replacement)) unless @manager
+          next compared(false) unless matches?(@working.value, expected, identity: @object.compare_by_identity?)
+          @working.store(wrap(replacement, mode:))
+          true
+        end
+      end
+
+      Wrapper.inherit(self, :compare_by_identity?, :unwrap)
+    end
+  end
+end

data/lib/farce/transaction/map.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::ConcurrentMap ConcurrentMap} that is part of a transaction.
+    #
+    # Reads and writes validate the keys they access, allowing concurrent changes
+    # to other keys. Size reads validate cardinality without observing contents.
+    # Enumeration, keys, getkey, and clear capture and validate the full map.
+    # Staged changes are visible through this wrapper and publish only on commit.
+    # Key validation compares current values by identity, not per-key write history.
+    # Commit captures a full snapshot for maps accessed by key. Changes after
+    # that snapshot is captured can still cause the attempt to fail.
+    class Map < Abstract::ConcurrentMap
+      include MapOperations
+
+      Wrapper.inherit(self, *MapOperations::READ_HELPERS, :delete_if, :reject!, :compact!, :keep_if,
+        :select!, :filter!, :transform_values!, :merge!)
+
+      private def enlist(backend) = @transaction.enlist(backend, per_key: true)
+    end
+  end
+end