farce 0 → 0.1.0

data/lib/farce/engine/truffleruby/native/counter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Counter < Numeric
+      attr_reader :initial
+
+      def initialize(value = 0)
+        raise "Counter is already initialized" if defined?(@reference)
+        check_frozen!
+        raise TypeError, "initial value must be an Integer" unless value.is_a?(Integer)
+        @signal    = Signal.new
+        @initial   = value
+        @reference = TruffleRuby::AtomicReference.new(value)
+        super()
+      end
+
+      def get = @reference.get
+
+      def store(value)
+        check_frozen!
+        raise TypeError, "value must be an Integer" unless value.is_a?(Integer)
+        @reference.set(value)
+        @signal.broadcast
+        value
+      end
+
+      def swap(value)
+        check_frozen!
+        raise TypeError, "value must be an Integer" unless value.is_a?(Integer)
+        @reference.get_and_set(value).tap { @signal.broadcast }
+      end
+
+      def compare_and_set(expected_value, new_value)
+        check_frozen!
+        raise TypeError, "expected value must be an Integer" unless expected_value.is_a?(Integer)
+        raise TypeError, "replacement value must be an Integer" unless new_value.is_a?(Integer)
+        @reference.compare_and_set(expected_value, new_value).tap { @signal.broadcast }
+      end
+
+      def add(delta = 1)
+        check_frozen!
+        raise TypeError, "delta must be an Integer" unless delta.is_a?(Integer)
+        change(delta)
+      end
+
+      def subtract(delta = 1)
+        check_frozen!
+        raise TypeError, "delta must be an Integer" unless delta.is_a?(Integer)
+        change(-delta)
+      end
+
+      def increment(delta = 1)
+        check_frozen!
+        unless delta.is_a?(Integer)
+          delta = Integer(delta)
+          check_frozen!
+        end
+        change(delta)
+        self
+      end
+
+      def decrement(delta = 1)
+        check_frozen!
+        unless delta.is_a?(Integer)
+          delta = Integer(delta)
+          check_frozen!
+        end
+        change(-delta)
+        self
+      end
+
+      alias value get
+      alias value= store
+
+      def change_signal = @signal
+
+      private
+
+      def check_frozen!
+        raise FrozenError.new("can't modify frozen #{self.class}", receiver: self) if frozen?
+      end
+
+      def change(delta)
+        loop do
+          old_value = @reference.get
+          new_value = old_value + delta
+          if @reference.compare_and_set(old_value, new_value)
+            @signal.broadcast
+            return new_value
+          end
+        end
+      end
+
+      def initialize_copy(other)
+        @signal = Signal.new
+        @initial = other.initial
+        @reference = TruffleRuby::AtomicReference.new(other.value)
+      end
+    end
+  end
+end

data/lib/farce/engine/truffleruby/native/flag.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Flag
+      def initialize(value = false) # rubocop:disable Style/OptionalBooleanParameter
+        raise "Flag is already initialized" if defined?(@reference)
+        check_frozen!
+        @reference = TruffleRuby::AtomicReference.new(validate_boolean(value, "initial value"))
+      end
+
+      def value = @reference.get
+
+      def set # rubocop:disable Naming/PredicateMethod
+        check_frozen!
+        @reference.set(true)
+        true
+      end
+
+      def unset # rubocop:disable Naming/PredicateMethod
+        check_frozen!
+        @reference.set(false)
+        false
+      end
+
+      def store(value)
+        check_frozen!
+        value = validate_boolean(value, "value")
+        @reference.set(value)
+        value
+      end
+
+      def swap(value)
+        check_frozen!
+        value = validate_boolean(value, "value")
+        @reference.get_and_set(value)
+      end
+
+      def compare_and_set(expected_value, replacement_value)
+        check_frozen!
+        expected_value    = validate_boolean(expected_value, "expected value")
+        replacement_value = validate_boolean(replacement_value, "replacement value")
+        @reference.compare_and_set(expected_value, replacement_value)
+      end
+
+      def toggle
+        check_frozen!
+        loop do
+          current = @reference.get
+          replacement = !current
+          return replacement if @reference.compare_and_set(current, replacement)
+        end
+      end
+
+      alias get value
+      alias value= store
+
+      private
+
+      def check_frozen!
+        raise FrozenError.new("can't modify frozen #{self.class}", receiver: self) if frozen?
+      end
+
+      def validate_boolean(value, name)
+        return value if value.equal?(true) || value.equal?(false)
+        raise ArgumentError, "#{name} must be true or false"
+      end
+
+      def initialize_copy(other)
+        @reference = TruffleRuby::AtomicReference.new(other.value)
+      end
+    end
+  end
+end

data/lib/farce/engine/truffleruby/native/ordered_array_support.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Low-level operations shared by native TruffleRuby's ordered arrays.
+    # Bound primitive methods protect stored String snapshots and identity
+    # checks from user overrides.
+    module TruffleOrderedArraySupport
+      INTERRUPT_IMMEDIATE          = { Exception => :immediate }.freeze
+      BASIC_OBJECT_EQUAL           = BasicObject.instance_method(:equal?)
+      CLASS_ALLOCATE               = Class.instance_method(:allocate)
+      OBJECT_CLASS                 = Object.instance_method(:class)
+      OBJECT_FREEZE                = Object.instance_method(:freeze)
+      OBJECT_FROZEN                = Object.instance_method(:frozen?)
+      OBJECT_INSTANCE_VARIABLES    = Object.instance_method(:instance_variables)
+      OBJECT_INSTANCE_VARIABLE_GET = Object.instance_method(:instance_variable_get)
+      OBJECT_INSTANCE_VARIABLE_SET = Object.instance_method(:instance_variable_set)
+      OBJECT_IS_A                  = Object.instance_method(:is_a?)
+      STRING_INITIALIZE_COPY       = String.instance_method(:initialize_copy)
+      STRING_UMINUS                = String.instance_method(:-@)
+
+      private_constant :BASIC_OBJECT_EQUAL, :CLASS_ALLOCATE, :OBJECT_CLASS, :OBJECT_FREEZE,
+        :OBJECT_FROZEN, :OBJECT_INSTANCE_VARIABLES,
+        :OBJECT_INSTANCE_VARIABLE_GET, :OBJECT_INSTANCE_VARIABLE_SET,
+        :OBJECT_IS_A, :STRING_INITIALIZE_COPY, :STRING_UMINUS
+
+      private
+
+      def primitive_freeze(object)          = OBJECT_FREEZE.bind_call(object)
+      def primitive_frozen?(object)         = OBJECT_FROZEN.bind_call(object)
+      def primitive_is_a?(object, klass)    = OBJECT_IS_A.bind_call(object, klass)
+      def primitive_identical?(left, right) = BASIC_OBJECT_EQUAL.bind_call(left, right)
+
+      def canonical_ordered_key(key)
+        return key unless primitive_is_a?(key, String)
+        return STRING_UMINUS.bind_call(key) if
+          primitive_identical?(OBJECT_CLASS.bind_call(key), String)
+
+        snapshot_ordered_key(key)
+      end
+
+      def snapshot_ordered_key(key)
+        return key unless primitive_is_a?(key, String)
+
+        copy = CLASS_ALLOCATE.bind_call(OBJECT_CLASS.bind_call(key))
+        STRING_INITIALIZE_COPY.bind_call(copy, key)
+        OBJECT_INSTANCE_VARIABLES.bind_call(key).each do |name|
+          value = OBJECT_INSTANCE_VARIABLE_GET.bind_call(key, name)
+          OBJECT_INSTANCE_VARIABLE_SET.bind_call(copy, name, value)
+        end
+        primitive_freeze(copy)
+      end
+
+      def without_async_interrupts(&)
+        Thread.handle_interrupt(INTERRUPT_MASK, &)
+      end
+
+      def with_interruptible_callbacks(&)
+        Thread.handle_interrupt(INTERRUPT_IMMEDIATE, &)
+      end
+    end
+    private_constant :TruffleOrderedArraySupport
+  end
+end

data/lib/farce/engine/truffleruby/native/priority_queue.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/truffleruby/native/ordered_array_support"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Synchronized minimum-priority queue for native TruffleRuby. Binary
+    # search locates a priority bucket, whose small Array preserves FIFO order.
+    class PriorityQueue
+      include TruffleOrderedArraySupport
+      include Freeze::Unfreezable
+
+      DEFAULT_CAPACITY = nil
+      EMPTY = Object.new.freeze
+      INITIALIZATION_LOCK = Mutex.new
+      private_constant :DEFAULT_CAPACITY, :EMPTY, :INITIALIZATION_LOCK
+
+      Bucket = Struct.new(:priority, :items)
+      TrackedItem = Struct.new(:value, :enqueued_at)
+      private_constant :Bucket, :TrackedItem
+
+      class State
+        attr_accessor :size, :sealed, :closed, :generation, :operation_owner
+        attr_reader :buckets, :capacity, :signal, :lock, :tracked_items, :track_age
+
+        def initialize(capacity:, signal:, lock:, track_age:)
+          @buckets = []
+          @capacity = capacity
+          @signal = signal
+          @lock = lock
+          @size = 0
+          @sealed = false
+          @closed = false
+          @track_age = track_age
+          @tracked_items = [] if track_age
+          @generation = 0
+          @operation_owner = nil
+        end
+      end
+      private_constant :State
+
+      def initialize(capacity: DEFAULT_CAPACITY, signal: nil, track_age: false)
+        ensure_initializable!
+        capacity = normalize_capacity(capacity)
+        signal = normalize_signal(signal)
+        prepared = State.new(capacity:, signal:, lock: Lock.new, track_age: track_age ? true : false)
+        commit_initialization(prepared)
+      end
+      private :initialize
+
+      def initialize_copy(_other)
+        raise TypeError, "priority queues cannot be copied"
+      end
+
+      def push(priority, value)
+        state = initialized_state
+        with_queue_operation(state) do
+          raise_closed if state.closed
+          raise_sealed if state.sealed
+          next false if state.capacity && state.size >= state.capacity
+
+          stored = state.track_age ? TrackedItem.new(value, Clock.now) : value
+
+          index, found = locate_priority(state.buckets, priority)
+          if found
+            bucket = state.buckets[index]
+            prepared_items = bucket.items.dup << stored
+            notify_and_commit(state) do
+              bucket.items = prepared_items
+              state.size += 1
+              track_push(state, stored)
+            end
+          else
+            pending = Bucket.new(snapshot_ordered_key(priority), [stored])
+            notify_and_commit(state) do
+              index, duplicate = with_interruptible_callbacks do
+                locate_priority(state.buckets, priority)
+              end
+              raise "priority comparator changed during insertion" if duplicate
+              state.buckets.insert(index, pending)
+              state.size += 1
+              track_push(state, stored)
+            end
+          end
+          true
+        end
+      end
+
+      def pop(&fallback)
+        pop_endpoint(last: false, fallback:)
+      end
+
+      def pop_last(&fallback)
+        pop_endpoint(last: true, fallback:)
+      end
+
+      def pop_before(latest_priority, &fallback)
+        pop_endpoint(last: false, fallback:, latest_priority:)
+      end
+
+      def peek(&fallback)
+        read_endpoint(:value, last: false, fallback:)
+      end
+
+      def peek_last(&fallback)
+        read_endpoint(:value, last: true, fallback:)
+      end
+
+      def peek_priority(&fallback)
+        read_endpoint(:priority, last: false, fallback:)
+      end
+
+      def peek_last_priority(&fallback)
+        read_endpoint(:priority, last: true, fallback:)
+      end
+
+      def delete(priority, value)
+        delete_value(priority, value, identity: false)
+      end
+
+      def delete_identity(priority, value)
+        delete_value(priority, value, identity: true)
+      end
+
+      def delete_match(priority, pattern)
+        delete_value(priority, pattern, identity: false, match: true)
+      end
+
+      def size
+        state = initialized_state
+        with_queue_operation(state) { state.size }
+      end
+
+      def empty?
+        state = initialized_state
+        with_queue_operation(state) { state.size.zero? } # rubocop:disable Style/ZeroLengthPredicate
+      end
+
+      def capacity = initialized_state.capacity
+
+      def clear
+        state = initialized_state
+        with_queue_operation(state) do
+          notify_and_commit(state) do
+            state.buckets.clear
+            state.generation += 1 if state.track_age && state.size.positive?
+            state.size = 0
+            state.tracked_items&.clear
+            state.closed = true if state.sealed
+          end
+          self
+        end
+      end
+
+      def close
+        state = initialized_state
+        with_queue_operation(state) do
+          notify_and_commit(state) do
+            state.generation += 1 if state.track_age && !state.closed
+            state.sealed = true
+            state.closed = true
+          end
+          self
+        end
+      end
+
+      def closed?
+        state = initialized_state
+        with_queue_operation(state) { state.closed }
+      end
+
+      def sealed?
+        state = initialized_state
+        with_queue_operation(state) { state.sealed }
+      end
+
+      def age_tracking? = initialized_state.track_age
+
+      def generation
+        state = initialized_state
+        with_queue_operation(state) { state.track_age ? state.generation : nil }
+      end
+
+      def oldest_enqueued_at
+        state = initialized_state
+        with_queue_operation(state) { state.tracked_items&.first&.enqueued_at }
+      end
+
+      def oldest_age
+        timestamp = oldest_enqueued_at
+        Clock.now - timestamp if timestamp
+      end
+
+      def seal
+        state = initialized_state
+        with_queue_operation(state) do
+          notify_and_commit(state) do
+            unless state.sealed
+              state.sealed = true
+              state.generation += 1 if state.track_age
+            end
+            state.closed = true if state.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+          end
+          self
+        end
+      end
+
+      private
+
+      def pop_endpoint(last:, fallback:, latest_priority: UNDEFINED)
+        state = initialized_state
+        result = with_queue_operation(state) do
+          raise_closed if state.closed
+          bucket = last ? state.buckets.last : state.buckets.first
+          next EMPTY unless bucket
+          if !UNDEFINED.equal?(latest_priority) && compare_priorities(bucket.priority, latest_priority).positive?
+            next EMPTY
+          end
+
+          stored = bucket.items.first
+          prepared_items = bucket.items.drop(1)
+          notify_and_commit(state) do
+            if prepared_items.empty?
+              last ? state.buckets.pop : state.buckets.shift
+            else
+              bucket.items = prepared_items
+            end
+            state.size -= 1
+            track_remove(state, stored)
+            state.closed = true if state.sealed && state.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+          end
+          tracked_value(state, stored)
+        end
+        return result unless EMPTY.equal?(result)
+        fallback&.call
+      end
+
+      def ensure_initializable!
+        raise "priority queue is already initialized" if @state
+        raise FrozenError, "can't modify frozen priority queue" if primitive_frozen?(self)
+      end
+
+      def commit_initialization(prepared)
+        INITIALIZATION_LOCK.synchronize do
+          raise "priority queue is already initialized" if @state
+          raise FrozenError, "can't modify frozen priority queue" if primitive_frozen?(self)
+
+          without_async_interrupts do
+            @state = prepared
+            primitive_freeze(self)
+          end
+        end
+        self
+      end
+
+      def initialized_state
+        @state || raise("uninitialized priority queue")
+      end
+
+      def normalize_capacity(capacity)
+        return nil if capacity.nil?
+        capacity = capacity.to_int unless primitive_is_a?(capacity, Integer)
+        raise TypeError, "capacity must be an Integer or nil" unless primitive_is_a?(capacity, Integer)
+        raise ArgumentError, "capacity must be positive or nil" unless capacity.positive?
+        capacity
+      end
+
+      def normalize_signal(signal)
+        return if signal.nil?
+        raise TypeError, "signal must respond to #broadcast" unless signal.respond_to?(:broadcast)
+        signal
+      end
+
+      def with_queue_operation(state)
+        current = Fiber.current
+        raise ThreadError, "deadlock; recursive priority queue access" if
+          primitive_identical?(state.operation_owner, current)
+
+        state.lock.synchronize do
+          without_async_interrupts { state.operation_owner = current }
+          yield
+        ensure
+          without_async_interrupts do
+            state.operation_owner = nil if primitive_identical?(state.operation_owner, current)
+          end
+        end
+      end
+
+      def read_endpoint(kind, last:, fallback:)
+        state = initialized_state
+        result = with_queue_operation(state) do
+          raise_closed if state.closed
+          bucket = last ? state.buckets.last : state.buckets.first
+          next EMPTY unless bucket
+          kind == :priority ? bucket.priority : tracked_value(state, bucket.items.first)
+        end
+        EMPTY.equal?(result) ? fallback&.call : result
+      end
+
+      def delete_value(priority, value, identity:, match: false)
+        state = initialized_state
+        with_queue_operation(state) do
+          raise_closed if state.closed
+          bucket_index, found = locate_priority(state.buckets, priority)
+          next false unless found
+
+          bucket = state.buckets[bucket_index]
+          item_index = if identity
+                         bucket.items.index { primitive_identical?(tracked_value(state, it), value) }
+                       elsif match
+                         bucket.items.index { value === tracked_value(state, it) } # rubocop:disable Style/CaseEquality
+                       else
+                         bucket.items.index { tracked_value(state, it) == value }
+                       end
+          next false unless item_index
+
+          removed = bucket.items[item_index]
+          prepared_items = bucket.items.dup
+          prepared_items.delete_at(item_index)
+          notify_and_commit(state) do
+            if prepared_items.empty?
+              state.buckets.delete_at(bucket_index)
+            else
+              bucket.items = prepared_items
+            end
+            state.size -= 1
+            track_remove(state, removed)
+            state.closed = true if state.sealed && state.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+          end
+          true
+        end
+      end
+
+      def locate_priority(buckets, priority)
+        low = 0
+        high = buckets.length
+        while low < high
+          middle = (low + high) / 2
+          order = compare_priorities(priority, buckets[middle].priority)
+          return [middle, true] if order.zero?
+          order.negative? ? high = middle : low = middle + 1
+        end
+        [low, false]
+      end
+
+      def compare_priorities(left, right)
+        result = left <=> right
+        raise ArgumentError, "priority comparison failed" if result.nil?
+        # rb_cmpint calls #> and #< when <=> returns a non-Integer object.
+        return 1 if result > 0 # rubocop:disable Style/NumericPredicate
+        return -1 if result < 0 # rubocop:disable Style/NumericPredicate
+        0
+      end
+
+      def notify_and_commit(state)
+        without_async_interrupts do
+          with_interruptible_callbacks { state.signal.broadcast } if state.signal
+          yield
+        end
+      end
+
+      def tracked_value(state, item) = state.track_age ? item.value : item
+
+      def track_push(state, item)
+        return unless state.track_age
+        state.tracked_items << item
+        state.generation += 1
+      end
+
+      def track_remove(state, item)
+        return unless state.track_age
+        state.tracked_items.delete(item)
+        state.generation += 1
+      end
+
+      def raise_closed
+        raise ::Farce::ClosedQueueError, "queue is closed"
+      end
+
+      def raise_sealed
+        raise ::Farce::SealedQueueError, "queue is sealed"
+      end
+    end
+  end
+end

data/lib/farce/engine/truffleruby/native/tree_map.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/truffleruby/native/unsafe_tree_map"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Synchronized native-TruffleRuby map. Storage and ordered operations come
+    # from UnsafeTreeMap; this subclass adds coordination and guarded mutability.
+    class TreeMap < UnsafeTreeMap
+      def transaction_snapshot
+        state = initialized_state
+        entries, revision = with_map_operation(state, mutation: false) do
+          [state.entries.map { Entry.new(it.key, it.value) }, state.revision]
+        end
+        working = self.class.new
+        working.instance_variable_get(:@state).instance_variable_set(:@entries, entries)
+        PortableTransaction::TreeEntry.new(self, working, revision, state.lock, :@entries)
+      end
+
+      private
+
+      def synchronized?                  = true
+      def operation_lock                 = Lock.new
+      def ensure_mutation_still_allowed! = Internal::Freeze.check(self)
+
+      def with_map_operation(state, mutation:)
+        current = Fiber.current
+        raise ThreadError, "deadlock; recursive tree map access" if
+          primitive_identical?(state.operation_owner, current)
+
+        state.lock.synchronize do
+          ensure_mutation_still_allowed! if mutation
+          without_async_interrupts { state.operation_owner = current }
+          yield
+        ensure
+          without_async_interrupts do
+            state.operation_owner = nil if primitive_identical?(state.operation_owner, current)
+          end
+        end
+      end
+    end
+
+    MutableTreeMap = TreeMap
+
+    # No Ractors, no problems :)
+    ShareableTreeMap = TreeMap
+  end
+end