leptris 1.9.197.2-arm-linux

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

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "pathname"
+require "stringio"
+
+class Leptris::XML::SAX::Parser
+  CHUNK_SIZE = 4096
+  private_constant :CHUNK_SIZE
+
+  attr_reader :document, :encoding
+
+  # streaming: true (default, since 1.9.40) delivers through the
+  # engine transports — bulk/callback picked by override weight
+  # (leptris-ruby#95's attribute corruption is fixed upstream in
+  # libleptris 1.9.18, verified on the issue fixture). streaming:
+  # false delivers from a DOM parse (SAX::DomDispatch) — the
+  # correctness-first fallback kept for engines older than 1.9.18
+  # and for consumers wanting the DOM view's shapes.
+  def initialize(handler = Leptris::XML::SAX::Document.new,
+                 encoding = nil, streaming: true)
+    @document = handler
+    @encoding = encoding
+    @streaming = streaming
+  end
+
+  # Swapping the handler invalidates the memoized callback struct so
+  # the next parse dispatches to the new handler.
+  def document=(handler)
+    @document = handler
+    @handler_struct = nil
+    @dispatched_kinds = nil
+  end
+
+  # The handler struct (eleven FFI::Function callbacks + the C
+  # struct) is built once per handler and reused across parses; the
+  # memoized struct is anchored against GC by the instance itself.
+  def handler_struct
+    @handler_struct ||= build_handler_struct
+  end
+
+  # Parse a string, IO, or file path. Dispatches to parse_memory /
+  # parse_io / parse_file based on the argument type.
+  def parse(input)
+    case input
+    when String                then parse_memory(input)
+    when IO, StringIO, Pathname then parse_io(input)
+    else
+      raise ArgumentError, "SAX parser expects a String or IO, got #{input.class}"
+    end
+  end
+
+  def parse_memory(string)
+    # Only re-encode when the input is not already UTF-8 — a
+    # dup+force_encoding on a multi-MB document is a full copy
+    # before any parse work starts.
+    unless string.encoding == Encoding::UTF_8 && string.valid_encoding?
+      string = string.dup.force_encoding(Encoding::UTF_8)
+    end
+    unless @streaming
+      Leptris::XML::SAX::DomDispatch.parse(
+        @document, dispatched_kinds, string)
+      return self
+    end
+    if bulk_dispatch?
+      parse_memory_bulk(string)
+    else
+      handler_struct = self.handler_struct
+      rc = Leptris::XML::FFI.leptris_sax_parse(
+        string, string.bytesize, handler_struct.pointer, nil)
+      if rc != 0
+        raise Leptris::XML::ParseError,
+          "leptris_sax_parse failed (rc=#{rc})"
+      end
+    end
+    self
+  end
+
+  # Bulk transport for many-override handlers: record the whole
+  # document C-side (~12ms per 250k events), then dispatch through
+  # the recorder's drain — 250k ffi callback trampolines cost
+  # ~150ms, so this wins outright for handlers that consume most of
+  # the event stream (and beats Nokogiri's C extension on the same
+  # shape). The delivered call shapes are IDENTICAL to the callback
+  # transport (pairs arrays, arity dispatch, UTF-8, PI-data
+  # normalization) — the transports are interchangeable to the
+  # handler.
+  #
+  # Transport choice, from the round-XXVI crossover measurements:
+  # ONE overridden hot kind pays less through the callbacks (the
+  # engine skips C-side emission for unattached kinds entirely:
+  # text-only 23ms vs 43ms), while two or more hot kinds win through
+  # the recorder (start+chars 138 -> 99ms, start+end+chars 167 ->
+  # 122ms vs Nokogiri's 142ms). The weights are document-shape
+  # priors — text-heavy documents with tagged structure.
+  HOT_KIND_WEIGHTS = {
+    characters: 0.6, start_element: 0.2, end_element: 0.2,
+  }.freeze
+  private_constant :HOT_KIND_WEIGHTS
+  DISPATCH_WEIGHT_THRESHOLD = 0.8
+  private_constant :DISPATCH_WEIGHT_THRESHOLD
+
+  def parse_memory_bulk(string)
+    recorder = Leptris::XML::SAX::Recorder.open
+    begin
+      rc = recorder.feed(string, final: true)
+      recorder.dispatch(@document, dispatched_kinds)
+      if rc != 0
+        raise Leptris::XML::ParseError,
+          "leptris_sax_parse failed (rc=#{rc})"
+      end
+    ensure
+      recorder.free
+    end
+    self
+  end
+
+  # The handler's overridden-kind map — the same decisions
+  # build_handler_struct makes, in dispatch form. Memoized with the
+  # handler struct; document= invalidates both.
+  def dispatched_kinds
+    @dispatched_kinds ||= begin
+      kinds = {}
+      {
+        start_document: :start_document,
+        end_document: :end_document,
+        start_element: :start_element,
+        end_element: :end_element,
+        characters: :characters,
+        comment: :comment,
+        cdata_block: :cdata,
+        processing_instruction: :pi,
+        start_prefix_mapping: :start_prefix,
+        end_prefix_mapping: :end_prefix,
+        error: :error,
+      }.each do |method_name, kind|
+        next unless overridden?(method_name)
+        kinds[kind] =
+          if method_name == :start_element &&
+              @document.method(:start_element).arity == 1
+            :one_arg
+          else
+            true
+          end
+      end
+      kinds
+    end
+  end
+
+  def bulk_dispatch?
+    dispatched_kinds.keys.sum do |kind|
+      HOT_KIND_WEIGHTS.fetch(kind, 0.0)
+    end >= DISPATCH_WEIGHT_THRESHOLD
+  end
+
+  def parse_io(io)
+    unless @streaming
+      parse_memory(io.read)
+      return self
+    end
+    handler_struct = self.handler_struct
+    parser_ptr = Leptris::XML::FFI.leptris_sax_parser_create(
+      handler_struct.pointer, nil)
+    if parser_ptr.null?
+      raise Leptris::XML::Error, "leptris_sax_parser_create failed"
+    end
+    begin
+      while (chunk = io.read(CHUNK_SIZE))
+        rc = Leptris::XML::FFI.leptris_sax_parser_feed(
+          parser_ptr, chunk, chunk.bytesize, 0)
+        if rc != 0
+          raise Leptris::XML::ParseError, "leptris_sax_parser_feed failed (rc=#{rc})"
+        end
+      end
+      # Final flush
+      rc = Leptris::XML::FFI.leptris_sax_parser_feed(parser_ptr, "", 0, 1)
+      if rc != 0
+        raise Leptris::XML::ParseError, "leptris_sax_parser_feed (final) failed (rc=#{rc})"
+      end
+    ensure
+      Leptris::XML::FFI.leptris_sax_parser_free(parser_ptr)
+    end
+    self
+  end
+
+  def parse_file(path)
+    if @streaming
+      File.open(path, "r") { |f| parse_io(f) }
+    else
+      parse_memory(File.read(path))
+    end
+  end
+
+  private
+
+  # Build a LeptrisSAXHandler struct populated with FFI::Function callbacks
+  # 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
+
+    if overridden?(:start_document)
+      s[:start_document] = callback(:void, [:pointer]) do |_|
+        handler.start_document
+      end
+    end
+
+    if overridden?(:end_document)
+      s[:end_document] = callback(:void, [:pointer]) do |_|
+        handler.end_document
+      end
+    end
+
+    if overridden?(:start_element)
+      # Arity-declared interest: a start_element that takes exactly
+      # one argument declares name-only — the attr walk (2N pointer
+      # reads + N string pairs per start; 3.7x of an elements-only
+      # parse on the 1.9 MB stream) never runs. It is also the only
+      # way a 1-arg handler can receive events: the two-argument
+      # call raises ArgumentError.
+      if @document.method(:start_element).arity == 1
+        s[:start_element] = callback(:void, [:pointer, :string, :pointer]) do |_, name, _|
+          handler.start_element(utf8(name))
+        end
+      else
+        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
+    end
+
+    if overridden?(:end_element)
+      s[:end_element] = callback(:void, [:pointer, :string]) do |_, name|
+        handler.end_element(utf8(name))
+      end
+    end
+
+    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
+
+    if overridden?(:comment)
+      s[:comment] = callback(:void, [:pointer, :string]) do |_, comment|
+        handler.comment(utf8(comment))
+      end
+    end
+
+    if overridden?(:cdata_block)
+      s[:cdata] = callback(:void, [:pointer, :string]) do |_, cdata|
+        handler.cdata_block(utf8(cdata))
+      end
+    end
+
+    if overridden?(:processing_instruction)
+      s[:processing_instruction] = callback(:void, [:pointer, :string, :string]) do |_, target, data|
+        handler.processing_instruction(
+          utf8(target), Leptris::XML::FFI.read_pi_data(utf8(data)))
+      end
+    end
+
+    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
+
+    if overridden?(:end_prefix_mapping)
+      s[:end_prefix_mapping] = callback(:void, [:pointer, :string]) do |_, prefix|
+        handler.end_prefix_mapping(utf8(prefix))
+      end
+    end
+
+    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
+
+  # FFI's implicit :string conversion does not set encoding — every
+  # callback string param crosses the seam as ASCII-8BIT unless
+  # corrected here (the headers contract UTF-8; nil for NULL).
+  def utf8(str)
+    str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
+  end
+
+  # The C `const char** attrs` is a NULL-terminated flat array of
+  # name/value pairs. Build the [name, value] pairs in one pass —
+  # no intermediate flat string array, no each_slice enumerator.
+  def walk_attr_array(attrs_ptr)
+    ptr_size = ::FFI.type_size(:pointer)
+    pairs = []
+    i = 0
+    loop do
+      name_ptr = attrs_ptr.get_pointer(i * ptr_size)
+      break if name_ptr.null?
+      value_ptr = attrs_ptr.get_pointer((i + 1) * ptr_size)
+      pairs << [utf8(name_ptr.read_string), utf8(value_ptr.read_string)]
+      i += 2
+    end
+    pairs
+  end
+end

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

@@ -0,0 +1,374 @@
+# 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
+      unless xml_or_io.is_a?(String)
+        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
+
+  # Resets a finished recorder for the next document (libleptris
+  # 1.9.10, upstream #594): fresh parser state, record/arena
+  # buffers retained — a one-document-per-parse loop reuses ONE
+  # recorder without new/free churn. Records restart empty.
+  def reset
+    rc = Leptris::XML::FFI.leptris_sax_recorder_reset(@handle)
+    if rc != 0
+      raise Leptris::XML::Error, "leptris_sax_recorder_reset failed"
+    end
+    self
+  end
+
+  # Feed one chunk; records/arena reset at feed entry, so drain
+  # after every feed. Returns self.
+  def feed(chunk, final: false)
+    unless chunk.encoding == Encoding::UTF_8 && chunk.valid_encoding?
+      chunk = chunk.dup.force_encoding(Encoding::UTF_8)
+    end
+    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
+
+  # Which kinds carry each string field (the record layout leaves
+  # the other at offset 0 / length 0): slicing a zero-length run
+  # allocates a wasted empty String per event — 150k+ of them on a
+  # text-heavy document. Unused fields yield nil (the callback
+  # transport delivers no name for characters either).
+  HAS_NAME = {
+    start_element: true, end_element: true,
+    pi: true, start_prefix: true, end_prefix: true,
+  }.freeze
+  HAS_TEXT = {
+    characters: true, comment: true, cdata: true,
+    pi: true, start_prefix: true, error: true,
+  }.freeze
+
+  # Layout offsets (the struct stays the ABI's single source of
+  # truth) and per-count kind-strip templates: one byte per record,
+  # skipping the stride — the kind codes are 0..10, so the strip
+  # unpacks to cache-resident Fixnums, unlike the old whole-record
+  # unpack whose 2.25M-Integer array for a single-feed drain was
+  # most of the loop's allocation profile.
+  RECORD = Leptris::XML::FFI::SaxEventRecord
+  NAME_OFF = RECORD.offset_of(:name_off)
+  NAME_LEN = RECORD.offset_of(:name_len)
+  TEXT_OFF = RECORD.offset_of(:text_off)
+  TEXT_LEN = RECORD.offset_of(:text_len)
+  ATTRS_OFF = RECORD.offset_of(:attrs_off)
+  ATTR_COUNT = RECORD.offset_of(:attr_count)
+  LINE_OFF = RECORD.offset_of(:line)
+  COLUMN_OFF = RECORD.offset_of(:column)
+  RECORD_STRIDE = RECORD.size
+  SAX_EVENT_CHARACTERS_CODE = Leptris::XML::FFI::SAX_EVENT_CHARACTERS
+  NUL = "\0".freeze
+  KIND_TEMPLATE_FOR = ::Hash.new do |cache, count|
+    cache[count] = ("C x#{RECORD_STRIDE - 1}" * count)
+  end
+
+  # Dispatch drain: delivers the recorded events as handler method
+  # calls with the CALLBACK transport's exact shapes — pairs arrays
+  # (not hashes), one-argument start_element arity dispatch, UTF-8
+  # strings, PI-data whitespace normalization. +dispatched+ maps
+  # kind symbols to true for the kinds the handler overrides (the
+  # attach-only-overridden policy carried onto the bulk transport:
+  # other records cost one strip read). The C recorder costs ~12ms
+  # per 250k-event document while 250k ffi callback trampolines
+  # cost ~150ms — this is how a many-override handler beats the
+  # callback transport (and Nokogiri's C extension) outright.
+  def dispatch(handler, dispatched)
+    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
+      # Kind strip in ONE bulk read + ONE unpack per drain: the
+      # per-count template reads the first byte of each record,
+      # skipping the stride (KIND_TEMPLATE_FOR is memoized per
+      # count). Kind codes are 0..10 — unpack yields immediate
+      # Fixnums, so the strip allocates nothing. This replaces a
+      # get_uint8 crossing per EVENT (all events, dispatched or
+      # not) with one memory read per drain — the SAX gap to
+      # Nokogiri's per-event C callback lives exactly here.
+      kinds = records_ptr.get_bytes(0, count * RECORD_STRIDE)
+                         .unpack(KIND_TEMPLATE_FOR[count])
+      one_arg_start = dispatched[:start_element] == :one_arg
+      i = 0
+      while i < count
+        kind = kinds[i] && KIND_BY_CODE[kinds[i]]
+        if kind && dispatched[kind]
+          base = i * RECORD_STRIDE
+          case kind
+          when :characters
+            handler.characters(slice(arena,
+              records_ptr.get_uint32(base + TEXT_OFF),
+              records_ptr.get_uint32(base + TEXT_LEN)))
+          when :start_element
+            name = slice(arena,
+              records_ptr.get_uint32(base + NAME_OFF),
+              records_ptr.get_uint32(base + NAME_LEN))
+            if one_arg_start
+              handler.start_element(name)
+            else
+              handler.start_element(name, attrs_pairs(arena,
+                records_ptr.get_uint32(base + ATTRS_OFF),
+                records_ptr.get_uint32(base + ATTR_COUNT)))
+            end
+          when :end_element
+            handler.end_element(slice(arena,
+              records_ptr.get_uint32(base + NAME_OFF),
+              records_ptr.get_uint32(base + NAME_LEN)))
+          when :comment
+            handler.comment(slice(arena,
+              records_ptr.get_uint32(base + TEXT_OFF),
+              records_ptr.get_uint32(base + TEXT_LEN)))
+          when :cdata
+            handler.cdata_block(slice(arena,
+              records_ptr.get_uint32(base + TEXT_OFF),
+              records_ptr.get_uint32(base + TEXT_LEN)))
+          when :pi
+            handler.processing_instruction(slice(arena,
+              records_ptr.get_uint32(base + NAME_OFF),
+              records_ptr.get_uint32(base + NAME_LEN)),
+              Leptris::XML::FFI.read_pi_data(slice(arena,
+                records_ptr.get_uint32(base + TEXT_OFF),
+                records_ptr.get_uint32(base + TEXT_LEN))))
+          when :start_prefix
+            handler.start_prefix_mapping(slice(arena,
+              records_ptr.get_uint32(base + NAME_OFF),
+              records_ptr.get_uint32(base + NAME_LEN)),
+              slice(arena,
+                records_ptr.get_uint32(base + TEXT_OFF),
+                records_ptr.get_uint32(base + TEXT_LEN)))
+          when :end_prefix
+            handler.end_prefix_mapping(slice(arena,
+              records_ptr.get_uint32(base + NAME_OFF),
+              records_ptr.get_uint32(base + NAME_LEN)))
+          when :error
+            handler.error(slice(arena,
+              records_ptr.get_uint32(base + TEXT_OFF),
+              records_ptr.get_uint32(base + TEXT_LEN)),
+              records_ptr.get_uint32(base + LINE_OFF),
+              records_ptr.get_uint32(base + COLUMN_OFF))
+          when :start_document
+            handler.start_document
+          when :end_document
+            handler.end_document
+          end
+        end
+        i += 1
+      end
+    ensure
+      count_ptr.free
+      len_ptr.free
+    end
+    self
+  end
+
+  # attrs as [name, value] pairs in source order — the callback
+  # transport's shape (walk_attr_array).
+  def attrs_pairs(arena, off, count)
+    return [] if count.zero?
+    pairs = []
+    pos = off
+    nul = NUL
+    utf8 = Encoding::UTF_8
+    while count > 0
+      name_end = arena.index(nul, pos)
+      name = arena.byteslice(pos, name_end - pos).force_encoding(utf8)
+      pos = name_end + 1
+      value_end = arena.index(nul, pos)
+      pairs << [name,
+        arena.byteslice(pos, value_end - pos).force_encoding(utf8)]
+      pos = value_end + 1
+      count -= 1
+    end
+    pairs
+  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
+
+      # Kind is the first byte of each record — read off the C
+      # pointer. The previous path copied every record and unpacked
+      # a Fixnum array just for the kind strip.
+      has_name = HAS_NAME
+      has_text = HAS_TEXT
+      drain = wanted.nil?
+      i = 0
+      while i < count
+        base = i * RECORD_STRIDE
+        code = records_ptr.get_uint8(base)
+        if code == SAX_EVENT_CHARACTERS_CODE && drain
+          # The dominant branch (text-heavy documents): no name, no
+          # attrs, no per-kind gate lookups — kind, text, position.
+          yield :characters, nil,
+                slice(arena, records_ptr.get_uint32(base + TEXT_OFF),
+                             records_ptr.get_uint32(base + TEXT_LEN)),
+                nil,
+                records_ptr.get_uint32(base + LINE_OFF),
+                records_ptr.get_uint32(base + COLUMN_OFF)
+        else
+          kind = KIND_BY_CODE[code]
+          if kind && (drain || wanted[kind])
+            name = if has_name[kind]
+                     slice(arena, records_ptr.get_uint32(base + NAME_OFF),
+                                  records_ptr.get_uint32(base + NAME_LEN))
+                   end
+            text = if has_text[kind]
+                     slice(arena, records_ptr.get_uint32(base + TEXT_OFF),
+                                  records_ptr.get_uint32(base + TEXT_LEN))
+                   end
+            text = Leptris::XML::FFI.read_pi_data(text) if kind == :pi
+            yield kind, name, text,
+                  attrs_from(arena, records_ptr.get_uint32(base + ATTRS_OFF),
+                                    records_ptr.get_uint32(base + ATTR_COUNT)),
+                  records_ptr.get_uint32(base + LINE_OFF),
+                  records_ptr.get_uint32(base + COLUMN_OFF)
+          end
+        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
+
+  # The default-namespace prefix is legitimately "" (START_PREFIX:
+  # name may be zero-length) — zero-length slices stay "" where the
+  # field is carried (unused fields never reach here).
+  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
+    nul = NUL
+    utf8 = Encoding::UTF_8
+    while count > 0
+      name_end = arena.index(nul, pos)
+      name = arena.byteslice(pos, name_end - pos).force_encoding(utf8)
+      pos = name_end + 1
+      value_end = arena.index(nul, pos)
+      hash[name] =
+        arena.byteslice(pos, value_end - pos).force_encoding(utf8)
+      pos = value_end + 1
+      count -= 1
+    end
+    hash
+  end
+end