leptris 1.9.21-aarch64-linux → 1.9.24-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a10b8e5a3f59b43792a986200af06e1d8f5ed09006b94272adf423546b9b5d3
-  data.tar.gz: 0f23a65d72a713b0221e6d67b68ef11b0f1244472ab17470924d41afe1018c0e
+  metadata.gz: 1be15b3c37fddd0b1f5c30c79b08adae540825a34605ffa2d44f8c9800dc1cd5
+  data.tar.gz: e008a194237148e03af56e37032cd3e3e30c1762680d3013b5cb3053af4a7c21
 SHA512:
-  metadata.gz: b926e9e47f7b86dec2a7ca0768052a31b430849a020ceb10b4cd970b51299b750da3928bae592e254994170c0891a003c1be3e6a73179ea0b38f9fa8b079d26a
-  data.tar.gz: 8201fa8740f34c221fc72f26e1572ad4199af57042aecdb6ad7b0f3b120172a1b0fa2c6e6963b400b966547433a50e47417c9043e5444acbc059d669be74c617
+  metadata.gz: '04893f33c1d19df655b5ae1e5aeb15cd753988e1f7f7872f5984fa6a011863c59c860919186d7f688dbc200e3d2cc76c5266917ff0293f7ad125d8d1913daa6e'
+  data.tar.gz: 4698e55f88198a6058302c6df78062c57771e809b49b99fbdee63e21fe7b348f0bf707650e9690b46e6c975b474d1daa51ba5782dd3074655c62be67f24df621

data/CHANGELOG.md

@@ -5,6 +5,74 @@ 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.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
+
+- **libleptris 1.9.4 lockstep** (leptris/leptris#585, #586): Rakefile
+  pin bumped; symbol audit 242/242 attached-vs-exported with the ten
+  new functions.
+- **`SAX::Recorder`**: public chunked-event API over the C recorder —
+  `Recorder.parse(xml_or_io)` / `Recorder#feed` / `#each_event`
+  yield `kind, name, text, attrs, line, column` with UTF-8 strings,
+  drained as one bulk read per chunk (records via `read_bytes` +
+  `unpack` against the packed string arena — no per-event FFI
+  struct). NOT wired into `SAX::Parser#parse_memory`: measured
+  parity-to-−30% vs the callback path (per-parse recorder setup
+  scales with input size; findings and measurements filed upstream
+  as leptris/leptris#594). It remains the right shape for hosts
+  that drain bulk events per chunk.
+- **Iterparse v2** (#586): `Iterparse.parse` / `.parse_file` take
+  `mode:` — `:top_level` (v1: the root's completed children) or
+  `:full_document` (every element, post-order, child before parent).
+  `#namespace_uri(prefix)` / `#namespace_count` resolve prefixes on
+  the last yielded element's in-scope snapshot (call inside the run
+  block); `#error` reports truncated/malformed input.
+
+### Changed
+
+- **Iterparse lifecycle**: `#run` no longer frees in `ensure` — the
+  block form of `.parse`/`.parse_file` frees on return (Pull's
+  pattern), the no-block form returns a live iterator for explicit
+  `#free`. This fixes the `enum_for` path, which previously freed
+  the handle before the enumerator drove it, and lets `#error`
+  stay readable after the run (`#free` snapshots the terminal
+  message). Full-document mode measures +36% CPU over top-level —
+  proportional to yielding every element instead of root children.
+
+### Meta
+
+- Head-to-head vs published 1.9.21 (engine 1.9.0 vs 1.9.4): SAX
+  callback parsing and iterparse at parity across two passes; no
+  regression from the engine bump.
+
 ## [1.9.21] - 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.3"
+LIBLEPTRIS_VERSION = "1.9.4"
 
 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.21"
+  VERSION = "1.9.24"
 end

data/lib/leptris/xml/ffi.rb

@@ -43,6 +43,7 @@ module Leptris
       typedef :pointer, :leptris_xpath_ns_set
       typedef :pointer, :leptris_xpath_compiled
       typedef :pointer, :leptris_xslt
+      typedef :pointer, :leptris_sax_recorder
       typedef :pointer, :leptris_pull_parser
       typedef :pointer, :leptris_iterparse
       typedef :pointer, :leptris_xpath_var_set
@@ -81,6 +82,33 @@ module Leptris
           :recover, :int
       end
 
+      # LeptrisSaxEventRecord (types.h, issue #585): fixed layout the
+      # header explicitly freezes for FFI mirrors. Strings are NOT
+      # inline — name/text/attrs slice the recorder's arena.
+      class SaxEventRecord < ::FFI::Struct
+        layout :kind, :uint8,
+               :reserved, [:uint8, 7],
+               :name_off, :uint32, :name_len, :uint32,
+               :text_off, :uint32, :text_len, :uint32,
+               :attrs_off, :uint32, :attr_count, :uint32,
+               :line, :uint32, :column, :uint32
+      end
+
+      SAX_EVENT_START_DOCUMENT = 0
+      SAX_EVENT_END_DOCUMENT   = 1
+      SAX_EVENT_START_ELEMENT  = 2
+      SAX_EVENT_END_ELEMENT    = 3
+      SAX_EVENT_CHARACTERS     = 4
+      SAX_EVENT_COMMENT        = 5
+      SAX_EVENT_CDATA          = 6
+      SAX_EVENT_PI             = 7
+      SAX_EVENT_START_PREFIX   = 8
+      SAX_EVENT_END_PREFIX     = 9
+      SAX_EVENT_ERROR          = 10
+
+      ITERPARSE_TOP_LEVEL      = 0
+      ITERPARSE_FULL_DOCUMENT  = 1
+
       # struct LeptrisPullEvent (leptris/sax.h): FFI::Struct derives
       # the field offsets from the layout, so ABI changes are a
       # one-line edit here instead of silent offset drift in callers.
@@ -499,6 +527,19 @@ module Leptris
         [:pointer, :pointer], :leptris_sax_parser
       attach_function :leptris_sax_parser_feed,
         [:leptris_sax_parser, :string, :size_t, :int], :int
+      # Chunked event recorder (libleptris 1.9.4, #585): buffers
+      # events C-side (fixed records + packed arena); the host
+      # drains in bulk — callbacks become O(chunks), not O(events).
+      attach_function :leptris_sax_recorder_new,
+        [], :leptris_sax_recorder
+      attach_function :leptris_sax_recorder_feed,
+        [:leptris_sax_recorder, :string, :size_t, :int], :int
+      attach_function :leptris_sax_recorder_records,
+        [:leptris_sax_recorder, :pointer], :pointer
+      attach_function :leptris_sax_recorder_arena,
+        [:leptris_sax_recorder, :pointer], :pointer
+      attach_function :leptris_sax_recorder_free,
+        [:leptris_sax_recorder], :void
       attach_function :leptris_sax_parser_free,
         [:leptris_sax_parser], :void
       attach_function :leptris_sax_parser_set_streaming,
@@ -528,6 +569,19 @@ module Leptris
         [:string], :leptris_iterparse
       attach_function :leptris_iterparse_next,
         [:leptris_iterparse], :leptris_element
+      # iterparse v2 (libleptris 1.9.4, #586): explicit yield mode
+      # (top-level children or full-document post-order), namespace
+      # resolution on the last yielded element, error channel.
+      attach_function :leptris_iterparse_new_ex,
+        [:string, :size_t, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_new_file_ex,
+        [:string, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_ns_count,
+        [:leptris_iterparse], :size_t
+      attach_function :leptris_iterparse_ns_uri,
+        [:leptris_iterparse, :string], :string
+      attach_function :leptris_iterparse_error,
+        [:leptris_iterparse], :string
       attach_function :leptris_iterparse_free,
         [:leptris_iterparse], :void
 

data/lib/leptris/xml/iterparse.rb

@@ -12,34 +12,78 @@ require "ffi"
 #       process(element)   # subtree valid until the next iteration
 #     end
 #
-# v1 limitation (upstream): element names are the QName as written;
-# namespace prefixes are not re-resolved — use the DOM path when
-# namespace URIs matter. The yielded elements have no parent
-# Document; #document returns nil and they must not outlive the
-# iteration.
+# v2 (libleptris 1.9.4, #586): an explicit yield mode —
+# :top_level (v1: the root's completed children) or
+# :full_document (every element in document-order completion —
+# post-order, child before parent, subtree attached) — plus
+# namespace resolution on the last yielded element and an error
+# channel for truncated input:
+#
+#     it = Leptris::XML::Iterparse.parse(xml, mode: :full_document)
+#     it.run do |el|
+#       it.namespace_uri("p")   # in scope on el, the last yielded
+#     end
+#     it.free
+#
+#     Leptris::XML::Iterparse.parse(xml) { |el| ... }.error
+#     # => nil, or the parse failure (readable after the run: the
+#     #    block form frees the iterator on return, snapshotting it)
+#
+# The yielded elements have no parent Document; #document returns
+# nil and they must not outlive the iteration.
 class Leptris::XML::Iterparse
+  MODES = {
+    top_level: Leptris::XML::FFI::ITERPARSE_TOP_LEVEL,
+    full_document: Leptris::XML::FFI::ITERPARSE_FULL_DOCUMENT,
+  }.freeze
+
   # NOTE: an IO argument is read fully into memory before the C
   # iterator starts — the bounded-memory path is parse_file (C-side
   # file streaming). The C API takes one (xml, len) buffer.
-  def self.parse(xml_or_io, &block)
+  def self.parse(xml_or_io, mode: :top_level, &block)
     xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
-    iterator = new(Leptris::XML::FFI.leptris_iterparse_new(xml, xml.bytesize))
-    iterator.run(&block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_ex(
+      xml, xml.bytesize, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
   end
 
-  def self.parse_file(path, &block)
-    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file(path))
-    iterator.run(&block)
+  def self.parse_file(path, mode: :top_level, &block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file_ex(
+      path, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
+  end
+
+  def self.mode_code(mode)
+    MODES.fetch(mode) do
+      raise ArgumentError,
+        "mode must be :top_level or :full_document, got #{mode.inspect}"
+    end
   end
+  private_class_method :mode_code
 
   def initialize(handle)
     raise Leptris::XML::ParseError, "leptris_iterparse_new failed" if handle.null?
     @handle = handle
   end
 
+  # Yields completed elements until the document is exhausted or the
+  # parse fails (see #error). Does not free the iterator — the block
+  # form of .parse/.parse_file does, or call #free explicitly.
   def run
     return enum_for(:run) unless block_given?
-    loop do
+    while @handle
       ptr = Leptris::XML::FFI.leptris_iterparse_next(@handle)
       break if ptr.null?
       # document: nil — the subtree belongs to the iterator's pool,
@@ -48,13 +92,44 @@ class Leptris::XML::Iterparse
       yield Leptris::XML::Node.wrap(ptr, nil)
     end
     self
-  ensure
-    free
   end
 
+  # The URI bound to +prefix+ ("" for the default namespace) in the
+  # last yielded element's in-scope namespace snapshot, or nil when
+  # unbound (v2, #586). Valid only while the iterator is live —
+  # call it inside the #run block; nil after #free.
+  def namespace_uri(prefix)
+    return nil if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_uri(@handle, prefix.to_s)
+  end
+
+  # Number of namespace bindings in the last yielded element's
+  # scope. Valid only while the iterator is live; 0 after #free.
+  def namespace_count
+    return 0 if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_count(@handle)
+  end
+
+  # The parse error for malformed/truncated input, or nil when the
+  # document is well-formed and exhausted. Yielded elements stop at
+  # the failure point; #free snapshots the message so this stays
+  # readable after the block form of .parse returns.
+  def error
+    @handle ? live_error : @last_error
+  end
+
+  # Releases the C iterator. Safe to call twice.
   def free
     return if @handle.nil?
+    @last_error = live_error
     Leptris::XML::FFI.leptris_iterparse_free(@handle)
     @handle = nil
   end
+
+  private
+
+  def live_error
+    msg = Leptris::XML::FFI.leptris_iterparse_error(@handle)
+    msg.nil? || msg.empty? ? nil : msg
+  end
 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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Chunked event recorder (libleptris 1.9.4, issue #585): a SAX
+# transport that buffers events C-side — fixed LeptrisSaxEventRecord
+# entries plus a packed string arena — and drains them in one bulk
+# read per fed chunk. The handler receives the identical calls the
+# callback API makes; only the transport changes, and the callback
+# count becomes O(chunks), not O(events): through FFI, per-event
+# C-to-Ruby dispatch cost more than the parse itself.
+#
+#     Leptris::XML::SAX::Recorder.parse(xml) do |kind, name, text, attrs|
+#       # kind: :start_element, :characters, ... (see KINDS)
+#     end
+#
+class Leptris::XML::SAX::Recorder
+  KINDS = {
+    Leptris::XML::FFI::SAX_EVENT_START_DOCUMENT => :start_document,
+    Leptris::XML::FFI::SAX_EVENT_END_DOCUMENT => :end_document,
+    Leptris::XML::FFI::SAX_EVENT_START_ELEMENT => :start_element,
+    Leptris::XML::FFI::SAX_EVENT_END_ELEMENT => :end_element,
+    Leptris::XML::FFI::SAX_EVENT_CHARACTERS => :characters,
+    Leptris::XML::FFI::SAX_EVENT_COMMENT => :comment,
+    Leptris::XML::FFI::SAX_EVENT_CDATA => :cdata,
+    Leptris::XML::FFI::SAX_EVENT_PI => :pi,
+    Leptris::XML::FFI::SAX_EVENT_START_PREFIX => :start_prefix,
+    Leptris::XML::FFI::SAX_EVENT_END_PREFIX => :end_prefix,
+    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?
+      raise Leptris::XML::Error, "leptris_sax_recorder_new failed"
+    end
+    new(raw)
+  end
+
+  # One-shot parse over a complete document, yielding Record structs.
+  # +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, kinds: kinds) { |*args| yield(*args) }
+      else
+        recorder.feed(xml_or_io.to_s, final: true)
+        recorder.each_event(*Array(kinds)) { |*args| yield(*args) }
+      end
+    ensure
+      recorder.free
+    end
+  end
+
+  def initialize(handle)
+    @handle = handle
+  end
+
+  def free
+    return if @handle.nil?
+    Leptris::XML::FFI.leptris_sax_recorder_free(@handle)
+    @handle = nil
+  end
+
+  # Feed one chunk; records/arena reset at feed entry, so drain
+  # after every feed. Returns self.
+  def feed(chunk, final: false)
+    chunk = chunk.dup.force_encoding(Encoding::UTF_8)
+    rc = Leptris::XML::FFI.leptris_sax_recorder_feed(
+      @handle, chunk, chunk.bytesize, final ? 1 : 0)
+    rc
+  end
+
+  # Feed an IO in chunks, draining events after each chunk.
+  def feed_stream(io, chunk_size = 65_536, kinds: nil, &block)
+    while (chunk = io.read(chunk_size))
+      feed(chunk)
+      each_event(*Array(kinds), &block)
+    end
+    feed("", final: true)
+    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. 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
+      records_ptr = Leptris::XML::FFI.leptris_sax_recorder_records(
+        @handle, count_ptr)
+      return self if records_ptr.null? || count_ptr.read_uint64.zero?
+
+      arena_ptr = Leptris::XML::FFI.leptris_sax_recorder_arena(
+        @handle, len_ptr)
+      arena = arena_ptr.read_bytes(len_ptr.read_uint64)
+      count = count_ptr.read_uint64
+
+      # The whole record block in ONE read: read_bytes + String#unpack
+      # (C-fast) — two FFI calls per chunk total (records + arena),
+      # the true bulk discipline. Template per record: kind byte,
+      # 7 pad, then the eight uint32 fields (little-endian hosts —
+      # the layout the header freezes for FFI mirrors).
+      stride = Leptris::XML::FFI::SaxEventRecord.size
+      fields = records_ptr.read_bytes(count * stride)
+        .unpack("C x7 V8" * count)
+
+      i = 0
+      while i < count
+        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]),
+                slice(arena, fields[base + 2], fields[base + 3]),
+                attrs_from(arena, fields[base + 4], fields[base + 5]),
+                fields[base + 6], fields[base + 7]
+        end
+        i += 1
+      end
+    ensure
+      count_ptr.free
+      len_ptr.free
+    end
+    self
+  end
+
+  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.
+  def slice(arena, off, len)
+    arena.byteslice(off, len).force_encoding(Encoding::UTF_8)
+  end
+
+  # attrs_off addresses name\0value\0... pairs, attr_count pairs;
+  # nil when the element carries none.
+  def attrs_from(arena, off, count)
+    return nil if count.zero?
+    hash = {}
+    pos = off
+    count.times do
+      name_end = arena.index("\0", pos)
+      name = arena.byteslice(pos, name_end - pos)
+      pos = name_end + 1
+      value_end = arena.index("\0", pos)
+      value = arena.byteslice(pos, value_end - pos)
+      pos = value_end + 1
+      hash[name.force_encoding(Encoding::UTF_8)] =
+        value.force_encoding(Encoding::UTF_8)
+    end
+    hash
+  end
+end

data/lib/leptris/xml/sax.rb

@@ -7,6 +7,7 @@ module Leptris
     module SAX
       autoload :Document, "leptris/xml/sax/document"
       autoload :Parser, "leptris/xml/sax/parser"
+      autoload :Recorder, "leptris/xml/sax/recorder"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.21
+  version: 1.9.24
 platform: aarch64-linux
 authors:
 - Ribose Inc.
@@ -99,6 +99,7 @@ files:
 - lib/leptris/xml/sax.rb
 - lib/leptris/xml/sax/document.rb
 - lib/leptris/xml/sax/parser.rb
+- lib/leptris/xml/sax/recorder.rb
 - lib/leptris/xml/searchable.rb
 - lib/leptris/xml/serialization.rb
 - lib/leptris/xml/text.rb