leptris 1.9.23 → 1.9.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec6d834f30c917e77000bf9784e85ecc59b8752c246f28bb6932bd003f0d45f9
-  data.tar.gz: a0cd90f99e074b719d9538dc3c1f245e85fc3185fbe693c5b4dab3bee405c77b
+  metadata.gz: afa52b007ec23d222a3562207fcef3f9975f62c11378da91de2d238eff7a74be
+  data.tar.gz: 878468ec897ba3f9b60aca28e1379ac712e261c4500c4cc51c2a7379545730ee
 SHA512:
-  metadata.gz: d4de54e8c4cb0b5d3951a7c7ac63fc4ce4d97335597d923eb424f445cbaaa790fb27220563d6bbd65ca7490522f2a42423da5e28b199b9e16fcfeb638b148dfb
-  data.tar.gz: 797164d946ad51fde25139e6cbdcc45d9c86a18f5062b09a93c63e098f443ad4b48c1c1f8cce6d26b7f2583a7decd774954dbe4dbe77e4839ad3f5c9d9e3eab9
+  metadata.gz: a8caa0b2d6052ff1e72a1d23c59d1f283b887c852e7cb669fa8449d85438f8f89a2005726f96644f6bc46c880d717e54c922210fb9b638c2d890d6d0cdc57fbe
+  data.tar.gz: 19fab1e638971c2402b69e70447657c9dfe4d140ba55e588f09b4a394690b34c2e43ba46433615209f66be1660ee6755b83827e7b51e84516c5793b67f44d0d2

data/CHANGELOG.md

@@ -5,7 +5,62 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.9.22] - 2026-08-27
+## [1.9.25] - 2026-08-28
+
+### Fixed
+
+- **Cold full-tree walk regression (1.9.1 → 1.9.24, ~1.4-1.5x)
+  recovered to parity**: the batch-fetch era (1.9.11-1.9.17) bought
+  its warm-path wins with per-call machinery the cold branch paid
+  on every children() — reproduced, bisected across every published
+  release, and profiled end to end this round. Raw cold walk of a
+  ~4,200-node catalog (interleaved best-of-5): 1.9.24 5,441 µs ->
+  **4,519 µs (-17%)**, vs 1.9.1's 4,369 µs = parity. Through moxml
+  the same shape improves 20.1 ms -> 16.5 ms (-18%).
+  - `FFI.fetch_children` (and the XPath result batch) now use
+    thread-local scratch buffers that grow to the largest family
+    seen and are reused — no MemoryPointer allocation/free per
+    call, and materially less GC. The count query is paid only when
+    the buffer fills exactly (possible truncation): a family that
+    fits costs ONE dispatch, not two.
+  - `Node.wrap`'s miss path resolves the wrapper cache and pointer
+    address once instead of twice — a cold walk wraps every node
+    exactly once, so the cache is 100% misses and every redundant
+    resolution was pure cost. Identity semantics unchanged.
+  - Kept: the per-field version-stamped memo stores on writable
+    documents (ADR-0003's writable extension — the residual ~3% vs
+    1.9.1 is that feature working) and the batch architecture
+    itself (never more FFI dispatches than the linked-list walk,
+    and 2 vs 701 for the 700-child root).
+
+## [1.9.24] - 2026-08-27
+
+### Changed
+
+- **Interest-proportional SAX (both transports)**: the handler's
+  declared interest — which event methods it overrides — now decides
+  what the transport dispatches or drains.
+  - `SAX::Parser` attaches a callback only when the handler defines
+    the method beyond `SAX::Document`'s no-ops; the C engine already
+    skips NULL callbacks, so unwanted events cost nothing on either
+    side. Measured per parse of a 1.9 MB / 250k-event document:
+    text-only handler 151 ms -> 22 ms (**6.9x**); a handler that
+    overrides nothing runs at the C floor, 151 ms -> 7 ms
+    (**22x**); elements-only 151 ms -> 121 ms (-20%, the remainder
+    is attribute walking). Handlers overriding most kinds stay at
+    parity. Duck-typed handlers attach exactly what they define.
+  - `SAX::Recorder#each_event(*kinds)` (and `Recorder.parse(...,
+    kinds:)`, `#feed_stream(..., kinds:)`) skips records of other
+    kinds BEFORE slicing any strings from the arena — an unwanted
+    event costs one Array read. Filtered `:characters` drain 201 ms
+    -> 119 ms (**-41%**); unknown kinds raise ArgumentError. The
+    kind lookup table is now an Array indexed by the event code.
+  - Transport choice, by measurement: the pruned callback transport
+    beats the filtered recorder for selective consumers (C-side
+    emission is skipped entirely), so callbacks remain the default;
+    the recorder keeps its niche — bulk raw-event drains per chunk.
+
+## [1.9.23] - 2026-08-27
 
 ### Added
 

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.23"
+  VERSION = "1.9.25"
 end

data/lib/leptris/xml/ffi.rb

@@ -817,16 +817,33 @@ module Leptris
         end
       end
 
-      # All-kind child handle batch (libleptris 1.7.0): count-only
-      # query sizes the buffer, one fetch copies every child kind,
-      # one bulk read materializes the pointers.
+      # All-kind child handle batch (libleptris 1.7.0). Opportunistic
+      # single dispatch: the C call copies up to the capacity handed
+      # it and returns what fit, so the count query is paid only when
+      # the buffer fills exactly (a possible truncation) — families
+      # that fit the scratch buffer cost ONE dispatch, not two.
+      FETCH_INITIAL = 32
+      private_constant :FETCH_INITIAL
+
       def self.fetch_children(c_ptr)
-        count = leptris_node_children(c_ptr, nil, 0)
-        return [] if count.zero?
-        with_pointer_buffer(count) do |buffer|
-          copied = leptris_node_children(c_ptr, buffer, count)
-          buffer.get_array_of_pointer(0, copied)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        buffer = scratch[:pointers]
+        if buffer.nil?
+          buffer = scratch[:pointers] =
+            ::FFI::MemoryPointer.new(:pointer, FETCH_INITIAL)
+        end
+        cap = buffer.size / PTR_BYTES
+        copied = leptris_node_children(c_ptr, buffer, cap)
+        if copied == cap
+          total = leptris_node_children(c_ptr, nil, 0)
+          if total > cap
+            buffer.free
+            buffer = scratch[:pointers] =
+              ::FFI::MemoryPointer.new(:pointer, total)
+            copied = leptris_node_children(c_ptr, buffer, total)
+          end
         end
+        buffer.get_array_of_pointer(0, copied)
       end
 
       # XPath result-set batch (leptris_xpath_result_get_nodes_ex):
@@ -840,18 +857,13 @@ module Leptris
 
       def self.fetch_result_nodes(result_ptr, count)
         return [[], nil] if count.zero?
-        with_pointer_buffer(count) do |buffer|
-          kinds = ::FFI::MemoryPointer.new(:int, count)
-          begin
-            copied = leptris_xpath_result_get_nodes_ex(
-              result_ptr, buffer, kinds, count)
-            hints = kinds.get_array_of_int(0, copied)
-              .map { |k| XPATH_KIND_HINT[k] }
-            [buffer.get_array_of_pointer(0, copied), hints]
-          ensure
-            kinds.free
-          end
-        end
+        buffer = scratch_pointers(count)
+        kinds = scratch_ints(count)
+        copied = leptris_xpath_result_get_nodes_ex(
+          result_ptr, buffer, kinds, count)
+        hints = kinds.get_array_of_int(0, copied)
+          .map { |k| XPATH_KIND_HINT[k] }
+        [buffer.get_array_of_pointer(0, copied), hints]
       end
 
       # Fragment parse with the status out-param read: returns
@@ -863,16 +875,38 @@ module Leptris
         [raw, status.read_int]
       end
 
-      # The one buffer-allocation point for handle-array fetches:
-      # everything MemoryPointer-related above this line is either
-      # an attached C call or another seam helper.
-      def self.with_pointer_buffer(count)
-        buffer = ::FFI::MemoryPointer.new(:pointer, count)
-        begin
-          yield buffer
-        ensure
-          buffer.free
+      # Thread-local scratch buffers for batch handle fetches (round
+      # XX): the per-call MemoryPointer new/free was pure cold-path
+      # overhead — two allocations and a GC visit per children() /
+      # result-set batch, ~15% of a cold full-tree walk between
+      # 1.9.1 and 1.9.24. The buffers grow to the largest request
+      # seen (bounded by the widest element or result set) and are
+      # reused. Safe: no Ruby reentrancy during the C call, and
+      # per-thread storage keeps concurrent fetches independent.
+      # Never freed — a few KB pinned per thread.
+      PTR_BYTES = ::FFI.type_size(:pointer)
+      private_constant :PTR_BYTES
+      INT_BYTES = ::FFI.type_size(:int)
+      private_constant :INT_BYTES
+
+      def self.scratch_pointers(count)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:pointers]
+        if ptr.nil? || ptr.size / PTR_BYTES < count
+          ptr&.free
+          ptr = scratch[:pointers] = ::FFI::MemoryPointer.new(:pointer, count)
+        end
+        ptr
+      end
+
+      def self.scratch_ints(count)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:ints]
+        if ptr.nil? || ptr.size / INT_BYTES < count
+          ptr&.free
+          ptr = scratch[:ints] = ::FFI::MemoryPointer.new(:int, count)
         end
+        ptr
       end
     end
   end

data/lib/leptris/xml/node.rb

@@ -19,9 +19,15 @@ class Leptris::XML::Node
     # Per-document weak-ref cache. Returns the existing wrapper when the
     # same c_ptr is wrapped twice (common in children/sibling walks,
     # repeated xpath queries, traverse-then-access patterns). The cache
-    # dies with the document so no stale entries.
-    if document && (cached = document.wrapper_cache[c_ptr.address])
-      return cached
+    # dies with the document so no stale entries. The miss path
+    # resolves the cache and address once — a cold walk wraps every
+    # node exactly once and pays both only on the store.
+    if document
+      cache = document.wrapper_cache
+      address = c_ptr.address
+      if (cached = cache[address])
+        return cached
+      end
     end
 
     node_type ||= Leptris::XML::FFI.leptris_node_get_type(c_ptr)
@@ -41,7 +47,7 @@ class Leptris::XML::Node
         new(c_ptr, document, parent: parent, node_type: node_type)
       end
 
-    document.wrapper_cache[c_ptr.address] = node if document
+    cache[address] = node if document
     node
   end
 

data/lib/leptris/xml/sax/parser.rb

@@ -83,59 +83,95 @@ class Leptris::XML::SAX::Parser
   private
 
   # Build a LeptrisSAXHandler struct populated with FFI::Function callbacks
-  # that dispatch to the Ruby handler.
+  # that dispatch to the Ruby handler. Only the callbacks the handler
+  # actually overrides are attached: the C engine skips NULL callbacks,
+  # so cost scales with the handler's declared interest, not with the
+  # document's event mix (measured 4.9x for an elements-only handler on
+  # a 1.9 MB stream).
   def build_handler_struct
     s = Leptris::XML::FFI::SAXHandler.new
     handler = @document  # capture in closures
 
-    s[:start_document] = callback(:void, [:pointer]) do |_|
-      handler.start_document
+    if overridden?(:start_document)
+      s[:start_document] = callback(:void, [:pointer]) do |_|
+        handler.start_document
+      end
     end
 
-    s[:end_document] = callback(:void, [:pointer]) do |_|
-      handler.end_document
+    if overridden?(:end_document)
+      s[:end_document] = callback(:void, [:pointer]) do |_|
+        handler.end_document
+      end
     end
 
-    s[:start_element] = callback(:void, [:pointer, :string, :pointer]) do |_, name, attrs_ptr|
-      attrs = walk_attr_array(attrs_ptr)
-      handler.start_element(utf8(name), attrs)
+    if overridden?(:start_element)
+      s[:start_element] = callback(:void, [:pointer, :string, :pointer]) do |_, name, attrs_ptr|
+        attrs = walk_attr_array(attrs_ptr)
+        handler.start_element(utf8(name), attrs)
+      end
     end
 
-    s[:end_element] = callback(:void, [:pointer, :string]) do |_, name|
-      handler.end_element(utf8(name))
+    if overridden?(:end_element)
+      s[:end_element] = callback(:void, [:pointer, :string]) do |_, name|
+        handler.end_element(utf8(name))
+      end
     end
 
-    s[:characters] = callback(:void, [:pointer, :pointer, :size_t]) do |_, text_ptr, len|
-      handler.characters(text_ptr.read_bytes(len).force_encoding(Encoding::UTF_8))
+    if overridden?(:characters)
+      s[:characters] = callback(:void, [:pointer, :pointer, :size_t]) do |_, text_ptr, len|
+        handler.characters(text_ptr.read_bytes(len).force_encoding(Encoding::UTF_8))
+      end
     end
 
-    s[:comment] = callback(:void, [:pointer, :string]) do |_, comment|
-      handler.comment(utf8(comment))
+    if overridden?(:comment)
+      s[:comment] = callback(:void, [:pointer, :string]) do |_, comment|
+        handler.comment(utf8(comment))
+      end
     end
 
-    s[:cdata] = callback(:void, [:pointer, :string]) do |_, cdata|
-      handler.cdata_block(utf8(cdata))
+    if overridden?(:cdata_block)
+      s[:cdata] = callback(:void, [:pointer, :string]) do |_, cdata|
+        handler.cdata_block(utf8(cdata))
+      end
     end
 
-    s[:processing_instruction] = callback(:void, [:pointer, :string, :string]) do |_, target, data|
-      handler.processing_instruction(utf8(target), utf8(data))
+    if overridden?(:processing_instruction)
+      s[:processing_instruction] = callback(:void, [:pointer, :string, :string]) do |_, target, data|
+        handler.processing_instruction(utf8(target), utf8(data))
+      end
     end
 
-    s[:start_prefix_mapping] = callback(:void, [:pointer, :string, :string]) do |_, prefix, uri|
-      handler.start_prefix_mapping(utf8(prefix), utf8(uri))
+    if overridden?(:start_prefix_mapping)
+      s[:start_prefix_mapping] = callback(:void, [:pointer, :string, :string]) do |_, prefix, uri|
+        handler.start_prefix_mapping(utf8(prefix), utf8(uri))
+      end
     end
 
-    s[:end_prefix_mapping] = callback(:void, [:pointer, :string]) do |_, prefix|
-      handler.end_prefix_mapping(utf8(prefix))
+    if overridden?(:end_prefix_mapping)
+      s[:end_prefix_mapping] = callback(:void, [:pointer, :string]) do |_, prefix|
+        handler.end_prefix_mapping(utf8(prefix))
+      end
     end
 
-    s[:error] = callback(:void, [:pointer, :string, :int, :int]) do |_, msg, line, col|
-      handler.error(utf8(msg), line, col)
+    if overridden?(:error)
+      s[:error] = callback(:void, [:pointer, :string, :int, :int]) do |_, msg, line, col|
+        handler.error(utf8(msg), line, col)
+      end
     end
 
     s
   end
 
+  # True when the handler defines the event method beyond the no-op
+  # every SAX::Document carries — subclasses, included modules, and
+  # duck-typed handlers all qualify; a handler that overrides nothing
+  # attaches nothing and the parse runs at the C floor.
+  def overridden?(name)
+    @document.method(name).owner != Leptris::XML::SAX::Document
+  rescue NameError
+    false
+  end
+
   def callback(return_type, params, blocking: true, &block)
     ::FFI::Function.new(return_type, params, blocking: blocking, &block)
   end

data/lib/leptris/xml/sax/recorder.rb

@@ -29,6 +29,10 @@ class Leptris::XML::SAX::Recorder
     Leptris::XML::FFI::SAX_EVENT_ERROR => :error,
   }.freeze
 
+  # Kind symbol per code byte — Array indexing in the drain loop,
+  # not a Hash lookup per event.
+  KIND_BY_CODE = Array.new(KINDS.size) { |code| KINDS[code] }.freeze
+
   def self.open
     raw = Leptris::XML::FFI.leptris_sax_recorder_new
     if raw.null?
@@ -38,14 +42,17 @@ class Leptris::XML::SAX::Recorder
   end
 
   # One-shot parse over a complete document, yielding Record structs.
-  def self.parse(xml_or_io)
+  # +kinds+ filters the drain (see #each_event) — pass e.g.
+  # `kinds: [:start_element]` to slice strings only for the events
+  # you consume.
+  def self.parse(xml_or_io, kinds: nil)
     recorder = open
     begin
       if xml_or_io.respond_to?(:read)
-        recorder.feed_stream(xml_or_io) { |*args| yield(*args) }
+        recorder.feed_stream(xml_or_io, kinds: kinds) { |*args| yield(*args) }
       else
         recorder.feed(xml_or_io.to_s, final: true)
-        recorder.each_event { |*args| yield(*args) }
+        recorder.each_event(*Array(kinds)) { |*args| yield(*args) }
       end
     ensure
       recorder.free
@@ -72,19 +79,23 @@ class Leptris::XML::SAX::Recorder
   end
 
   # Feed an IO in chunks, draining events after each chunk.
-  def feed_stream(io, chunk_size = 65_536, &block)
+  def feed_stream(io, chunk_size = 65_536, kinds: nil, &block)
     while (chunk = io.read(chunk_size))
       feed(chunk)
-      each_event(&block)
+      each_event(*Array(kinds), &block)
     end
     feed("", final: true)
-    each_event(&block)
+    each_event(*Array(kinds), &block)
   end
 
   # Drains the current chunk's records: bulk-reads the record array
   # and the packed arena (two FFI calls), then slices every string
-  # from the arena in Ruby — no per-string FFI.
-  def each_event
+  # from the arena in Ruby — no per-string FFI. With +kinds+, records
+  # of other kinds are skipped BEFORE any string is sliced: an
+  # unwanted event costs one Array read, and cost scales with what
+  # the consumer asked for, not with the document's event mix.
+  def each_event(*kinds)
+    wanted = kinds.empty? ? nil : wanted_set(kinds)
     count_ptr = ::FFI::MemoryPointer.new(:size_t)
     len_ptr = ::FFI::MemoryPointer.new(:size_t)
     begin
@@ -108,8 +119,8 @@ class Leptris::XML::SAX::Recorder
 
       i = 0
       while i < count
-        kind = KINDS[fields[i * 9]]
-        if kind
+        kind = KIND_BY_CODE[fields[i * 9]]
+        if kind && (wanted.nil? || wanted[kind])
           base = i * 9 + 1
           yield kind,
                 slice(arena, fields[base], fields[base + 1]),
@@ -128,6 +139,18 @@ class Leptris::XML::SAX::Recorder
 
   private
 
+  def wanted_set(kinds)
+    unknown = kinds.each_with_object([]) do |kind, acc|
+      acc << kind unless KINDS.value?(kind)
+    end
+    unless unknown.empty?
+      raise ArgumentError,
+        "unknown event kinds #{unknown.inspect} " \
+        "(known: #{KINDS.values.inspect})"
+    end
+    kinds.each_with_object({}) { |kind, set| set[kind] = true }
+  end
+
   # Zero-length slices are empty strings, not nil — the default
   # namespace prefix is legitimately "" (START_PREFIX: name may be
   # ""), matching the callback transport's delivery.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.23
+  version: 1.9.25
 platform: ruby
 authors:
 - Ribose Inc.