leptris 1.9.24 → 1.9.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6d5a244d8c1bf6743629a19b9256da3df1159cd6fba153a61f0bdad6037b072
-  data.tar.gz: 37430812bf170d6e47f8a187cda3669e5b0e422e7420f1da2ec642cff13e1d76
+  metadata.gz: afa52b007ec23d222a3562207fcef3f9975f62c11378da91de2d238eff7a74be
+  data.tar.gz: 878468ec897ba3f9b60aca28e1379ac712e261c4500c4cc51c2a7379545730ee
 SHA512:
-  metadata.gz: 4cf2c7ccd09de5e89588db0bbad0fe9650f892608f6a4a4a08e4c40f5175768091a6f88ff1bedfd8d5b571eb04c9249c09daec7ed3ba99dff0ba1b89d426e0b0
-  data.tar.gz: '038b8c917cde736d84df62a3bbe9e7c870ccdb210184c0ac49c785d900805f5a5ed71f33e922d56c4abf9a3fa99bf38d0368976b49efa7da2f58d7fadc0dc648'
+  metadata.gz: a8caa0b2d6052ff1e72a1d23c59d1f283b887c852e7cb669fa8449d85438f8f89a2005726f96644f6bc46c880d717e54c922210fb9b638c2d890d6d0cdc57fbe
+  data.tar.gz: 19fab1e638971c2402b69e70447657c9dfe4d140ba55e588f09b4a394690b34c2e43ba46433615209f66be1660ee6755b83827e7b51e84516c5793b67f44d0d2

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.24"
+  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
 

metadata

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