leptris 1.9.24-aarch64-linux → 1.9.26-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1be15b3c37fddd0b1f5c30c79b08adae540825a34605ffa2d44f8c9800dc1cd5
-  data.tar.gz: e008a194237148e03af56e37032cd3e3e30c1762680d3013b5cb3053af4a7c21
+  metadata.gz: 2ff1e0252cab3e0bf0f626b2561c127325c2540332d1049e0eaec864f5065d29
+  data.tar.gz: 2bc04e7940829b977148af31a56e8044496c1138773858a25e69c0d216b81fee
 SHA512:
-  metadata.gz: '04893f33c1d19df655b5ae1e5aeb15cd753988e1f7f7872f5984fa6a011863c59c860919186d7f688dbc200e3d2cc76c5266917ff0293f7ad125d8d1913daa6e'
-  data.tar.gz: 4698e55f88198a6058302c6df78062c57771e809b49b99fbdee63e21fe7b348f0bf707650e9690b46e6c975b474d1daa51ba5782dd3074655c62be67f24df621
+  metadata.gz: 902dbd67e428e7efd945017cc2a72e6d80c79250b19eabaeeceeab711c7d00669dbaecf3696778bce1780fe1f613042201eb12042370a767b2705ebc392d06b0
+  data.tar.gz: 5eb92eb2921f786ad97dbebe5131e508d7ae16d205f073fed6010ea91cdbefd0db933457ed0d628f18b54e557ea8c8c2a67f1df4c9bf5c9c3f511700ec53b01d

data/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.26] - 2026-08-28
+
+### Added
+
+- **libleptris 1.9.7 lockstep** (upstream #602/#604): Rakefile pin
+  bumped; symbol audit 247/247 with the five new functions.
+- **`Pull::Parser#each_batch(max = 256)`** — the #589 batch
+  transport: ONE C call stages up to max events (scratch-staged,
+  layout-offset drain, no per-event dispatch). Streaming big.xml
+  (250k events): 408 ms -> **210 ms per parse (-48%)**; the cursor
+  path also drops to 347 ms (Events are now constructed
+  positionally — the keyword-init Struct cost ~220 ns/event; a
+  minor API change: `Pull::Event` no longer takes keyword args,
+  readers unchanged). Per the engine's attr-mirror protocol,
+  attributes are captured for each batch's LAST start_element —
+  use `#each` when every start's attrs must be present. Attr
+  capture on both paths is now one count query + one flat copy
+  (`leptris_pull_attrs`) instead of 2N per-index dispatches.
+- **`Document#node` / `Document#children`** (#580, our upstream
+  ask): document-level PIs/comments are tree children behind a
+  stable singleton navigation head — `children` is
+  [prolog…, root, epilog…] in document order (the libxml2/Nokogiri
+  model), and `/comment()` / `//processing-instruction()` see the
+  document-level nodes. The dedicated memoized
+  `#processing_instructions` / `#comments` readers are unchanged.
+- **`NodeSet#xpath` through the union entry** (`leptris_xpath_
+  eval_nodeset`, #589): one C call for N contexts — results
+  de-duplicated and document-ordered, which the per-member Ruby
+  loop it replaces could not guarantee.
+
+### Meta
+
+- Engine swap 1.9.4 -> 1.9.7 regression battery (interleaved
+  best-of-3): cold walk 4,637 vs 4,652 µs, DOM parse 72 vs 73 µs,
+  SAX text-only 22.7 vs 22.6 ms — parity across the board. The
+  v1.9.6 XPath fixes (`/descendant::` root inclusion, $var head
+  dropping) are covered by the existing suite plus the new specs.
+
+## [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/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.9.4"
+LIBLEPTRIS_VERSION = "1.9.7"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -151,6 +151,26 @@ class Leptris::XML::Document
     Leptris::XML::Node.wrap(ptr, self)
   end
 
+  # The document node — navigation head over the whole tree chain
+  # [prolog comments/PIs, root element, epilog comments/PIs] in
+  # document order (libleptris 1.9.7, upstream #580: the libxml2
+  # model; XPath /comment() and //processing-instruction() see the
+  # document-level nodes). A stable, document-owned singleton —
+  # Node.wrap's cache keeps the returned wrapper identical.
+  def node
+    raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
+    @node ||= Leptris::XML::Node.wrap(
+      Leptris::XML::FFI.leptris_document_node(@c_ptr), self)
+  end
+
+  # The document's children, via the document node: prolog
+  # comments/PIs, the root element, epilog comments/PIs, in
+  # document order (Nokogiri-parity shape).
+  def children
+    doc_node = node
+    doc_node ? doc_node.children : Leptris::XML::NodeSet.new(self, [])
+  end
+
   # Attach +element+ as the document's root element. The element must
   # have been created against this document and must not already have
   # a parent. Any previous root is left detached (still owned by the

data/lib/leptris/xml/ffi.rb

@@ -143,6 +143,11 @@ module Leptris
         [:leptris_document, :leptris_element], :leptris_status
       attach_function :leptris_document_root,
         [:leptris_document], :leptris_element
+      # The document node — navigation head over the whole tree
+      # chain [prolog comments/PIs, root, epilog...] (libleptris
+      # 1.9.7, upstream #580; the libxml2 model).
+      attach_function :leptris_document_node,
+        [:leptris_document], :leptris_node_ref
       # Document-level PIs (v1.6.0): not tree nodes — enumerate via
       # these accessors only.
       attach_function :leptris_document_pi_count,
@@ -430,6 +435,14 @@ module Leptris
         [:leptris_document, :leptris_element, :string], :leptris_xpath_result
       attach_function :leptris_xpath_eval_with_vars,
         [:leptris_document, :string, :leptris_xpath_var_set], :leptris_xpath_result
+      # Union semantics (NodeSet#xpath): N contexts, ONE call — the
+      # engine merges the per-context results into a de-duplicated,
+      # document-ordered nodeset (libleptris 1.9.7, upstream #589).
+      attach_function :leptris_xpath_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :string], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :leptris_xpath_compiled],
+        :leptris_xpath_result
       attach_function :leptris_xpath_eval_with_vars_context,
         [:leptris_document, :leptris_element, :string, :leptris_xpath_var_set],
         :leptris_xpath_result
@@ -552,12 +565,16 @@ module Leptris
         [:string], :leptris_pull_parser
       attach_function :leptris_pull_next,
         [:leptris_pull_parser], :pointer
+      attach_function :leptris_pull_next_batch,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
       attach_function :leptris_pull_attr_count,
         [:leptris_pull_parser], :size_t
       attach_function :leptris_pull_attr_name,
         [:leptris_pull_parser, :size_t], :string
       attach_function :leptris_pull_attr_value,
         [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_attrs,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
       attach_function :leptris_pull_free,
         [:leptris_pull_parser], :void
 
@@ -817,16 +834,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 +874,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 +892,52 @@ 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
+
+      # Pull-event staging block for leptris_pull_next_batch (the
+      # #589 bulk transport): LeptrisPullEvent records, stride from
+      # the struct layout that mirrors the ABI.
+      def self.scratch_events(count)
+        need = count * PullEventStruct.size
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:pull_events]
+        if ptr.nil? || ptr.size < need
+          ptr&.free
+          ptr = scratch[:pull_events] = ::FFI::MemoryPointer.new(need)
         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/node_set.rb

@@ -127,24 +127,23 @@ class Leptris::XML::NodeSet
   end
   alias_method :text, :inner_text
 
-  # Union semantics: evaluate the expression against each element
-  # member (one C eval per member — the engine has no multi-context
-  # eval yet; leptris/leptris ask pending) and accumulate into ONE
-  # NodeSet, instead of merging NodeSets per member.
+  # Union semantics: ONE engine call evaluates the expression
+  # against every element member and merges the results into a
+  # de-duplicated, document-ordered nodeset (libleptris 1.9.7,
+  # upstream #589 — the per-member Ruby loop this replaces could
+  # neither dedup nor order).
   def xpath(*paths)
     handler, _ns, _vars = parse_search_args(paths)
     raise ArgumentError, "custom XPath handlers not supported" if handler
     expr = paths.join(" | ")
-    accumulated = []
-    each do |node|
-      next unless node.is_a?(Leptris::XML::Element)
-      result_ptr = Leptris::XML::FFI.leptris_xpath_eval(
-        @document.c_ptr, node.c_ptr, expr)
-      next if result_ptr.null?
-      accumulated.concat(
-        Leptris::XML::NodeSet.from_result(@document, result_ptr).to_a)
-    end
-    Leptris::XML::NodeSet.new(@document, accumulated)
+    contexts = to_a.select { |node| node.is_a?(Leptris::XML::Element) }
+    return Leptris::XML::NodeSet.new(@document, []) if contexts.empty?
+    buffer = Leptris::XML::FFI.scratch_pointers(contexts.size)
+    buffer.write_array_of_pointer(contexts.map(&:c_ptr))
+    result_ptr = Leptris::XML::FFI.leptris_xpath_eval_nodeset(
+      @document.c_ptr, buffer, contexts.size, expr)
+    return Leptris::XML::NodeSet.new(@document, []) if result_ptr.null?
+    Leptris::XML::NodeSet.from_result(@document, result_ptr)
   end
 
   def inspect

data/lib/leptris/xml/pull.rb

@@ -14,7 +14,10 @@ require "ffi"
 #     end
 #
 module Leptris::XML::Pull
-  Event = Struct.new(:type, :name, :text, :attrs, keyword_init: true)
+  # Constructed positionally by the parser: the keyword-init
+  # variant cost ~220ns/event in batch drains (round XXI). Readers
+  # (event.type, event.attrs, ...) are unchanged.
+  Event = Struct.new(:type, :name, :text, :attrs)
 
   TYPES = {
     Leptris::XML::FFI::PULL_START_ELEMENT => :start_element,
@@ -60,6 +63,49 @@ module Leptris::XML::Pull
       self
     end
 
+    # Bulk-delivers events (libleptris 1.9.7, upstream #589): ONE C
+    # call stages up to +max_count+ events — the per-event dispatch
+    # that made streaming ~145x slower than a DOM parse collapses to
+    # amortized noise. Per the engine's protocol, attributes are
+    # captured only for the LAST start_element of each batch
+    # (earlier starts in the same batch carry nil attrs — segment
+    # boundaries fall where they fall); use #each when every
+    # start's attrs must be captured.
+    def each_batch(max_count = 256)
+      return enum_for(:each_batch, max_count) unless block_given?
+      stride = Leptris::XML::FFI::PullEventStruct.size
+      type_off = 0
+      name_off = Leptris::XML::FFI::PullEventStruct.offset_of(:name)
+      text_off = Leptris::XML::FFI::PullEventStruct.offset_of(:text)
+      buffer = Leptris::XML::FFI.scratch_events(max_count)
+      while (n = Leptris::XML::FFI.leptris_pull_next_batch(
+               @handle, buffer, max_count)) > 0
+        events = Array.new(n) do |i|
+          base = i * stride
+          name_ptr = buffer.get_pointer(base + name_off)
+          text_ptr = buffer.get_pointer(base + text_off)
+          Event.new(
+            TYPES[buffer.get_int(base + type_off)],
+            name_ptr.null? ? nil :
+              name_ptr.read_string.force_encoding(Encoding::UTF_8),
+            text_ptr.null? ? nil :
+              text_ptr.read_string.force_encoding(Encoding::UTF_8),
+            nil
+          )
+        end
+        # The attr mirror holds the batch's most recent start.
+        last_start = nil
+        events.each_with_index do |event, i|
+          last_start = i if event.type == :start_element
+        end
+        events[last_start].attrs = capture_attrs if last_start
+        events.each { |event| yield event }
+        tail = events.last.type
+        break if tail == :end_document || tail == :error
+      end
+      self
+    end
+
     # Hot-loop offsets: derived from PullEventStruct's layout (the
     # struct stays the single source of truth for the ABI), read via
     # get_int/get_pointer so the per-event struct-wrapper allocation
@@ -80,23 +126,32 @@ module Leptris::XML::Pull
       text_ptr = raw.get_pointer(TEXT_OFFSET)
       attrs = type == :start_element ? capture_attrs : nil
       Event.new(
-        type: type,
-        name: name_ptr.null? ? nil : name_ptr.read_string.force_encoding(Encoding::UTF_8),
-        text: text_ptr.null? ? nil : text_ptr.read_string.force_encoding(Encoding::UTF_8),
-        attrs: attrs
+        type,
+        name_ptr.null? ? nil : name_ptr.read_string.force_encoding(Encoding::UTF_8),
+        text_ptr.null? ? nil : text_ptr.read_string.force_encoding(Encoding::UTF_8),
+        attrs
       )
     end
 
     private
 
+    # One count-only query plus one flat copy (leptris_pull_attrs,
+    # 1.9.7) — the char** wire format the SAX callbacks already use —
+    # replaces the 2N per-index dispatches.
     def capture_attrs
-      count = Leptris::XML::FFI.leptris_pull_attr_count(@handle)
-      return nil if count.zero?
+      total = Leptris::XML::FFI.leptris_pull_attrs(@handle, nil, 0)
+      return nil if total.zero?
+      buffer = Leptris::XML::FFI.scratch_pointers(2 * total)
+      copied = Leptris::XML::FFI.leptris_pull_attrs(@handle, buffer, total)
+      ptr_size = ::FFI.type_size(:pointer)
       hash = {}
       i = 0
-      while i < count
-        hash[Leptris::XML::FFI.leptris_pull_attr_name(@handle, i)] =
-          Leptris::XML::FFI.leptris_pull_attr_value(@handle, i)
+      while i < copied
+        name = buffer.get_pointer(2 * i * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        value = buffer.get_pointer((2 * i + 1) * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        hash[name] = value
         i += 1
       end
       hash

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.24
+  version: 1.9.26
 platform: aarch64-linux
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi