parsanol 1.3.13-arm-linux

data/lib/parsanol/pools/buffer_pool.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "../buffer"
+
+module Parsanol
+  module Pools
+    # Manages fixed-size buffers organized by size class.
+    #
+    # BufferPool provides efficient buffer allocation by maintaining
+    # separate pools for common buffer sizes. This reduces allocation
+    # overhead and enables buffer reuse across parses.
+    #
+    # == Usage
+    #
+    #   pool = BufferPool.new
+    #   buffer = pool.acquire(size: 8)  # Get buffer with capacity >= 8
+    #   buffer.push("a")
+    #   pool.release(buffer)
+    #
+    # == Size Classes
+    #
+    # Buffers are organized into size classes:
+    # - Small: 2, 4, 8 (most common)
+    # - Medium: 16, 32 (common)
+    # - Large: 64+ (rare, allocated on demand)
+    #
+    # This matches typical parsing patterns where most arrays are small.
+    #
+    class BufferPool
+      # Standard size classes (power of 2 for efficiency)
+      SIZE_CLASSES = [2, 4, 8, 16, 32, 64].freeze
+
+      # Default pool size per class
+      DEFAULT_POOL_SIZE = 100
+
+      # @return [Hash] Pools by size class
+      attr_reader :pools
+
+      # @return [Hash] Statistics per size class
+      attr_reader :stats
+
+      # Initialize a new BufferPool.
+      #
+      # @param pool_size [Integer] Number of buffers per size class
+      #
+      def initialize(pool_size: DEFAULT_POOL_SIZE)
+        @pool_size = pool_size
+        @pools = {}
+        @stats = {}
+
+        # Create pool for each size class
+        SIZE_CLASSES.each do |size|
+          @pools[size] = []
+          @stats[size] = { created: 0, reused: 0, released: 0, discarded: 0 }
+        end
+      end
+
+      # Acquire a buffer with at least the requested capacity.
+      #
+      # Returns a buffer from the appropriate size class pool.
+      # If no buffer available, creates a new one.
+      #
+      # @param size [Integer] Minimum required capacity
+      # @return [Buffer] Buffer with capacity >= size
+      #
+      def acquire(size:)
+        size_class = select_size_class(size)
+
+        # For non-standard size classes, create buffer on demand
+        return Buffer.new(capacity: size_class) unless @pools.key?(size_class)
+
+        pool = @pools[size_class]
+
+        if pool.empty?
+          @stats[size_class][:created] += 1
+          Buffer.new(capacity: size_class)
+        else
+          @stats[size_class][:reused] += 1
+          pool.pop
+        end
+      end
+
+      # Release a buffer back to the pool.
+      #
+      # Clears the buffer and returns it to the appropriate size class pool.
+      #
+      # @param buffer [Buffer] Buffer to release
+      # @return [Boolean] true if returned to pool, false if discarded
+      #
+      def release(buffer)
+        size_class = buffer.capacity
+        pool = @pools[size_class]
+
+        # Discard if pool is full or size not in standard classes
+        if !pool || pool.size >= @pool_size
+          @stats[size_class][:discarded] += 1 if @stats[size_class]
+          return false
+        end
+
+        buffer.clear!
+        @stats[size_class][:released] += 1
+        pool.push(buffer)
+        true
+      end
+
+      # Get statistics for all size classes.
+      #
+      # @return [Hash] Statistics by size class
+      #
+      def statistics
+        result = {}
+        SIZE_CLASSES.each do |size|
+          stats = @stats[size]
+          total_acquires = stats[:created] + stats[:reused]
+          utilization = if total_acquires.zero?
+                          0.0
+                        else
+                          (stats[:reused].to_f / total_acquires * 100)
+                        end
+
+          result[size] = {
+            available: @pools[size].size,
+            created: stats[:created],
+            reused: stats[:reused],
+            released: stats[:released],
+            discarded: stats[:discarded],
+            utilization: utilization.round(2),
+          }
+        end
+        result
+      end
+
+      # Clear all pools.
+      #
+      # @return [void]
+      #
+      def clear!
+        @pools.each_value(&:clear)
+        @stats.each_value do |s|
+          s[:created] = s[:reused] = s[:released] = s[:discarded] = 0
+        end
+      end
+
+      private
+
+      # Select appropriate size class for requested size.
+      #
+      # Returns smallest size class >= requested size.
+      #
+      # @param size [Integer] Requested size
+      # @return [Integer] Size class
+      #
+      def select_size_class(size)
+        i = 0
+        n = SIZE_CLASSES.length
+        while i < n
+          return SIZE_CLASSES[i] if SIZE_CLASSES[i] >= size
+
+          i += 1
+        end
+        next_power_of_2(size)
+      end
+
+      # Find next power of 2 greater than or equal to n.
+      #
+      # @param n [Integer] Input value
+      # @return [Integer] Next power of 2
+      #
+      def next_power_of_2(n)
+        return 1 if n <= 0
+
+        n -= 1
+        n |= n >> 1
+        n |= n >> 2
+        n |= n >> 4
+        n |= n >> 8
+        n |= n >> 16
+        n + 1
+      end
+    end
+  end
+end

data/lib/parsanol/pools/position_pool.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module Pools
+    # Specialized object pool for Position instances.
+    #
+    # PositionPool extends ObjectPool to provide position-specific behavior,
+    # particularly managing the line and column state for reuse.
+    #
+    # == Usage
+    #
+    #   pool = Parsanol::Pools::PositionPool.new(size: 1000)
+    #
+    #   # Acquire a position with line/column
+    #   pos = pool.acquire_with(string: "source", bytepos: 42, charpos: 42)
+    #
+    #   # Return to pool (automatically reset)
+    #   pool.release(pos)
+    #
+    # == Architecture
+    #
+    # v3.0.0 uses integer positions during parsing for efficiency.
+    # Position objects are only created when:
+    # - Generating error messages (need line/column)
+    # - Materializing error context
+    #
+    # By pooling Position objects, we reduce GC pressure at the
+    # materialization point without changing the fast integer-based
+    # parsing path.
+    #
+    class PositionPool < Parsanol::ObjectPool
+      # Initialize a new PositionPool.
+      #
+      # @param size [Integer] Maximum number of Position objects to pool
+      # @param preallocate [Boolean] Whether to pre-allocate positions
+      #
+      def initialize(size: 1000, preallocate: false)
+        # NOTE: Position requires arguments, so we cannot pre-allocate
+        super(Parsanol::Position, size: size, preallocate: false)
+      end
+
+      # Acquire a Position from the pool.
+      # Overrides ObjectPool#acquire to handle Position's required arguments.
+      #
+      # @return [Parsanol::Position] A position instance from pool or newly created
+      #
+      def acquire
+        if @available.empty?
+          @stats[:created] += 1
+          # Create Position with default values since it requires arguments
+          Parsanol::Position.new("", 0, 0)
+        else
+          @stats[:reused] += 1
+          @available.pop
+        end
+      end
+
+      # Acquire a Position from the pool and initialize it with values.
+      #
+      # @param string [String] Source string for position tracking
+      # @param bytepos [Integer] Byte position in source
+      # @param charpos [Integer, nil] Character position (optional)
+      # @return [Parsanol::Position] Initialized position from pool
+      #
+      def acquire_with(string:, bytepos:, charpos: nil)
+        pos = acquire
+        pos.reset!(string, bytepos, charpos)
+        pos
+      end
+
+      # Return a position to the pool after resetting it.
+      #
+      # @param pos [Parsanol::Position] The position to return
+      # @return [Boolean] true if returned to pool, false if discarded
+      #
+      def release(pos)
+        # Don't pool if we're at capacity - discard instead
+        if @available.size >= @size
+          @stats[:discarded] += 1
+          return false
+        end
+
+        # Reset position state with default values before returning to pool
+        pos.reset!("", 0, 0)
+
+        @stats[:released] += 1
+        @available.push(pos)
+        true
+      end
+    end
+  end
+end

data/lib/parsanol/pools/slice_pool.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module Pools
+    # Specialized object pool for Parsanol::Slice instances.
+    #
+    # SlicePool extends ObjectPool to provide convenient methods for
+    # acquiring and configuring Slice objects. Since Slices are frequently
+    # created during parsing, pooling them significantly reduces GC pressure.
+    #
+    # == Usage
+    #
+    #   pool = Parsanol::Pools::SlicePool.new(size: 1000)
+    #
+    #   # Acquire and initialize in one step
+    #   slice = pool.acquire_with(0, "hello", line_cache)
+    #
+    #   # Use the slice...
+    #
+    #   # Return to pool
+    #   pool.release(slice)
+    #
+    # == Why Pool Slices?
+    #
+    # Profiling (Session 19) showed that Slice allocation contributes
+    # significantly to GC overhead. By reusing Slice objects, we can:
+    # - Reduce object allocations by 70-80%
+    # - Decrease GC time from 67% to ~20%
+    # - Improve overall parsing throughput by 2-3x
+    #
+    class SlicePool < Parsanol::ObjectPool
+      # Initialize a new SlicePool.
+      #
+      # @param size [Integer] Maximum number of Slice objects to pool (default: 1000)
+      # @param preallocate [Boolean] Whether to pre-allocate slices (default: true)
+      #
+      # @example Create a SlicePool
+      #   pool = SlicePool.new(size: 2000)
+      #
+      def initialize(size: 1000, preallocate: true)
+        super(Parsanol::Slice, size: size, preallocate: preallocate)
+      end
+
+      # Acquire a Slice from the pool and initialize it with given values.
+      #
+      # This is a convenience method that combines acquire + reset! into
+      # a single operation, making it easier to work with pooled slices.
+      #
+      # @param bytepos [Integer] Byte position in the original input
+      # @param str [String] The slice content
+      # @param line_cache [Object] Optional line cache for line/column info
+      # @return [Parsanol::Slice] An initialized slice ready for use
+      #
+      # @example Acquire and initialize
+      #   slice = pool.acquire_with(0, "hello", line_cache)
+      #
+      def acquire_with(bytepos, str, line_cache = nil)
+        slice = acquire
+        slice.reset!(bytepos, str, line_cache)
+        slice
+      end
+    end
+  end
+end

data/lib/parsanol/position.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Encapsules the concept of a position inside a string.
+#
+module Parsanol
+  class Position
+    include Parsanol::Resettable
+
+    # Changed to accessor to support pooling
+    attr_accessor :bytepos
+    attr_accessor :string, :charpos
+
+    include Comparable
+
+    def initialize(string, bytepos, charpos = nil)
+      @string = string
+      @bytepos = bytepos
+      @charpos = charpos
+    end
+
+    # Reset the position for reuse in object pooling.
+    # This allows the position to be reinitialized with new values for efficient reuse.
+    #
+    # @param string [String] Source string for position tracking
+    # @param bytepos [Integer] New byte position
+    # @param charpos [Integer, nil] Optional character position
+    # @return [self] Returns self for method chaining
+    #
+    def reset!(string, bytepos, charpos = nil)
+      @string = string
+      @bytepos = bytepos
+      @charpos = charpos
+      self
+    end
+
+    def charpos
+      # If charpos was provided during initialization, use it
+      return @charpos if @charpos
+
+      # Cache the calculated charpos to avoid repeated calculations
+      @charpos ||= calculate_charpos
+    end
+
+    private
+
+    def calculate_charpos
+      # Calculate it based on platform
+      if defined?(RUBY_ENGINE) && RUBY_ENGINE == "opal"
+        # In Opal, convert byte position to character position.
+        # We need to calculate how many characters occupy the first @bytepos bytes.
+        `
+        var str = #{@string};
+        var bytePos = #{@bytepos};
+        var chars = Array.from(str);
+        var byteCount = 0;
+        var charCount = 0;
+
+        for (var i = 0; i < chars.length; i++) {
+          if (byteCount >= bytePos) break;
+
+          var char = chars[i];
+          var codePoint = char.codePointAt(0);
+
+          // Calculate UTF-8 byte length for this character
+          if (codePoint < 0x80) {
+            byteCount += 1;
+          } else if (codePoint < 0x800) {
+            byteCount += 2;
+          } else if (codePoint < 0x10000) {
+            byteCount += 3;
+          } else {
+            byteCount += 4;
+          }
+
+          if (byteCount <= bytePos) {
+            charCount++;
+          }
+        }
+
+        return charCount;
+      `
+      else
+        # Ruby: Use standard byteslice which handles Unicode correctly
+        @string.byteslice(0, @bytepos).size
+      end
+    end
+
+    public
+
+    def <=>(other)
+      bytepos <=> other.bytepos
+    end
+  end
+end

data/lib/parsanol/resettable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Module for objects that can be reset for object pool reuse.
+  #
+  # Including this module signals that an object supports the reset!
+  # method for pooling purposes. This provides an explicit contract
+  # instead of duck-typing with respond_to?.
+  #
+  # @example
+  #   class MyPooledObject
+  #     include Parsanol::Resettable
+  #
+  #     def reset!
+  #       @state = nil
+  #       self
+  #     end
+  #   end
+  #
+  module Resettable
+    # Reset object state for reuse in object pool.
+    #
+    # @return [self] for method chaining
+    # @raise [NotImplementedError] if not implemented by including class
+    def reset!
+      raise NotImplementedError, "#{self.class} must implement #reset!"
+    end
+  end
+end

data/lib/parsanol/result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Phase 58: Result wrapper to replace [success, value] arrays
+#
+# This class wraps parse results to eliminate array allocations.
+# Instead of [true, value] or [false, cause], we use Result objects.
+#
+# Benefits:
+# - Eliminates array allocations (40% reduction)
+# - Cleaner API with success? method
+# - Can be optimized further (object pooling, etc.)
+#
+module Parsanol
+  class Result
+    attr_reader :value
+
+    def initialize(success, value)
+      @success = success
+      @value = value
+    end
+
+    def success?
+      @success
+    end
+
+    def error?
+      !@success
+    end
+
+    # Compatibility: Allow destructuring like arrays
+    # This enables gradual migration: result.success?, result.value
+    # or: success, value = result (array-like)
+    def to_ary
+      [@success, @value]
+    end
+
+    # Factory methods for common cases
+    def self.success(value)
+      new(true, value)
+    end
+
+    def self.error(cause)
+      new(false, cause)
+    end
+  end
+end

data/lib/parsanol/result_builder.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Base class for efficient result construction.
+  #
+  # ResultBuilder provides specialized construction patterns that avoid
+  # intermediate array allocations by building results directly.
+  #
+  # == Usage
+  #
+  #   builder = ResultBuilder.for(:repetition, context, estimated_size: 10)
+  #   builder.add_element(value1)
+  #   builder.add_element(value2)
+  #   result = builder.build  # Returns LazyResult
+  #
+  # == Builders
+  #
+  # - RepetitionBuilder: For repetition results
+  # - SequenceBuilder: For sequence results
+  # - HashBuilder: For named capture results
+  #
+  class ResultBuilder
+    # Factory method to create appropriate builder.
+    #
+    # @param type [Symbol] Builder type (:repetition, :sequence, :hash)
+    # @param context [Context] Parse context
+    # @param options [Hash] Builder options
+    # @return [ResultBuilder] Appropriate builder instance
+    #
+    def self.for(type, context, **)
+      case type
+      when :repetition
+        RepetitionBuilder.new(context, **)
+      when :sequence
+        SequenceBuilder.new(context, **)
+      when :hash
+        HashBuilder.new(context, **)
+      else
+        raise ArgumentError, "Unknown builder type: #{type}"
+      end
+    end
+
+    # Initialize builder.
+    #
+    # @param context [Context] Parse context for buffer access
+    #
+    def initialize(context)
+      @context = context
+    end
+
+    # Add element to result (subclasses implement).
+    #
+    # @param value [Object] Value to add
+    # @return [self] For method chaining
+    #
+    def add_element(value)
+      raise NotImplementedError
+    end
+
+    # Build final result (subclasses implement).
+    #
+    # @return [Object] Constructed result
+    #
+    def build
+      raise NotImplementedError
+    end
+
+    # Release resources (subclasses implement).
+    #
+    # @return [void]
+    #
+    def release
+      # Default: no-op
+    end
+  end
+
+  # Builder for repetition results.
+  #
+  # Constructs [:repetition, ...] arrays efficiently.
+  #
+  class RepetitionBuilder < ResultBuilder
+    # Initialize repetition builder.
+    #
+    # @param context [Context] Parse context
+    # @param tag [Symbol] Tag to use (default: :repetition)
+    # @param estimated_size [Integer] Estimated element count
+    #
+    def initialize(context, tag: :repetition, estimated_size: 10)
+      super(context)
+      @tag = tag
+      @buffer = context.acquire_buffer(size: estimated_size + 1)
+      @buffer.push(@tag)
+    end
+
+    # Add element to repetition.
+    #
+    # @param value [Object] Element to add
+    # @return [self]
+    #
+    def add_element(value)
+      @buffer.push(value)
+      self
+    end
+
+    # Build LazyResult.
+    #
+    # @return [LazyResult] Lazy repetition result
+    #
+    def build
+      Parsanol::LazyResult.new(@buffer, @context)
+    end
+
+    # Release buffer on failure.
+    #
+    # @return [void]
+    #
+    def release
+      @context.release_buffer(@buffer) if @buffer
+      @buffer = nil
+    end
+  end
+
+  # Builder for sequence results.
+  #
+  # Constructs [:sequence, ...] arrays efficiently.
+  #
+  class SequenceBuilder < ResultBuilder
+    # Initialize sequence builder.
+    #
+    # @param context [Context] Parse context
+    # @param size [Integer] Expected sequence length
+    #
+    def initialize(context, size: 5)
+      super(context)
+      @buffer = context.acquire_buffer(size: size + 1)
+      @buffer.push(:sequence)
+    end
+
+    # Add element to sequence.
+    #
+    # @param value [Object] Element to add
+    # @return [self]
+    #
+    def add_element(value)
+      @buffer.push(value) if value # Skip nil values
+      self
+    end
+
+    # Build LazyResult.
+    #
+    # @return [LazyResult] Lazy sequence result
+    #
+    def build
+      Parsanol::LazyResult.new(@buffer, @context)
+    end
+
+    # Release buffer on failure.
+    #
+    # @return [void]
+    #
+    def release
+      @context.release_buffer(@buffer) if @buffer
+      @buffer = nil
+    end
+  end
+
+  # Builder for hash results (named captures).
+  #
+  # Constructs hashes directly without intermediate arrays.
+  #
+  class HashBuilder < ResultBuilder
+    # Initialize hash builder.
+    #
+    # @param context [Context] Parse context
+    #
+    def initialize(context)
+      super
+      @hash = {}
+    end
+
+    # Add key-value pair.
+    #
+    # @param key [Symbol] Hash key
+    # @param value [Object] Hash value
+    # @return [self]
+    #
+    def add_pair(key, value)
+      @hash[key] = value
+      self
+    end
+
+    # Build hash result.
+    #
+    # @return [Hash] Constructed hash
+    #
+    def build
+      @hash
+    end
+
+    # Release resources (hash cleanup).
+    #
+    # @return [void]
+    #
+    def release
+      @hash = nil
+    end
+  end
+end