farce 0 → 0.1.0

data/lib/farce/transaction/map_operations.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # Implements the staged reads and writes shared by Map and TreeMap wrappers.
+    #
+    # The participant supplies key normalization and value transfer rules.
+    # Operations use the backend snapshot enrolled in the transaction, so they
+    # see earlier staged writes without modifying the participant before commit.
+    #
+    # @!visibility private
+    module MapOperations # :nodoc: all
+      include Wrapper
+
+      READ_HELPERS = %i[
+        assoc compare_by_identity? dig length value? has_value? key rassoc has_key? member? include?
+        fetch_values to_a to_h to_hash deconstruct_keys values_at weak_keys? weak_values? inspect to_s
+        pretty_print values flatten to_proc
+      ].freeze
+
+      def [](key) = access { unwrap_stored(@working[prepare(key)]) }
+
+      def []=(key, value)
+        store(key, value)
+      end
+
+      def fetch(key, *defaults)
+        access do
+          raise ArgumentError, "expected at most one default" if defaults.size > 1
+          canonical = prepare(key)
+          next unwrap_stored(@working[canonical]) if @working.key?(canonical)
+          next yield(key) if block_given?
+          next defaults.first unless defaults.empty?
+          raise KeyError.new("key not found: #{key.inspect}", receiver: @object, key:)
+        end
+      end
+
+      def compare_keys_by_identity?    = access { @object.compare_keys_by_identity? }
+      def compare_values_by_identity?  = access { @object.compare_values_by_identity? }
+      def delete(key)                  = write { unwrap_stored(@working.delete(prepare(key))) }
+      def empty?                       = size.zero?
+      def get(key)                     = self[key]
+      def getkey(key)                  = access { @working.getkey(prepare(key)) }
+      def key?(key)                    = access { @working.key?(prepare(key)) }
+      def keys                         = access { @working.keys }
+      def shareable_keys?              = access { @object.shareable_keys? }
+      def shareable_values?            = access { @object.shareable_values? }
+      def size                         = access { @working.size }
+      def store(key, value, mode: nil) = write { unwrap_stored(store_value(prepare(key), wrap(value, mode:))) }
+      def swap(key, value, mode: nil)  = write { unwrap_stored(@working.swap(prepare(key), wrap(value, mode:))) }
+
+      def each
+        return enum_for(__method__) unless block_given?
+        access { @working.each { |key, value| yield key, unwrap_stored(value) } }
+        self
+      end
+      alias each_pair each
+      alias each_live each
+
+      def clear
+        write { @working.clear }
+        self
+      end
+
+      def update(key, mode: nil)
+        require_block!(block_given?)
+        write do
+          canonical = prepare(key)
+          unwrap_stored(store_value(canonical, wrap(yield(unwrap_stored(@working[canonical])), mode:)))
+        end
+      end
+
+      def store_if_absent(key, mode: nil)
+        require_block!(block_given?)
+        write do
+          canonical = prepare(key)
+          next unwrap_stored(@working[canonical]) if @working.key?(canonical)
+          unwrap_stored(store_value(canonical, wrap(yield, mode:)))
+        end
+      end
+
+      def upsert(key, initial, mode: nil)
+        require_block!(block_given?)
+        write do
+          canonical = prepare(key)
+          value = @working.key?(canonical) ? yield(unwrap_stored(@working[canonical])) : initial
+          unwrap_stored(store_value(canonical, wrap(value, mode:)))
+        end
+      end
+
+      def compare_and_set(key, expected, replacement, mode: nil)
+        write do
+          canonical = prepare(key)
+          next compared(@working.compare_and_set(canonical, expected, replacement)) unless @manager
+          next compared(false) unless @working.key?(canonical) &&
+            matches?(@working[canonical], expected, identity: @object.compare_values_by_identity?)
+          store_value(canonical, wrap(replacement, mode:))
+          true
+        end
+      end
+
+      def each_key
+        return enum_for(__method__) { size } unless block_given?
+        each { |key, _| yield key }
+        self
+      end
+
+      def each_value
+        return enum_for(__method__) { size } unless block_given?
+        each { |_, value| yield value }
+        self
+      end
+
+      private
+
+      def store_value(key, value) = @working.store(key, value)
+
+      def modify_entry(key, canonical: false)
+        write do
+          key = prepare(key) unless canonical
+          present = @working.key?(key)
+          replacement = yield(present, present ? unwrap_stored(@working[key]) : nil)
+          next false if Internal::MAP_KEEP.equal?(replacement)
+          if Internal::MAP_DELETE.equal?(replacement)
+            @working.delete(key)
+            present
+          else
+            store_value(key, wrap(replacement))
+          end
+        end
+      end
+
+      def prepare(key)
+        return @backend.transaction_key(key) if @backend.respond_to?(:transaction_key)
+        @backend.respond_to?(:normalize_external_key) ? @backend.normalize_external_key(key) : key
+      end
+    end
+
+    private_constant :MapOperations
+  end
+end

data/lib/farce/transaction/molecule.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::Molecule Molecule} that is part of a transaction.
+    class Molecule < Abstract::Molecule
+      include Wrapper
+
+      # @api private
+      def initialize(transaction, object)
+        super
+        @members = object.members
+        @atoms = object.each_atom.to_h.transform_values { transaction[it] }
+        @fields = @members.to_h { [it, @atoms.fetch(:"#{it}_atom")] }
+        @writers = @members.to_h { [:"#{it}=", @atoms.fetch(:"#{it}_atom")] }
+        # A field named map or count must read its atom, not call the inherited
+        # Enumerable method. Define those readers before method_missing is needed.
+        @members.each do |field|
+          next unless Enumerable.method_defined?(field)
+          atom = @fields.fetch(field)
+          define_singleton_method(field) { access { atom.value } }
+        end
+      end
+
+      # (see Abstract::Molecule#compare_by_identity?)
+      # @see Abstract::Molecule#compare_by_identity?
+      def compare_by_identity? = access { @object.compare_by_identity? }
+
+      # (see Abstract::Molecule#members)
+      # @see Abstract::Molecule#members
+      def members = access { @members }
+
+      # (see Abstract::Molecule#atoms)
+      # @see Abstract::Molecule#atoms
+      def atoms = access { @atoms.keys.freeze }
+
+      # (see Abstract::Molecule#each)
+      # @see Abstract::Molecule#each
+      def each
+        return enum_for(__method__) unless block_given?
+        access { @members.each { yield it, @atoms.fetch(:"#{it}_atom").value } }
+        self
+      end
+      alias each_pair each
+
+      # (see Abstract::Molecule#each_atom)
+      # @see Abstract::Molecule#each_atom
+      def each_atom
+        return enum_for(__method__) unless block_given?
+        access { @atoms.each { yield _1, _2 } }
+        self
+      end
+
+      # (see Abstract::Molecule#each_member)
+      # @see Abstract::Molecule#each_member
+      def each_member
+        return enum_for(__method__) unless block_given?
+        access { @members.each { yield it } }
+        self
+      end
+      alias each_key each_member
+
+      # (see Abstract::Molecule#each_value)
+      # @see Abstract::Molecule#each_value
+      def each_value
+        return enum_for(__method__) unless block_given?
+        each { |_, value| yield value }
+        self
+      end
+
+      private
+
+      def method_missing(name, *arguments, **options, &block)
+        return access { @atoms.fetch(name) } if @atoms.key?(name) && arguments.empty? && options.empty? && !block
+        return super unless options.empty? && !block
+        return access { @fields.fetch(name).value } if @fields.key?(name) && arguments.empty?
+        return write { @writers.fetch(name).value = arguments.first } if @writers.key?(name) && arguments.size == 1
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @atoms.key?(name) || @fields.key?(name) || @writers.key?(name) || super
+      end
+
+      Wrapper.inherit(self, :compare_by_identity?)
+    end
+  end
+end

data/lib/farce/transaction/mutable.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Farce::Mutable} that stages method calls within a transaction.
+    #
+    # Reads use the attempt's current snapshot. Mutations replace only its staged
+    # value and are published with the other participants when the attempt commits.
+    # Snapshots must be frozen. Use a dedicated transaction participant for a
+    # shareable object whose state can change while it remains unfrozen.
+    class Mutable < Farce::Mutable
+      include Wrapper
+
+      # @api private
+      def initialize(transaction, object, backend)
+        super
+        @atom = Atom.new(transaction, object, backend)
+        return if @atom.value.frozen?
+        ::Kernel.raise(::TypeError, "mutable transactions require a frozen snapshot")
+      end
+
+      # @api private
+      def marshal_dump = ::Kernel.raise(::TypeError, "transaction wrappers cannot be marshaled")
+
+      # @api private
+      def respond_to?(name, include_private = false) # rubocop:disable Style/OptionalBooleanParameter
+        access { name != :freeze && super }
+      end
+
+      # @api private
+      def frozen? = access { @object.frozen? }
+
+      private
+
+      # Wrapper's error guards must raise locally rather than delegate to the value.
+      def raise(...) = ::Kernel.raise(...)
+
+      def method_missing(name, ...) # rubocop:disable Style/MissingRespondToMissing
+        access do
+          ::Kernel.raise(::NoMethodError, "transaction wrappers cannot be frozen") if name == :freeze
+          begin
+            @atom.value.__send__(name, ...)
+          rescue ::FrozenError
+            result = nil
+            @atom.update do |current|
+              copy = current.dup
+              result = copy.__send__(name, ...)
+              result = self if result.equal?(copy)
+              copy.freeze
+            end
+            result
+          end
+        end
+      end
+
+      Wrapper.inherit(self, :is_a?, :pretty_print_cycle)
+    end
+  end
+end

data/lib/farce/transaction/set.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::Set Set} that is part of a transaction.
+    #
+    # Membership reads and changes validate the members they access.
+    # Size reads validate cardinality. Enumeration captures the full set.
+    class Set < Abstract::Set
+      include SetOperations
+
+      Wrapper.inherit(self, *SetOperations::READ_HELPERS, writes: SetOperations::WRITE_HELPERS)
+    end
+  end
+end

data/lib/farce/transaction/set_operations.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # Initializes Set and SortedSet wrappers with a transactional backing map.
+    # Abstract::Set's methods operate directly on this wrapper's @map. The map
+    # owns the snapshot and commit logic. Only membership settings and transfer
+    # checks belong here, because some transfers change values before insertion.
+    # @!visibility private
+    module SetOperations # :nodoc: all
+      include Wrapper
+
+      READ_HELPERS = %i[
+        each size length empty? count include? member? === compare_by_identity? weak?
+        == eql? hash subset? proper_subset? superset? proper_superset? intersect? disjoint? <=>
+        <= < >= > join inspect to_s to_set each_stored equality_index ordered? public_stored
+      ].freeze
+      WRITE_HELPERS = %i[add << add? delete delete? clear merge subtract].freeze
+
+      def initialize(transaction, object, map)
+        super(transaction, object)
+        compose(:normalizer, :compare_by_identity, :manager, map:)
+        @value_modes = object.method(:value_modes?).call
+      end
+
+      def value_modes? = access { @value_modes }
+
+      private
+
+      def add_mode_value?(element, mode:)
+        selected = UNDEFINED.equal?(mode) || mode.nil? ? @manager.mode : mode
+        if %i[move make_shareable dedup proxy].include?(selected)
+          raise TypeError, "#{selected} transfers do not support transactions"
+        end
+        super
+      end
+
+      def unwrap_entry(key, entry)
+        raise TypeError, "move envelopes do not support transactions" if Envelope::Move === entry.payload
+        super
+      end
+    end
+
+    private_constant :SetOperations
+  end
+end

data/lib/farce/transaction/sorted_set.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::SortedSet SortedSet} that is part of a transaction.
+    class SortedSet < Abstract::SortedSet
+      include SetOperations
+
+      Wrapper.inherit(self, *SetOperations::READ_HELPERS, :ordered_keys, writes: SetOperations::WRITE_HELPERS)
+
+      # SortedSet builds temporary membership indexes for comparisons. Use the
+      # participant's map factory to retain support for mutable Local keys.
+      private def new_map(...) = @object.method(:new_map).call(...)
+    end
+  end
+end

data/lib/farce/transaction/tree_map.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::TreeMap TreeMap} that is part of a transaction.
+    class TreeMap < Abstract::TreeMap
+      include MapOperations
+
+      # (see Abstract::TreeMap#first_key)
+      # @see Abstract::TreeMap#first_key
+      def first_key = access { @working.first_key }
+
+      # (see Abstract::TreeMap#last_key)
+      # @see Abstract::TreeMap#last_key
+      def last_key = access { @working.last_key }
+
+      # (see Abstract::TreeMap#getkey)
+      # @see Abstract::TreeMap#getkey
+      def getkey(key) = access { @working.getkey(prepare(key)) }
+
+      # (see Abstract::TreeMap#keys)
+      # @see Abstract::TreeMap#keys
+      def keys = access { @working.each.map { |key, _| key }.freeze }
+
+      # (see Abstract::TreeMap#pop)
+      # @see Abstract::TreeMap#pop
+      def pop = write { public_pair(@working.pop) }
+
+      # (see Abstract::TreeMap#shift)
+      # @see Abstract::TreeMap#shift
+      def shift = write { public_pair(@working.shift) }
+
+      # (see Abstract::TreeMap#swap)
+      # @see Abstract::TreeMap#swap
+      def swap(key, value, mode: nil)
+        write do
+          canonical = prepare(key)
+          previous = unwrap_stored(@working[canonical])
+          store_value(canonical, wrap(value, mode:))
+          previous
+        end
+      end
+
+      # (see Abstract::TreeMap#compare_and_set)
+      # @see Abstract::TreeMap#compare_and_set
+      def compare_and_set(key, expected, replacement, mode: nil)
+        write do
+          canonical = prepare(key)
+          next compared(false) unless @working.key?(canonical)
+          current = @working[canonical]
+          matches = @manager ? matches?(current, expected, identity: false) : current == expected
+          next compared(false) unless matches
+          store_value(canonical, wrap(replacement, mode:))
+          true
+        end
+      end
+
+      private
+
+      def store_value(key, value)
+        @working[key] = value
+      end
+
+      def prepare(key)
+        normalizer = @object.instance_variable_get(:@key_normalizer)
+        @working.prepare_key(normalizer ? normalizer.call(key) : key)
+      end
+
+      def public_pair(pair)
+        [pair.first, unwrap_stored(pair.last)] if pair
+      end
+
+      Wrapper.inherit(self, *MapOperations::READ_HELPERS)
+    end
+  end
+end

data/lib/farce/transaction/vector.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Transaction
+    # A {Abstract::Vector Vector} that is part of a transaction.
+    class Vector < Abstract::Vector
+      include Wrapper
+
+      # (see Abstract::Vector#compare_by_identity?)
+      # @see Abstract::Vector#compare_by_identity?
+      def compare_by_identity? = access { @object.compare_by_identity? }
+
+      # (see Abstract::Vector#shareable_values?)
+      # @see Abstract::Vector#shareable_values?
+      def shareable_values? = access { @object.shareable_values? }
+
+      # (see Abstract::Vector#[])
+      # @see Abstract::Vector#[]
+      def [](index) = access { unwrap_stored(@working[index]) }
+
+      # (see Abstract::Vector#get)
+      # @see Abstract::Vector#get
+      def get(index) = self[index]
+
+      # (see Abstract::Vector#size)
+      # @see Abstract::Vector#size
+      def size = access { @working.size }
+
+      # (see Abstract::Vector#empty?)
+      # @see Abstract::Vector#empty?
+      def empty? = size.zero?
+
+      # (see Abstract::Vector#[]=)
+      # @see Abstract::Vector#[]=
+      def []=(index, value)
+        store(index, value)
+      end
+
+      # (see Abstract::Vector#store)
+      # @see Abstract::Vector#store
+      def store(index, value, mode: nil)
+        write { unwrap_stored(@working.store(index, wrap(value, mode:))) }
+      end
+
+      # (see Abstract::Vector#swap)
+      # @see Abstract::Vector#swap
+      def swap(index, value, mode: nil)
+        write { unwrap_stored(@working.swap(index, wrap(value, mode:))) }
+      end
+
+      # (see Abstract::Vector#push)
+      # @see Abstract::Vector#push
+      def push(value, mode: nil)
+        write { @working.push(wrap(value, mode:)) }
+        self
+      end
+      alias << push
+
+      # (see Abstract::Vector#pop)
+      # @see Abstract::Vector#pop
+      def pop = write { unwrap_stored(@working.pop) }
+
+      # (see Abstract::Vector#clear)
+      # @see Abstract::Vector#clear
+      def clear
+        write { @working.clear }
+        self
+      end
+
+      # (see Abstract::Vector#each)
+      # @see Abstract::Vector#each
+      def each
+        return enum_for(__method__) unless block_given?
+        access { @working.snapshot.each { |value| yield unwrap_stored(value) } }
+        self
+      end
+
+      # (see Abstract::Vector#update)
+      # @see Abstract::Vector#update
+      def update(index, mode: nil)
+        require_block!(block_given?)
+        write { unwrap_stored(@working.update(index) { |value| wrap(yield(unwrap_stored(value)), mode:) }) }
+      end
+
+      # (see Abstract::Vector#store_if_absent)
+      # @see Abstract::Vector#store_if_absent
+      def store_if_absent(index, mode: nil)
+        require_block!(block_given?)
+        write { unwrap_stored(@working.store_if_absent(index) { wrap(yield, mode:) }) }
+      end
+
+      # (see Abstract::Vector#upsert)
+      # @see Abstract::Vector#upsert
+      def upsert(index, initial, mode: nil)
+        require_block!(block_given?)
+        write do
+          unwrap_stored(@working.upsert(index, wrap(initial, mode:)) do |value|
+            wrap(yield(unwrap_stored(value)), mode:)
+          end)
+        end
+      end
+
+      # (see Abstract::Vector#compare_and_set)
+      # @see Abstract::Vector#compare_and_set
+      def compare_and_set(index, expected, replacement, mode: nil)
+        write do
+          next compared(@working.compare_and_set(index, expected, replacement)) unless @manager
+          index = Integer(index)
+          next compared(false) unless index >= -@working.size && index < @working.size &&
+            matches?(@working[index], expected, identity: @object.compare_by_identity?)
+          @working.store(index, wrap(replacement, mode:))
+          true
+        end
+      end
+
+      protected
+
+      def internal_vector = @working
+      def logical_value(value) = unwrap_stored(value)
+
+      # Slice helpers return independent data rather than another participant.
+      # Use an ordinary vector that remains usable after the attempt ends.
+      def build_derived_vector(values)
+        Unshared::Vector.new(values.map { unwrap_stored(it) }, compare_by_identity: compare_by_identity?)
+      end
+
+      private
+
+      def inspect_value(inspector, value) = super(inspector, value, @manager)
+      def derived_storage(value)          = wrap(value)
+
+      Wrapper.inherit(self, :each_index, :reverse_each, :to_a, :deconstruct, :to_h, :join, :dig, :assoc,
+        :rassoc, :at, :fetch, :fetch_values, :values_at, :slice, :rfind, :bsearch, :bsearch_index, :pack,
+        :length, :count, :compare_by_identity?, :shareable_values?)
+    end
+  end
+end