farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/internal/portable_transaction/strong_map_size_entry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    module PortableTransaction
+      # Validate a size-only read without comparing values. Keep the index locked
+      # through publication so additions and removals wait. Cells created after
+      # preparation use temporary locks. A live absent cell remains reserved by
+      # its initializer and invalidates the attempt. Present or retired cells
+      # cannot change membership without the index lock.
+      class StrongMapSizeEntry < StrongMapEntry
+        def initialize(source, size)
+          super(source, nil, :strong_map, size)
+        end
+
+        def prepare
+          capture_cells
+          @cell_locks = {}.compare_by_identity
+          @cells.each { @cell_locks[it.instance_variable_get(:@mutex)] = true }
+        end
+
+        def valid?
+          return false if @index_lock.instance_variable_get(:@reserved)
+          current  = @index.instance_variable_get(:@entries).compact
+          acquired = []
+          begin
+            current.each do |cell|
+              lock = cell.instance_variable_get(:@mutex)
+              next if @cell_locks.key?(lock)
+              return false unless lock.try_lock
+              acquired << lock
+            end
+            return false if current.any? { it.instance_variable_get(:@reserved) }
+            current.count { !it.instance_variable_get(:@retired) && it.instance_variable_get(:@present) } == @baseline
+          ensure
+            acquired.reverse_each(&:unlock)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/portable_transaction/tree_entry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    module PortableTransaction
+      # Keep the state object and lock stable for ordinary operations already
+      # waiting on them. Only replace storage under that existing lock.
+      class TreeEntry < Entry
+        def initialize(source, working, revision, lock, field) # rubocop:disable Lint/MissingSuper
+          @source = source
+          @working = working
+          @state = source.instance_variable_get(:@state)
+          @baseline = revision
+          @locks = [lock]
+          @field = field
+          @dirty = @applied = false
+        end
+
+        def prepare
+          state = @working.instance_variable_get(:@state)
+          @replacement = @field == :tree ? state.tree : state.entries
+          @next_version = @baseline + 1
+        end
+
+        def valid?
+          return false if @dirty && @source.frozen?
+          owner = if @field == :tree
+                    @source.instance_variable_get(:@guard).instance_variable_get(:@owner)
+                  else
+                    @state.operation_owner
+                  end
+          return false if owner || @state.revision != @baseline
+          @original = @field == :tree ? @state.tree : @state.entries
+          true
+        end
+
+        def apply
+          return unless @dirty
+          @applied = true
+          replace(@replacement, @next_version)
+        end
+
+        def restore
+          replace(@original, @baseline) if @applied
+        end
+
+        def notify = nil
+
+        private
+
+        def replace(storage, revision)
+          if @field == :tree
+            @state.tree = storage
+          else
+            @state.instance_variable_set(:@entries, storage)
+          end
+          @state.revision = revision
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/portable_transaction.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Portable commits use existing mutexes. Validation compares original
+    # storage by identity without invoking user equality or hash callbacks.
+    module PortableTransaction
+      include Autoloads
+
+      def self.same?(left, right) = BasicObject.instance_method(:equal?).bind_call(left, right)
+
+      def self.snapshot(source, kind)
+        case kind
+        when :atom
+          value, version = source.instance_variable_get(:@mutex).synchronize do
+            [source.instance_variable_get(:@value), source.instance_variable_get(:@version)]
+          end
+          working = source.class.new(value, compare_by_identity: source.compare_by_identity?)
+          Entry.new(source, working, kind, version)
+        when :vector
+          values = source.snapshot
+          working = source.class.new(values, compare_by_identity: source.compare_by_identity?)
+          Entry.new(source, working, kind, values)
+        when :map, :strong_map
+          pairs = source.transaction_pairs
+          working = source.class.new(
+            compare_keys_by_identity:   source.compare_keys_by_identity?,
+            compare_values_by_identity: source.compare_values_by_identity?,
+          )
+          pairs.each { |key, value| working[key] = value }
+          baseline = {}.compare_by_identity
+          pairs.each { |key, value| baseline[key] = value }
+          entry_class = kind == :strong_map ? StrongMapEntry : Entry
+          entry_class.new(source, working, kind, baseline)
+        end
+      end
+
+      def self.commit(entries, guards = [])
+        entries.each(&:prepare)
+        locks = entries.flat_map(&:locks).uniq.sort_by(&:object_id)
+        acquired = []
+        begin
+          locks.each do |lock|
+            return false unless lock.try_lock
+            acquired << lock
+          end
+          return false if guards.any?(&:value)
+          return false unless entries.all?(&:valid?)
+          begin
+            entries.each(&:apply)
+            unless !block_given? || yield
+              entries.reverse_each(&:restore)
+              return false
+            end
+          rescue Exception # rubocop:disable Lint/RescueException -- restore before propagating any interruption
+            entries.reverse_each(&:restore)
+            raise
+          end
+          true
+        ensure
+          acquired.reverse_each(&:unlock)
+        end
+      end
+
+      class Entry
+        attr_reader :working, :locks
+
+        def initialize(source, working, kind, baseline)
+          @source   = source
+          @working  = working
+          @kind     = kind
+          @baseline = baseline
+          @dirty    = false
+          @applied  = false
+          @field    = { atom: :@value, vector: :@values, map: :@map }.fetch(kind)
+          @locks    = if kind == :map
+                        %i[@reservation_mutex @state_mutex].map { source.instance_variable_get(it) }
+                      else
+                        [source.instance_variable_get(:@mutex)]
+                      end
+        end
+
+        def write!
+          @dirty = true
+        end
+
+        def prepare
+          @replacement = @working.instance_variable_get(@field)
+          @next_version = @baseline + 1 if @kind == :atom
+        end
+
+        def valid?
+          frozen = @kind == :map ? @source.frozen? : @source.instance_variable_get(:@farce_frozen)
+          return false if @dirty && frozen
+          @original = @source.instance_variable_get(@field)
+          case @kind
+          when :atom
+            !@source.instance_variable_get(:@updating) &&
+              @source.instance_variable_get(:@version) == @baseline
+          when :vector
+            !@source.instance_variable_get(:@updating) && @original.size == @baseline.size &&
+              @baseline.each_index.all? { PortableTransaction.same?(@original[it], @baseline[it]) }
+          when :map
+            return false unless @source.transaction_idle?
+            pairs = @source.transaction_pairs
+            pairs.size == @baseline.size && pairs.all? do |key, value|
+              @baseline.key?(key) && PortableTransaction.same?(@baseline[key], value)
+            end
+          end
+        end
+
+        def apply
+          return unless @dirty
+          @applied = true
+          @source.instance_variable_set(@field, @replacement)
+          @source.instance_variable_set(:@version, @next_version) if @kind == :atom
+        end
+
+        # CRuby's Array iteration captures storage without its Ruby mutex.
+        # Hide provisional replacements from newly starting iterators.
+        def reserve
+          return unless @kind == :vector
+          @reserved = true
+          @source.instance_variable_set(:@updating, :transaction)
+        end
+
+        def unreserve
+          return unless @reserved
+          @source.instance_variable_set(:@updating, false)
+          @reserved = false
+        end
+
+        def restore
+          return unless @applied
+          @source.instance_variable_set(@field, @original)
+          @source.instance_variable_set(:@version, @baseline) if @kind == :atom
+        end
+
+        def notify
+          return unless @dirty
+          signal = @source.instance_variable_get(@kind == :map ? :@change_signal : :@signal)
+          if @kind == :atom
+            @locks.first.synchronize { signal.broadcast }
+          else
+            signal.broadcast
+          end
+        end
+      end
+
+      # Validate only cardinality while ordinary map mutations are excluded by
+      # the existing reservation and state locks. This entry never publishes data.
+      class MapSizeEntry < Entry
+        def initialize(source, size)
+          super(source, nil, :map, size)
+        end
+
+        def prepare = nil
+        def valid?  = @source.transaction_idle? && @source.size == @baseline
+      end
+    end
+  end
+end

data/lib/farce/internal/proxy_owner_notifications.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Close proxy channels when their owner exits, without retaining unused proxies.
+    module ProxyOwnerNotifications
+      def initialize
+        @alive = Flag.new(true)
+        @supervisors = Strict::Map.new(compare_by_identity: true)
+      end
+
+      def alive? = @alive.value
+
+      def register(supervisor)
+        @supervisors[supervisor] = true
+        supervisor.stop unless alive?
+      end
+
+      def unregister(supervisor) = @supervisors.delete(supervisor)
+
+      def stop
+        @alive.value = false
+        @supervisors.each_key(&:stop)
+      end
+    end
+  end
+end

data/lib/farce/internal/reservation_waiting.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Keep reservation waits cancelable without shortening their overall deadline.
+    module ReservationWaiting
+      def self.wait(signal, generation, deadline)
+        while true
+          remaining = deadline - Clock.now if deadline
+          return false if remaining && !remaining.positive?
+
+          # LeaseWaiting supplies the full remaining timeout on default engines
+          # and short cancellation slices on JRuby. Reuse that existing hook
+          # without changing how other Signal users wait.
+          interval = LeaseWaiting.wait_interval(remaining)
+          return true if signal.wait(generation, timeout: interval) { false }
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/scheduled_task.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A shareable task and its transferred arguments.
+    class ScheduledTask
+      include Internal::Copyable
+      include Shareable::Immutable
+
+      MANAGER = ModeManager.new
+
+      def initialize(args, block, mode)
+        @block  = Ractor.shareable_proc(&block)
+        @unwrap = false
+        @args   = args.map! do |arg|
+          wrapped = MANAGER.wrap(arg, mode:)
+          @unwrap = true if MANAGER.managed_envelope?(wrapped)
+          wrapped
+        end.freeze
+        super()
+      end
+
+      def to_proc(completion = nil)
+        if completion
+          if @unwrap
+            lambda do
+              @block.call(*@args.map { |arg| MANAGER.unwrap(arg) })
+            ensure
+              completion.task_finished
+            end
+          else
+            lambda do
+              @block.call(*@args)
+            ensure
+              completion.task_finished
+            end
+          end
+        elsif @unwrap
+          -> { @block.call(*@args.map { |arg| MANAGER.unwrap(arg) }) }
+        else
+          -> { @block.call(*@args) }
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/scheduler_io.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+require "fcntl"
+require "socket"
+require "io/nonblock"
+
+module Farce
+  module Internal
+    # IO hooks and helpers shared by the scheduler implementations.
+    module SchedulerIO
+      def io_select(readers = nil, writers = nil, errors = nil, timeout = nil)
+        check_fiber
+        timeout = duration_value(timeout)
+        groups  = [readers, writers, errors].map { |list| list.nil? ? [] : list.to_ary.dup }
+        ios     = groups.map { |list| list.map(&:to_io) }
+        check_fiber # to_ary/to_io can run arbitrary Ruby
+
+        found = select_result(groups, ios, 0)
+        return checkpoint_result(found) if found || timeout&.zero?
+        token = arm_wait
+
+        register_select(token, groups, ios)
+        wait_with_timeout(token, timeout, nil)
+      ensure
+        retire_wait(token) if token
+      end
+
+      SINGLE_TRANSFER = defined?(IO::Buffer::VERSION) && IO::Buffer::VERSION >= 3
+      private_constant :SINGLE_TRANSFER
+
+      if SINGLE_TRANSFER
+        def io_pread(io, buffer, file_offset, offset, length)
+          positional_io(false, io, buffer, length, file_offset, offset, single_transfer: true)
+        end
+
+        def io_pwrite(io, buffer, file_offset, offset, length)
+          positional_io(true, io, buffer, length, file_offset, offset, single_transfer: true)
+        end
+      else
+        def io_pread(io, buffer, file_offset, minimum, offset = 0)
+          positional_io(false, io, buffer, minimum, file_offset, offset)
+        end
+
+        def io_pwrite(io, buffer, file_offset, minimum, offset = 0)
+          positional_io(true, io, buffer, minimum, file_offset, offset)
+        end
+      end
+
+      private
+
+      def owner_thread = Thread.current
+      def start_fiber(fiber) = fiber.resume
+      def policy_changed = nil
+      def dispatch_budget = 256
+      def finish_fiber = nil
+      def begin_close = nil
+      def begin_shutdown = nil
+
+      def select_snapshot(groups, timeout)
+        Fiber.blocking { IO.select(*groups, timeout) }
+      end
+
+      # Coercion belongs to admission. A mutable wrapper must not switch the IO
+      # being observed after its wait has been registered.
+      def select_result(groups, ios, timeout)
+        selected = select_snapshot(ios, timeout)
+        return unless selected
+        identities = selected.map do |list|
+          list.each_with_object({}.compare_by_identity) { |io, set| set[io] = true }
+        end
+        groups.each_with_index.map do |list, i|
+          list.each_with_index.filter_map { |object, j| object if identities[i].key?(ios[i][j]) }
+        end
+      end
+
+      def readiness(result)
+        return 0 unless result
+        (result[0].empty? ? 0 : IO::READABLE) |
+          (result[1].empty? ? 0 : IO::WRITABLE) |
+          (result[2].empty? ? 0 : IO::PRIORITY)
+      end
+
+      def transfer_arguments(io, buffer, minimum, offset, writing)
+        check_fiber
+        io = io.to_io
+        minimum, offset = Integer(minimum), Integer(offset)
+        check_fiber
+        io.fileno
+        raise ArgumentError, "minimum and offset exceed buffer size" if
+          minimum.negative? || offset.negative? || offset > buffer.size || minimum > buffer.size - offset
+        raise IO::Buffer::AccessError, "buffer is readonly" if !writing && buffer.readonly?
+        [io, minimum, offset]
+      end
+
+      def locked_buffer(buffer, &work)
+        !SINGLE_TRANSFER && buffer.locked? ? work.call : buffer.locked(&work)
+      end
+
+      def duplicate_io(io, writing)
+        # IO#dup flushes Ruby's buffers. During an io_write hook that would flush
+        # the same payload twice. Duplicate the descriptor below Ruby buffering.
+        Fiber.blocking do
+          copy = IO.for_fd(io.fcntl(Fcntl::F_DUPFD, 0), writing ? "w" : "r")
+          copy.close_on_exec = true
+          copy
+        end
+      end
+
+      def positional_io(writing, io, buffer, minimum, file_offset, offset, single_transfer: false)
+        io, minimum, offset = transfer_arguments(io, buffer, minimum, offset, writing)
+        file_offset = Integer(file_offset)
+        check_fiber
+        locked_buffer(buffer) do
+          copy = duplicate_io(io, writing)
+          capacity = single_transfer ? minimum : buffer.size - offset
+          minimum = capacity.zero? ? 0 : 1 if single_transfer
+          data = buffer.get_string(offset, capacity) if writing
+          value = background do
+            worker_transfer(copy, writing, data, capacity, minimum, file_offset)
+          end
+          if writing || value.is_a?(Integer)
+            value
+          else
+            buffer.set_string(value, offset)
+            value.bytesize
+          end
+        ensure
+          copy&.close
+        end
+      end
+
+      # File workers own copies. A cancelled caller waits for acknowledgement
+      # before its ensure closes the duplicated IO or releases any borrowed state.
+      def file_transfer(writing, io, buffer, minimum, offset, capacity = buffer.size - offset)
+        copy = duplicate_io(io, writing)
+        data = buffer.get_string(offset, capacity) if writing
+        value = background do
+          worker_transfer(copy, writing, data, capacity, minimum)
+        end
+        return value if writing || value.is_a?(Integer)
+        buffer.set_string(value, offset)
+        value.bytesize
+      ensure
+        copy&.close
+      end
+
+      def worker_transfer(io, writing, data, capacity, minimum, position = nil)
+        total = 0
+        output = +"".b
+        return writing ? 0 : output if capacity.zero?
+        loop do
+          remaining = capacity - total
+          if writing
+            chunk = data.byteslice(total, remaining)
+            amount = position ? io.pwrite(chunk, position + total) : io.syswrite(chunk)
+          else
+            chunk = position ? io.pread(remaining, position + total) : io.sysread(remaining)
+            output << chunk
+            amount = chunk.bytesize
+          end
+          total += amount
+          break if amount.zero? || total >= minimum
+        end
+        writing ? total : output
+      rescue EOFError
+        output
+      rescue SystemCallError => e
+        total.positive? ? (writing ? total : output) : -e.errno
+      end
+    end
+  end
+end