leptris 1.9.174.2 → 1.9.174.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb172d69b816cff764e249cd5708a2394e7e4886a5c5281bf69160f876550c20
-  data.tar.gz: 22ff15b7a5dbaee59a9643f150662321e6f52267cb96b47c6621e73957615f46
+  metadata.gz: 741e98553c4d88169d4c2f8ec0fb793eeebd80ffd8b00771fcfb0be218721f64
+  data.tar.gz: 5e02a23549a4e1c708dc40710b499e64fcd83150772dd08c8bbeac7fc77f0718
 SHA512:
-  metadata.gz: d86e101b19a89c87b3ff67fc6fae563da827d3b389618fbada51cb9bcd387e772b474315e4d3d9f21bd6dd4bb1429df5b5f1de624787fc02db889dd6b1dc6efc
-  data.tar.gz: c20c6f8446a7aef0b0d08c672deccf1d5aaa7653fe04e8f69c6a8a1b0f641f6bb5221d44f0c28f0cabcfb901ce2762ce5eed3ed6fa427b2231935bda1c6bd9b9
+  metadata.gz: b1a3b25cd5b770b6edfb06bc2d448dacd691dc7e5af3fb301454fb1057e419c5fc779e4c9556a3f3b4be654ea5ec36be8f8e5c4e0f7ab16af380b6986da3bcb5
+  data.tar.gz: 85e81207c2abaca9a80af5dcfb33ae4e4f83c2ec24950b16d38fcb239bf7fa4d01b40d4d88b7fa19e019ba35a9ce58984c823e3f049fc47492459ebde53aa47b

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.174.3] - 2026-09-15
+
+### Changed
+
+- **Lazy FFI::Pointer on wrappers (TODO.perf/19)**: the node's
+  canonical state is the Integer address; the Pointer
+  materializes only when read — the C construction faces stop
+  minting one per node (~200ns + one allocation each, and
+  proportionally less GC). Public `c_ptr` API and identity
+  unchanged. Measured (load 22-25): GC-amortized
+  `Document.create` ~5-6µs → ~4.0µs; `NativeNode#[]` 78ns
+  (budget 70), `#content` 45ns (budget 58 met).
+- **CSS translation cache (TODO.perf/20)**: repeat selectors skip
+  the per-call regex translation straight to the compiled handle;
+  the single-path xpath shape no longer allocates a joined
+  String per call.
+- **`Element#key?` consults the attribute memo (TODO.perf/21)**
+  before the engine round-trip; miss semantics unchanged.
+
 ## [1.9.174.2] - 2026-09-15
 
 ### Changed

data/TODO.perf/19-lazy-node-pointer.md

@@ -0,0 +1,39 @@
+# 19 — Lazy FFI::Pointer on wrappers
+
+Status: DONE (1.9.174.3)
+
+Every binding wrapper stores an FFI::Pointer (@c_ptr), and the C
+construction faces mint one per node via
+rb_funcall(FFI::Pointer, :new) — ~200ns plus a Ruby object and
+its GC visit per node, paid at creation even though most nodes'
+Pointers are never read (the hot reads are memoized or go through
+the address-based native faces).
+
+Store @c_address (Integer) as the canonical truth on every
+wrapper; `c_ptr` becomes a lazy materializer
+(@c_ptr ||= FFI::Pointer.new(@c_address)) preserving the public
+API. Internal call sites: `@c_ptr.address` collapses to
+@c_address (also skipping the #address dispatch), and remaining
+internal @c_ptr reads go through the c_ptr reader (same cost as
+the old attr_reader). The C faces stop constructing Pointers
+entirely — they already hold the address.
+
+Gates: suite green both modes (a missed site fails loudly — nil
+to FFI raises TypeError); wrapper identity and c_ptr stability
+unchanged; creation faces drop ~200ns and one allocation per
+node; fresh-doc build row improves accordingly.
+
+## Outcome (1.9.174.3)
+
+@c_address is the canonical truth on every Node wrapper; c_ptr
+materializes lazily (@c_ptr ||= FFI::Pointer.new(@c_address)),
+preserving the public API and identity. All internal @c_ptr
+reads became c_ptr reader calls; the 15 @c_ptr.address sites
+collapsed to @c_address (also skipping the #address dispatch).
+The C construction faces (create element/text, bulk children,
+every xpath materialization) stopped minting Pointers entirely —
+one allocation and ~200ns saved per node, and proportionally less
+GC. Document keeps its eager reader (documents are few).
+Measured under host load 22-25: GC-amortized Document.create
+~5-6µs -> ~4.0µs; NativeNode#[] 78ns (budget 70 — clear at
+load <10), content 45ns (budget 58 met).

data/TODO.perf/20-css-translation-cache.md

@@ -0,0 +1,24 @@
+# 20 — CSS translation cache
+
+Status: DONE (1.9.174.3)
+
+Searchable#css/#at_css run CssToXPath.convert on every call —
+pure Ruby regex/string work (~300ns+) — before the compiled-
+expression cache (TODO.perf/15) can hit on the result. The
+translation is a pure function of (selector, prefix); cache it
+with the same bounded-LRU shape (64 entries, Hash#shift
+eviction, GVL-safe), so repeat selectors skip straight to the
+compiled handle.
+
+Gates: css/at_css results identical; repeat-call rows improve by
+the translation cost; the join in xpath()'s expression build is
+also skipped for the single-String-path shape (join minted a
+fresh String per call even for one path).
+
+## Outcome (1.9.174.3)
+
+Searchable.css_expression: bounded LRU (64, shared limit) keyed
+on prefix+selector; css/at_css translate through it so repeat
+selectors skip the regex machinery straight to the compiled-
+expression cache. The single-String-path shape of xpath/at_xpath
+no longer joins (join minted a fresh String per call).

data/TODO.perf/21-key-memo-consult.md

@@ -0,0 +1,20 @@
+# 21 — key? consults the attribute memo
+
+Status: DONE (1.9.174.3)
+
+Element#key?/has_attribute? pays an engine FFI round-trip per
+call even when the versioned @attr_values memo already proves
+presence. Consult the memo first (hit = true; only a miss falls
+through to the engine + written-name fallback — the memo cannot
+prove ABSENCE for a partial fill).
+
+Gates: key? true for memoized names, unchanged miss semantics
+(undeclared-prefix fallback intact), readonly/namespace specs
+green.
+
+## Outcome (1.9.174.3)
+
+Element#key? consults the versioned @attr_values memo first —
+presence-proven hits skip the engine round-trip; partial-fill
+misses still fall through to the engine + written-name fallback
+(the memo cannot prove absence).

data/ext/leptris/native/native.c

@@ -870,9 +870,8 @@ static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
         key = ULL2NUM((uint64_t)(uintptr_t)buf[i]);
         node = rb_hash_aref(cache, key);
         if (NIL_P(node)) {
-            VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
             node = rb_obj_alloc(binding_klass_for(kinds[i]));
-            rb_iv_set(node, "@c_ptr", ptr);
+            rb_iv_set(node, "@c_address", key);
             rb_iv_set(node, "@document", document);
             rb_iv_set(node, "@parent", Qnil);
             rb_iv_set(node, "@structure_memoizable", Qtrue);
@@ -965,9 +964,8 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
     case 0: /* element */
         node = rb_hash_aref(cache, key);
         if (NIL_P(node)) {
-            VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
             node = rb_obj_alloc(c_b_element);
-            rb_iv_set(node, "@c_ptr", p);
+            rb_iv_set(node, "@c_address", key);
             rb_iv_set(node, "@document", document);
             rb_iv_set(node, "@parent", Qnil);
             rb_iv_set(node, "@structure_memoizable", Qtrue);
@@ -980,9 +978,8 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
         {
             const char *name = f_xp_node_name(result, idx);
             const char *value = f_xp_node_value(result, idx);
-            VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
             node = rb_obj_alloc(c_b_result_attr);
-            rb_iv_set(node, "@c_ptr", p);
+            rb_iv_set(node, "@c_address", key);
             rb_iv_set(node, "@document", document);
             rb_iv_set(node, "@attr_name",
                       name ? rb_utf8_str_new_cstr(name) : Qnil);
@@ -998,8 +995,7 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
             if (nt == 8) { /* NODE_SYNTHETIC_TEXT */
                 s = f_xp_node_value(result, idx);
                 node = rb_obj_alloc(c_b_result_text);
-                rb_iv_set(node, "@c_ptr",
-                          rb_funcall(c_ffi_pointer, id_ptr_new, 1, key));
+                rb_iv_set(node, "@c_address", key);
                 rb_iv_set(node, "@document", document);
                 rb_iv_set(node, "@value",
                           s ? rb_utf8_str_new_cstr(s) : Qnil);
@@ -1007,9 +1003,8 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
             }
             node = rb_hash_aref(cache, key);
             if (NIL_P(node)) {
-                VALUE p = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
                 node = rb_obj_alloc(binding_klass_for(nt));
-                rb_iv_set(node, "@c_ptr", p);
+                rb_iv_set(node, "@c_address", key);
                 rb_iv_set(node, "@document", document);
                 rb_iv_set(node, "@parent", Qnil);
                 rb_iv_set(node, "@structure_memoizable", Qtrue);
@@ -1096,9 +1091,8 @@ static VALUE nf_create_binding_element(VALUE self, VALUE document,
     if (!ptr)
         return Qnil; /* caller raises with the error channel */
     node = rb_obj_alloc(c_b_element);
-    rb_iv_set(node, "@c_ptr",
-              rb_funcall(c_ffi_pointer, id_ptr_new, 1,
-                         ULL2NUM((uint64_t)(uintptr_t)ptr)));
+    rb_iv_set(node, "@c_address",
+              ULL2NUM((uint64_t)(uintptr_t)ptr));
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);
@@ -1122,9 +1116,8 @@ static VALUE nf_create_binding_text(VALUE self, VALUE document,
     if (!ptr)
         return Qnil;
     node = rb_obj_alloc(c_b_text);
-    rb_iv_set(node, "@c_ptr",
-              rb_funcall(c_ffi_pointer, id_ptr_new, 1,
-                         ULL2NUM((uint64_t)(uintptr_t)ptr)));
+    rb_iv_set(node, "@c_address",
+              ULL2NUM((uint64_t)(uintptr_t)ptr));
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);

data/lib/leptris/version.rb

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

data/lib/leptris/xml/cdata.rb

@@ -6,7 +6,7 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr)
+    result = Leptris::XML::FFI.leptris_cdata_node_get_content(c_ptr)
     if @document
       @content = result
       @content_version = @document.version
@@ -17,7 +17,7 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   def content=(new_content)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_cdata_node_set_content(@c_ptr, new_content.to_s))
+      Leptris::XML::FFI.leptris_cdata_node_set_content(c_ptr, new_content.to_s))
     new_content
   end
 end

data/lib/leptris/xml/comment.rb

@@ -6,7 +6,7 @@ class Leptris::XML::Comment < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr)
+    result = Leptris::XML::FFI.leptris_comment_node_get_content(c_ptr)
     if @document
       @content = result
       @content_version = @document.version
@@ -17,7 +17,7 @@ class Leptris::XML::Comment < Leptris::XML::Node
   def content=(new_content)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_comment_node_set_content(@c_ptr, new_content.to_s))
+      Leptris::XML::FFI.leptris_comment_node_set_content(c_ptr, new_content.to_s))
     new_content
   end
 end

data/lib/leptris/xml/doc_type.rb

@@ -9,24 +9,24 @@ class Leptris::XML::DocType
   end
 
   def name
-    Leptris::XML::FFI.leptris_doctype_get_name(@c_ptr)
+    Leptris::XML::FFI.leptris_doctype_get_name(c_ptr)
   end
   alias_method :node_name, :name
 
   def root_name
-    Leptris::XML::FFI.leptris_doctype_get_root_name(@c_ptr)
+    Leptris::XML::FFI.leptris_doctype_get_root_name(c_ptr)
   end
 
   def public_id
-    Leptris::XML::FFI.leptris_doctype_get_public_id(@c_ptr)
+    Leptris::XML::FFI.leptris_doctype_get_public_id(c_ptr)
   end
 
   def system_id
-    Leptris::XML::FFI.leptris_doctype_get_system_id(@c_ptr)
+    Leptris::XML::FFI.leptris_doctype_get_system_id(c_ptr)
   end
 
   def internal_subset
-    Leptris::XML::FFI.leptris_doctype_get_internal_subset(@c_ptr)
+    Leptris::XML::FFI.leptris_doctype_get_internal_subset(c_ptr)
   end
 
   def external_id

data/lib/leptris/xml/document.rb

@@ -32,9 +32,9 @@ class Leptris::XML::Document
 
   def initialize(c_ptr = nil, freed = Freed.new(:alive))
     @c_ptr = c_ptr
-    # Plain-Integer address twin of @c_ptr: the native layer reads
+    # Plain-Integer address twin of c_ptr: the native layer reads
     # this ivar directly (no method dispatch), nil'ed exactly when
-    # @c_ptr is.
+    # c_ptr is.
     @c_address = c_ptr&.address
     @freed = freed
     @readonly = false
@@ -209,13 +209,13 @@ class Leptris::XML::Document
 
   def root
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
-    return nil if @c_ptr.nil?
+    return nil if c_ptr.nil?
     # Version-stamped memo (TODO.perf/13): root changes only
     # through mutations that advance @version (root=, unlink) or
-    # #free (which nils @c_ptr above) — the entry point of every
+    # #free (which nils c_ptr above) — the entry point of every
     # pipeline stops paying FFI + wrap per call.
     return @root if @root_version == @version
-    ptr = Leptris::XML::FFI.leptris_document_root(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_document_root(c_ptr)
     result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, self)
     @root = result
     @root_version = @version
@@ -231,7 +231,7 @@ class Leptris::XML::Document
   def node
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     @node ||= Leptris::XML::Node.wrap(
-      Leptris::XML::FFI.leptris_document_node(@c_ptr), self)
+      Leptris::XML::FFI.leptris_document_node(c_ptr), self)
   end
 
   # The document's children, via the document node: prolog
@@ -250,7 +250,7 @@ class Leptris::XML::Document
     doc_node = node
     return Leptris::XML::NodeSet.new(self, []) if doc_node.nil?
     kids = doc_node.children.to_a
-    root_ptr = Leptris::XML::FFI.leptris_document_root(@c_ptr)
+    root_ptr = Leptris::XML::FFI.leptris_document_root(c_ptr)
     return kids if root_ptr.null?
     return kids if kids.any? { |child| child.c_ptr == root_ptr }
     root = Leptris::XML::Node.wrap(root_ptr, self)
@@ -289,7 +289,7 @@ class Leptris::XML::Document
       Leptris::XML::Element.lift_namespaces_for_adoption(element, {})
     end
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_document_set_root(@c_ptr, element.c_ptr))
+      Leptris::XML::FFI.leptris_document_set_root(c_ptr, element.c_ptr))
     @version += 1
     # Seed the root memo through wrap: a cross-document element
     # must enter THIS document's identity cache with @document
@@ -308,7 +308,7 @@ class Leptris::XML::Document
       raise Leptris::XML::Error, "leptris_element_create failed" if node.nil?
       return node
     end
-    ptr = Leptris::XML::FFI.leptris_element_create(@c_ptr, name)
+    ptr = Leptris::XML::FFI.leptris_element_create(c_ptr, name)
     raise Leptris::XML::Error, "leptris_element_create failed" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_ELEMENT)
   end
@@ -319,25 +319,25 @@ class Leptris::XML::Document
       raise Leptris::XML::Error, "leptris_text_node_create failed" if node.nil?
       return node
     end
-    ptr = Leptris::XML::FFI.leptris_text_node_create(@c_ptr, content.to_s)
+    ptr = Leptris::XML::FFI.leptris_text_node_create(c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_text_node_create failed" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_TEXT)
   end
 
   def create_comment(content)
-    ptr = Leptris::XML::FFI.leptris_comment_node_create(@c_ptr, content.to_s)
+    ptr = Leptris::XML::FFI.leptris_comment_node_create(c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_comment_node_create failed" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_COMMENT)
   end
 
   def create_cdata(content)
-    ptr = Leptris::XML::FFI.leptris_cdata_node_create(@c_ptr, content.to_s)
+    ptr = Leptris::XML::FFI.leptris_cdata_node_create(c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_cdata_node_create failed" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_CDATA)
   end
 
   def create_processing_instruction(target, data = "")
-    ptr = Leptris::XML::FFI.leptris_pi_node_create(@c_ptr, target.to_s, data.to_s)
+    ptr = Leptris::XML::FFI.leptris_pi_node_create(c_ptr, target.to_s, data.to_s)
     raise Leptris::XML::Error, "leptris_pi_node_create failed" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_PI)
   end
@@ -347,14 +347,14 @@ class Leptris::XML::Document
   end
 
   def dup
-    raw = Leptris::XML::FFI.leptris_document_copy(@c_ptr)
+    raw = Leptris::XML::FFI.leptris_document_copy(c_ptr)
     raise Leptris::XML::Error, "leptris_document_copy failed" if raw.null?
     self.class.wrap(raw)
   end
   alias_method :clone, :dup
 
   def doctype
-    ptr = Leptris::XML::FFI.leptris_document_internal_subset(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_document_internal_subset(c_ptr)
     return nil if ptr.null?
     Leptris::XML::DocType.new(ptr, self)
   end
@@ -368,18 +368,18 @@ class Leptris::XML::Document
   # display-oriented and not round-trip-guaranteed).
   def to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false)
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
-    return "" if @c_ptr.nil?
+    return "" if c_ptr.nil?
     case indent_text
     when String
       return Leptris::XML::Serialization.to_xml_indent_unit(
-        @c_ptr, indent_text, indent: indent, no_decl: no_decl,
+        c_ptr, indent_text, indent: indent, no_decl: no_decl,
         encoding: encoding)
     when true
       return Leptris::XML::Serialization.to_xml_display(
-        @c_ptr, indent: indent, no_decl: no_decl, encoding: encoding)
+        c_ptr, indent: indent, no_decl: no_decl, encoding: encoding)
     end
     Leptris::XML::Serialization.to_xml(
-      Leptris::XML::Serialization::DOCUMENT_SERIALIZE_INTO, @c_ptr,
+      Leptris::XML::Serialization::DOCUMENT_SERIALIZE_INTO, c_ptr,
       indent: indent, no_decl: no_decl, encoding: encoding)
   end
   alias_method :to_s, :to_xml
@@ -391,7 +391,7 @@ class Leptris::XML::Document
       no_decl: opts.fetch(:no_decl, false),
       encoding: opts[:encoding])
     status = Leptris::XML::FFI.leptris_document_save_file(
-      @c_ptr, path, opts_struct.pointer)
+      c_ptr, path, opts_struct.pointer)
     Leptris::XML::FFI.check_status(status)
     self
   end
@@ -402,11 +402,11 @@ class Leptris::XML::Document
                    exclusive: false,
                    mode: nil)
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
-    return "" if @c_ptr.nil?
+    return "" if c_ptr.nil?
     resolved_mode = mode || (exclusive ? Leptris::XML::FFI::C14N_MODE_EXCLUSIVE
                                        : Leptris::XML::FFI::C14N_MODE_CANONICAL)
     Leptris::XML::Serialization.canonicalize(
-      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_ex), @c_ptr,
+      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_ex), c_ptr,
       version: version, mode: resolved_mode,
       inclusive_namespaces: inclusive_namespaces,
       with_comments: with_comments)
@@ -416,7 +416,7 @@ class Leptris::XML::Document
   def free
     return if @freed.state == :freed
     @freed.state = :freed
-    Leptris::XML::FFI.leptris_document_free(@c_ptr) unless @c_ptr.nil?
+    Leptris::XML::FFI.leptris_document_free(c_ptr) unless c_ptr.nil?
     @c_ptr = nil
     @c_address = nil
     @wrapper_cache&.clear
@@ -432,7 +432,7 @@ class Leptris::XML::Document
   # handlers. Returns self for chaining.
   def exslt
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_exslt_enable(@c_ptr))
+      Leptris::XML::FFI.leptris_exslt_enable(c_ptr))
     self
   end
 
@@ -440,11 +440,11 @@ class Leptris::XML::Document
   # an array of [target, data] pairs in document order.
   def processing_instructions
     return @processing_instructions if @pi_version == @version
-    count = Leptris::XML::FFI.leptris_document_pi_count(@c_ptr)
+    count = Leptris::XML::FFI.leptris_document_pi_count(c_ptr)
     result = count.times.map do |i|
-      [Leptris::XML::FFI.leptris_document_pi_target(@c_ptr, i),
+      [Leptris::XML::FFI.leptris_document_pi_target(c_ptr, i),
        Leptris::XML::FFI.read_pi_data(
-         Leptris::XML::FFI.leptris_document_pi_data(@c_ptr, i)).to_s]
+         Leptris::XML::FFI.leptris_document_pi_data(c_ptr, i)).to_s]
     end
     @processing_instructions = result
     @pi_version = @version
@@ -460,10 +460,10 @@ class Leptris::XML::Document
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     if target_or_index.is_a?(Integer)
       ptr = Leptris::XML::FFI.leptris_document_remove_pi(
-        @c_ptr, nil, target_or_index)
+        c_ptr, nil, target_or_index)
     else
       ptr = Leptris::XML::FFI.leptris_document_remove_pi(
-        @c_ptr, target_or_index.to_s, 0)
+        c_ptr, target_or_index.to_s, 0)
     end
     return nil if ptr.null?
     @version += 1
@@ -473,7 +473,7 @@ class Leptris::XML::Document
   # Append a document-level processing instruction. Returns self.
   def add_pi(target, data = "")
     witness = Leptris::XML::FFI.leptris_document_add_pi(
-      @c_ptr, target.to_s, data.to_s)
+      c_ptr, target.to_s, data.to_s)
     raise Leptris::XML::Error, "leptris_document_add_pi failed" if witness.null?
     @version += 1
     self
@@ -485,7 +485,7 @@ class Leptris::XML::Document
   # this is the writer). Returns self.
   def add_comment(content)
     witness = Leptris::XML::FFI.leptris_document_add_comment(
-      @c_ptr, content.to_s)
+      c_ptr, content.to_s)
     raise Leptris::XML::Error,
       "leptris_document_add_comment failed" if witness.null?
     @version += 1
@@ -497,7 +497,7 @@ class Leptris::XML::Document
   # (names, content, children, attributes) since they can never go
   # stale. The C document is also frozen (advisory upstream). One-way.
   def readonly!
-    Leptris::XML::FFI.leptris_document_freeze(@c_ptr)
+    Leptris::XML::FFI.leptris_document_freeze(c_ptr)
     @readonly = true
     self
   end
@@ -509,7 +509,7 @@ class Leptris::XML::Document
   # True once #free has run (or the GC finalizer fired) — borrowed
   # handles check this before dereferencing their c_ptr.
   def freed?
-    @freed.state == :freed || @c_ptr.nil?
+    @freed.state == :freed || c_ptr.nil?
   end
 
   # Document-level comments — parsed <!-- ... --> outside the
@@ -518,9 +518,9 @@ class Leptris::XML::Document
   # 1.9.3, upstream #578). Version-memoized like the PI list.
   def comments
     return @comments if @comments_version == @version
-    count = Leptris::XML::FFI.leptris_document_comment_count(@c_ptr)
+    count = Leptris::XML::FFI.leptris_document_comment_count(c_ptr)
     result = Array.new(count) do |i|
-      Leptris::XML::FFI.leptris_document_comment_content(@c_ptr, i)
+      Leptris::XML::FFI.leptris_document_comment_content(c_ptr, i)
     end
     @comments = result
     @comments_version = @version
@@ -545,15 +545,15 @@ class Leptris::XML::Document
 
   # The most recent error recorded against this document, or nil.
   def last_error
-    msg = Leptris::XML::FFI.leptris_document_last_error(@c_ptr)
+    msg = Leptris::XML::FFI.leptris_document_last_error(c_ptr)
     msg.nil? || msg.empty? ? nil : msg
   end
 
   def name; "document"; end
   def document; self; end
   def encoding
-    return nil if @c_ptr.nil?
-    Leptris::XML::FFI.leptris_document_encoding(@c_ptr)
+    return nil if c_ptr.nil?
+    Leptris::XML::FFI.leptris_document_encoding(c_ptr)
   end
 
   include Leptris::XML::Searchable

data/lib/leptris/xml/document_fragment.rb

@@ -25,7 +25,7 @@ class Leptris::XML::DocumentFragment
   end
 
   def children
-    pointers, kinds = Leptris::XML::FFI.fetch_children(@c_ptr)
+    pointers, kinds = Leptris::XML::FFI.fetch_children(c_ptr)
     nodes = Array.new(pointers.size) do |i|
       Leptris::XML::Node.wrap(pointers[i], @document, node_type: kinds[i])
     end

data/lib/leptris/xml/element.rb

@@ -16,9 +16,9 @@ class Leptris::XML::Element < Leptris::XML::Node
     return @name if @name
     ensure_alive!
     @name = if native_fast?
-              Leptris::XML::Native.fast_name(@c_ptr.address)
+              Leptris::XML::Native.fast_name(@c_address)
             else
-              Leptris::XML::FFI.leptris_element_name(@c_ptr)
+              Leptris::XML::FFI.leptris_element_name(c_ptr)
             end
   end
   alias_method :node_name, :name
@@ -26,7 +26,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def name=(new_name)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name))
+      Leptris::XML::FFI.leptris_element_set_name(c_ptr, new_name))
     @name = new_name
   end
   alias_method :node_name=, :name=
@@ -35,9 +35,9 @@ class Leptris::XML::Element < Leptris::XML::Node
     return @content if memo_hit?(@content_version)
     ensure_alive!
     result = if native_fast?
-               Leptris::XML::Native.fast_element_text(@c_ptr.address)
+               Leptris::XML::Native.fast_element_text(@c_address)
              else
-               Leptris::XML::FFI.leptris_element_text(@c_ptr)
+               Leptris::XML::FFI.leptris_element_text(c_ptr)
              end
     if @document
       @content = result
@@ -49,7 +49,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def content=(new_content)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s))
+      Leptris::XML::FFI.leptris_element_set_text(c_ptr, new_content.to_s))
     new_content
   end
 
@@ -80,9 +80,9 @@ class Leptris::XML::Element < Leptris::XML::Node
         return v if !v.nil? || @attributes
         ensure_alive!
         v = if native_fast?
-                 Leptris::XML::Native.fast_attribute(@c_ptr.address, name)
+                 Leptris::XML::Native.fast_attribute(@c_address, name)
                else
-                 Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+                 Leptris::XML::FFI.leptris_element_attribute(c_ptr, name)
                end
         values[name] = v
         return v
@@ -93,9 +93,9 @@ class Leptris::XML::Element < Leptris::XML::Node
       # stale @attributes hash and attributes would serve it.
       ensure_alive!
       v = if native_fast?
-            Leptris::XML::Native.fast_attribute(@c_ptr.address, name)
+            Leptris::XML::Native.fast_attribute(@c_address, name)
           else
-            Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+            Leptris::XML::FFI.leptris_element_attribute(c_ptr, name)
           end
       @attr_values = { name => v }
       @attributes = nil
@@ -106,7 +106,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       return v
     end
     ensure_alive!
-    v = Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+    v = Leptris::XML::FFI.leptris_element_attribute(c_ptr, name)
     # Namespace-aware misses (an undeclared prefix never resolves
     # through in-scope declarations) fall back to the WRITTEN name
     # — the same flat face #attributes exposes, so a value written
@@ -124,23 +124,32 @@ class Leptris::XML::Element < Leptris::XML::Node
     if native_fast_children?
       Leptris::XML::FFI.check_status(
         Leptris::XML::Native.set_binding_attribute(
-          @document, @c_ptr.address, key.to_s, value.to_s))
+          @document, @c_address, key.to_s, value.to_s))
       return value
     end
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s))
+      Leptris::XML::FFI.leptris_element_set_attribute(c_ptr, key.to_s, value.to_s))
     value
   end
   alias_method :set_attribute, :[]=
 
   def key?(name)
     ensure_alive!
+    # Versioned attribute memo first (TODO.perf/21): a hit proves
+    # presence without the engine round-trip; the memo cannot
+    # prove absence for a partial fill, so misses fall through.
+    n = name.to_s
+    values = @attr_values
+    if @document && values && @attributes_version == @document.version &&
+       values.key?(n)
+      return true
+    end
     return true if Leptris::XML::FFI.leptris_element_has_attribute(
-      @c_ptr, name.to_s) != 0
+      c_ptr, n) != 0
     # Same written-name fallback as #[] — the engine lookup is
     # namespace-aware and misses undeclared prefixes (#161).
-    attributes.key?(name.to_s)
+    attributes.key?(n)
   end
   alias_method :has_attribute?, :key?
 
@@ -152,19 +161,19 @@ class Leptris::XML::Element < Leptris::XML::Node
   def attribute_ns(uri, local)
     ensure_alive!
     Leptris::XML::FFI.leptris_element_attribute_ns(
-      @c_ptr, uri&.to_s, local.to_s)
+      c_ptr, uri&.to_s, local.to_s)
   end
 
   def has_attribute_ns?(uri, local)
     ensure_alive!
     Leptris::XML::FFI.leptris_element_has_attribute_ns(
-      @c_ptr, uri&.to_s, local.to_s) != 0
+      c_ptr, uri&.to_s, local.to_s) != 0
   end
 
   def remove_attribute(name)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s))
+      Leptris::XML::FFI.leptris_element_remove_attribute(c_ptr, name.to_s))
     self
   end
   alias_method :delete, :remove_attribute
@@ -177,10 +186,10 @@ class Leptris::XML::Element < Leptris::XML::Node
   def each_attribute
     return enum_for(:each_attribute) unless block_given?
     ensure_alive!
-    attr = Leptris::XML::FFI.leptris_element_first_attribute(@c_ptr)
+    attr = Leptris::XML::FFI.leptris_element_first_attribute(c_ptr)
     until attr.nil? || attr.null?
       name = Leptris::XML::FFI.leptris_attribute_get_name(attr)
-      value = Leptris::XML::FFI.leptris_attribute_get_value(@c_ptr, attr)
+      value = Leptris::XML::FFI.leptris_attribute_get_value(c_ptr, attr)
       yield Leptris::XML::Attr.new(name, value, self, c_handle: attr)
       attr = Leptris::XML::FFI.leptris_attribute_next(attr)
     end
@@ -214,7 +223,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     if native_fast?
       # TODO.perf/10: both memo faces in one C walk.
       result, values = Leptris::XML::Native.bulk_attr_faces(
-        @c_ptr.address, self)
+        @c_address, self)
       if @document
         @attributes = result
         @attr_values = values
@@ -251,9 +260,9 @@ class Leptris::XML::Element < Leptris::XML::Node
   def prefix
     ensure_alive!
     if native_fast?
-      Leptris::XML::Native.fast_prefix(@c_ptr.address)
+      Leptris::XML::Native.fast_prefix(@c_address)
     else
-      result = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+      result = Leptris::XML::FFI.leptris_element_prefix(c_ptr)
       result if result && !result.empty?
     end
   end
@@ -324,7 +333,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     # the namespace lift — the full path below handles it.
     if native_fast_children?
       st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_ptr.address, node.c_ptr.address, 1)
+        @document, @c_address, node.c_ptr.address, 1)
       unless st.nil?
         Leptris::XML::FFI.check_status(st)
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
@@ -336,7 +345,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
+      Leptris::XML::FFI.leptris_element_prepend_child(c_ptr, node.c_ptr))
     Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
@@ -347,7 +356,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     # the namespace lift — the full path below handles it.
     if native_fast_children?
       st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_ptr.address, node.c_ptr.address, 2)
+        @document, @c_address, node.c_ptr.address, 2)
       unless st.nil?
         Leptris::XML::FFI.check_status(st)
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
@@ -359,7 +368,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
+      Leptris::XML::FFI.leptris_element_insert_after(c_ptr, node.c_ptr))
     Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
@@ -370,7 +379,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     # the namespace lift — the full path below handles it.
     if native_fast_children?
       st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_ptr.address, node.c_ptr.address, 3)
+        @document, @c_address, node.c_ptr.address, 3)
       unless st.nil?
         Leptris::XML::FFI.check_status(st)
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
@@ -382,7 +391,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
+      Leptris::XML::FFI.leptris_element_insert_before(c_ptr, node.c_ptr))
     Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
@@ -390,7 +399,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def remove_child(node)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr))
+      Leptris::XML::FFI.leptris_element_remove_child(c_ptr, node.c_ptr))
     node
   end
 
@@ -398,7 +407,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     ensure_writable!
     # Remove existing children, then attach the new ones in source order.
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_remove_children(@c_ptr))
+      Leptris::XML::FFI.leptris_element_remove_children(c_ptr))
     Array(node_or_nodes).each { |n| add_child(n) }
   end
 
@@ -460,7 +469,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # document.create_element(name) + add_child.
   def create_child(name)
     ensure_writable!
-    ptr = Leptris::XML::FFI.leptris_element_create_child(@c_ptr, name.to_s)
+    ptr = Leptris::XML::FFI.leptris_element_create_child(c_ptr, name.to_s)
     raise Leptris::XML::Error,
       "leptris_element_create_child failed for #{name.inspect}" if ptr.null?
     Leptris::XML::Node.wrap_fresh(ptr, @document, Leptris::XML::FFI::NODE_ELEMENT)
@@ -477,7 +486,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       # to the full path.
       if native_fast_children?
         st = Leptris::XML::Native.append_binding_child(
-          @document, @c_ptr.address, node_or_markup.c_ptr.address)
+          @document, @c_address, node_or_markup.c_ptr.address)
         unless st.nil?
           Leptris::XML::FFI.check_status(st)
           Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
@@ -488,7 +497,7 @@ class Leptris::XML::Element < Leptris::XML::Node
         Leptris::XML::Element.lift_namespaces_for_adoption(node_or_markup, namespaces)
       end
       Leptris::XML::FFI.check_status(
-        Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node_or_markup.c_ptr))
+        Leptris::XML::FFI.leptris_element_append_child(c_ptr, node_or_markup.c_ptr))
       Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
       node_or_markup
     when String
@@ -496,7 +505,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       added = []
       frag.children.each do |n|
         Leptris::XML::FFI.check_status(
-          Leptris::XML::FFI.leptris_element_append_child(@c_ptr, n.c_ptr))
+          Leptris::XML::FFI.leptris_element_append_child(c_ptr, n.c_ptr))
         added << n
       end
       Leptris::XML::NodeSet.new(@document, added)
@@ -509,7 +518,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def namespace
     return @namespace if memo_hit?(@namespace_version)
     ensure_alive!
-    uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
+    uri = Leptris::XML::FFI.leptris_element_namespace(c_ptr)
     result =
       if uri.nil? || uri.empty?
         nil
@@ -517,7 +526,7 @@ class Leptris::XML::Element < Leptris::XML::Node
         # The resolved namespace is reached via this element's own
         # prefix, so carry it through: consumers that distinguish
         # {"p" => "urn:p"} from the default {"nil => "urn:p"} need it.
-        prefix = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+        prefix = Leptris::XML::FFI.leptris_element_prefix(c_ptr)
         prefix = nil if prefix.nil? || prefix.empty?
         Leptris::XML::Namespace.new(self, uri, prefix: prefix)
       end
@@ -538,7 +547,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def namespace=(uri)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_set_namespace(@c_ptr, uri&.to_s))
+      Leptris::XML::FFI.leptris_element_set_namespace(c_ptr, uri&.to_s))
     uri
   end
 
@@ -551,7 +560,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     prefix = ::FFI::MemoryPointer.new(:pointer)
     uri = ::FFI::MemoryPointer.new(:pointer)
     Leptris::XML::FFI.leptris_element_expanded_name(
-      @c_ptr, local, prefix, uri)
+      c_ptr, local, prefix, uri)
     local_ptr = local.read_pointer
     prefix_ptr = prefix.read_pointer
     uri_ptr = uri.read_pointer
@@ -569,10 +578,10 @@ class Leptris::XML::Element < Leptris::XML::Node
   def namespace_definitions
     return @namespace_definitions if memo_hit?(@namespace_definitions_version)
     ensure_alive!
-    count = Leptris::XML::FFI.leptris_element_namespace_count(@c_ptr)
+    count = Leptris::XML::FFI.leptris_element_namespace_count(c_ptr)
     result = count.times.map do |i|
-      prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@c_ptr, i)
-      uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@c_ptr, i)
+      prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(c_ptr, i)
+      uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(c_ptr, i)
       Leptris::XML::Namespace.new(self, uri, prefix: prefix)
     end
     if @document
@@ -612,7 +621,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     # One C pass (TODO.perf/18): the child chain, per-kind
     # serialization, and the escape set all in one dispatch —
     # byte-identical to the Ruby loop below.
-    return Leptris::XML::Native.fast_inner_xml(@c_ptr.address) if
+    return Leptris::XML::Native.fast_inner_xml(@c_address) if
       @native_fast
     children.map do |child|
       case child
@@ -646,9 +655,9 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     return Leptris::XML::Serialization.to_xml_element_unit(
       self, indent_text, indent: indent) if indent_text.is_a?(String)
-    return Leptris::XML::Serialization.element_xml_expand_empty(@c_ptr) if expand_empty
+    return Leptris::XML::Serialization.element_xml_expand_empty(c_ptr) if expand_empty
     Leptris::XML::Serialization.to_xml(
-      Leptris::XML::Serialization::ELEMENT_SERIALIZE_INTO, @c_ptr,
+      Leptris::XML::Serialization::ELEMENT_SERIALIZE_INTO, c_ptr,
       indent: indent, no_decl: no_decl, encoding: encoding)
   end
 
@@ -660,7 +669,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     resolved_mode = mode || (exclusive ? Leptris::XML::FFI::C14N_MODE_EXCLUSIVE
                                        : Leptris::XML::FFI::C14N_MODE_CANONICAL)
     Leptris::XML::Serialization.canonicalize(
-      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_subtree_ex), @c_ptr,
+      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_subtree_ex), c_ptr,
       version: version, mode: resolved_mode,
       inclusive_namespaces: inclusive_namespaces,
       with_comments: with_comments)
@@ -671,7 +680,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_add_namespace_definition(
-        @c_ptr, prefix.to_s, href.to_s))
+        c_ptr, prefix.to_s, href.to_s))
     Leptris::XML::Namespace.new(self, href.to_s, prefix: prefix.nil? ? nil : prefix.to_s)
   end
   alias_method :add_namespace, :add_namespace_definition
@@ -679,14 +688,14 @@ class Leptris::XML::Element < Leptris::XML::Node
   def default_namespace=(href)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_set_default_namespace(@c_ptr, href.to_s))
+      Leptris::XML::FFI.leptris_element_set_default_namespace(c_ptr, href.to_s))
     href
   end
 
   def remove_namespace_definition(prefix)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s))
+      Leptris::XML::FFI.leptris_element_remove_namespace_definition(c_ptr, prefix.to_s))
     self
   end
 end

data/lib/leptris/xml/node.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 class Leptris::XML::Node
-  attr_reader :c_ptr
+  # TODO.perf/19: @c_address is the canonical truth; the Pointer
+  # materializes only when actually read (most wrappers' Pointers
+  # never are — hot reads are memoized or address-based).
+  def c_ptr
+    @c_ptr ||= ::FFI::Pointer.new(@c_address)
+  end
 
   # Iterparse-yielded elements are owned by an IterationScope (the
   # internal lifetime/memoization authority) — the public #document
@@ -12,6 +17,7 @@ class Leptris::XML::Node
 
   def initialize(c_ptr, document, parent: nil, node_type: nil)
     @c_ptr = c_ptr
+    @c_address = c_ptr&.address
     @document = document
     @parent = parent
     # Structural-memo stamp (TODO.perf/13): a constructor-seeded
@@ -142,7 +148,7 @@ class Leptris::XML::Node
   def type
     return @node_type if @node_type
     ensure_alive!
-    @node_type = Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+    @node_type = Leptris::XML::FFI.leptris_node_get_type(c_ptr)
   end
   alias_method :node_type, :type
 
@@ -165,7 +171,7 @@ class Leptris::XML::Node
   def digest(drop_ws: false)
     ensure_alive!
     Leptris::XML::FFI.leptris_node_digest(
-      @c_ptr, drop_ws ? 1 : 0)
+      c_ptr, drop_ws ? 1 : 0)
   end
   def text?;     type == Leptris::XML::FFI::NODE_TEXT;     end
   def comment?;  type == Leptris::XML::FFI::NODE_COMMENT;  end
@@ -187,7 +193,7 @@ class Leptris::XML::Node
       return @parent
     end
     ensure_alive!
-    ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_parent(c_ptr)
     result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document)
     if @document
       @parent = result
@@ -205,7 +211,7 @@ class Leptris::XML::Node
   # unstamped derivation at most once per version.
   def unstamped_parent
     ensure_alive!
-    ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_parent(c_ptr)
     ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document)
   end
 
@@ -274,7 +280,7 @@ class Leptris::XML::Node
 
   def line
     ensure_alive!
-    Leptris::XML::FFI.leptris_node_line(@c_ptr)
+    Leptris::XML::FFI.leptris_node_line(c_ptr)
   end
 
   # Byte offset of the node's markup in its parse source (the '<'
@@ -283,19 +289,19 @@ class Leptris::XML::Node
   # documents >= 2 GiB.
   def byte_offset
     ensure_alive!
-    Leptris::XML::FFI.leptris_node_byte_offset(@c_ptr)
+    Leptris::XML::FFI.leptris_node_byte_offset(c_ptr)
   end
 
   def <=>(other)
     return nil unless other.is_a?(Leptris::XML::Node)
     return nil unless @document == other.document
     ensure_alive!
-    Leptris::XML::FFI.leptris_node_compare(@c_ptr, other.c_ptr)
+    Leptris::XML::FFI.leptris_node_compare(c_ptr, other.c_ptr)
   end
 
   def child
     ensure_alive!
-    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_first_child(c_ptr)
     return nil if ptr.null?
     Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
   end
@@ -310,7 +316,7 @@ class Leptris::XML::Node
       # TODO.perf/01 tail: one C pass constructs every binding
       # wrapper (class dispatch + ivars + identity cache) — the
       # per-child Ruby wrap frames disappear.
-      nodes = Leptris::XML::Native.bulk_children(@document, @c_ptr.address)
+      nodes = Leptris::XML::Native.bulk_children(@document, @c_address)
       result = Leptris::XML::NodeSet.new(@document, nodes)
       if @document
         @children = result
@@ -319,7 +325,7 @@ class Leptris::XML::Node
       return result
     end
     parent = as_element_or_self
-    pointers, kinds = Leptris::XML::FFI.fetch_children(@c_ptr)
+    pointers, kinds = Leptris::XML::FFI.fetch_children(c_ptr)
     nodes = Array.new(pointers.size) do |i|
       Leptris::XML::Node.wrap(pointers[i], @document,
                               parent: parent, node_type: kinds[i])
@@ -337,7 +343,7 @@ class Leptris::XML::Node
       return @next_sibling
     end
     ensure_alive!
-    ptr = Leptris::XML::FFI.leptris_node_next_sibling(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_next_sibling(c_ptr)
     result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
     if @document
       @next_sibling = result
@@ -352,7 +358,7 @@ class Leptris::XML::Node
       return @previous_sibling
     end
     ensure_alive!
-    ptr = Leptris::XML::FFI.leptris_node_previous_sibling(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_previous_sibling(c_ptr)
     result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
     if @document
       @previous_sibling = result
@@ -368,7 +374,7 @@ class Leptris::XML::Node
     # Raw pointer scan: non-element siblings are typed with one C
     # call each — never wrapped, never cached — and the found
     # element carries the ELEMENT hint into the wrap.
-    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    ptr = Leptris::XML::FFI.leptris_node_first_child(c_ptr)
     result = nil
     until ptr.nil? || ptr.null?
       if Leptris::XML::FFI.leptris_node_get_type(ptr) ==
@@ -391,7 +397,7 @@ class Leptris::XML::Node
     # Element receivers: the element-only batch fetches pointers
     # without wrapping any text child; only the last is wrapped.
     if is_a?(Leptris::XML::Element)
-      kids = Leptris::XML::FFI.fetch_element_children(@c_ptr)
+      kids = Leptris::XML::FFI.fetch_element_children(c_ptr)
       return nil if kids.empty?
       return Leptris::XML::Node.wrap(
         kids.last, @document, parent: self,
@@ -408,10 +414,10 @@ class Leptris::XML::Node
     # ELEMENT hint rides along). Other nodes keep the filter.
     result =
       if native_fast_children?
-        Leptris::XML::Native.bulk_element_children(@document, @c_ptr.address)
+        Leptris::XML::Native.bulk_element_children(@document, @c_address)
       elsif is_a?(Leptris::XML::Element)
         parent = as_element_or_self
-        Leptris::XML::FFI.fetch_element_children(@c_ptr).map do |ptr|
+        Leptris::XML::FFI.fetch_element_children(c_ptr).map do |ptr|
           Leptris::XML::Node.wrap(ptr, @document, parent: parent,
                                   node_type: Leptris::XML::FFI::NODE_ELEMENT)
         end
@@ -441,7 +447,7 @@ class Leptris::XML::Node
   def unlink
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_node_unlink(@c_ptr))
+      Leptris::XML::FFI.leptris_node_unlink(c_ptr))
     @parent = nil
     self
   end
@@ -468,7 +474,7 @@ class Leptris::XML::Node
         Leptris::XML::Node.wrap(node_ptr, document),
         entering == 1, depth)
     end
-    Leptris::XML::FFI.leptris_node_visit(@c_ptr, visitor, nil)
+    Leptris::XML::FFI.leptris_node_visit(c_ptr, visitor, nil)
     self
   end
 
@@ -497,7 +503,7 @@ class Leptris::XML::Node
     return enum_for(:traverse) unless block_given?
     ensure_alive!
     error = nil
-    self_address = @c_ptr.address
+    self_address = @c_address
     callback = ::FFI::Function.new(:int, [:pointer, :pointer], blocking: true) do |node_ptr, _|
       begin
         yield Leptris::XML::Node.wrap(node_ptr, @document)
@@ -508,7 +514,7 @@ class Leptris::XML::Node
       end
     end
     Leptris::XML::FFI.leptris_node_traverse(
-      @c_ptr, Leptris::XML::FFI::TRAVERSE_POST_ORDER, callback, nil)
+      c_ptr, Leptris::XML::FFI::TRAVERSE_POST_ORDER, callback, nil)
     raise error if error
     self
   end
@@ -516,7 +522,7 @@ class Leptris::XML::Node
   def path
     return @path if memo_hit?(@path_version)
     ensure_alive!
-    str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(@c_ptr)
+    str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(c_ptr)
     result = str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
     if @document
       @path = result
@@ -555,7 +561,7 @@ class Leptris::XML::Node
 
   def ==(other)
     return false unless other.is_a?(Leptris::XML::Node)
-    @c_ptr == other.c_ptr
+    c_ptr == other.c_ptr
   end
 
   def inspect

data/lib/leptris/xml/processing_instruction.rb

@@ -4,7 +4,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def name
     return @name if memo_hit?(@name_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr)
+    result = Leptris::XML::FFI.leptris_pi_node_get_target(c_ptr)
     if @document
       @name = result
       @name_version = @document.version
@@ -17,7 +17,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
     return @content if memo_hit?(@content_version)
     ensure_alive!
     result = Leptris::XML::FFI.read_pi_data(
-      Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr)).to_s
+      Leptris::XML::FFI.leptris_pi_node_get_data(c_ptr)).to_s
     if @document
       @content = result
       @content_version = @document.version
@@ -31,14 +31,14 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def target=(new_target)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_pi_node_set_target(@c_ptr, new_target.to_s))
+      Leptris::XML::FFI.leptris_pi_node_set_target(c_ptr, new_target.to_s))
     new_target
   end
 
   def data=(new_data)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s))
+      Leptris::XML::FFI.leptris_pi_node_set_data(c_ptr, new_data.to_s))
     new_data
   end
 
@@ -48,7 +48,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   # comes out.
   def unlink
     ensure_writable!
-    rc = Leptris::XML::FFI.leptris_node_unlink(@c_ptr)
+    rc = Leptris::XML::FFI.leptris_node_unlink(c_ptr)
     if rc == Leptris::XML::FFI::LEPTRIS_ERROR_NOT_FOUND
       index = document_pi_index
       if index.negative?
@@ -56,7 +56,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
           "PI not found in its document — already removed?"
       end
       removed = @document.remove_pi(index)
-      unless removed && removed.c_ptr == @c_ptr
+      unless removed && removed.c_ptr == c_ptr
         raise Leptris::XML::Error, "document-level PI removal missed"
       end
       @parent = nil
@@ -75,7 +75,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
     pi_index = -1
     @document.children.each do |child|
       pi_index += 1 if child.pi?
-      return pi_index if child.c_ptr == @c_ptr
+      return pi_index if child.c_ptr == c_ptr
     end
     -1
   end

data/lib/leptris/xml/searchable.rb

@@ -29,10 +29,31 @@ module Leptris::XML::Searchable
     nil # fall back to the string path — its error surface is the contract
   end
 
+  # CSS translation cache (TODO.perf/20): the selector -> XPath
+  # translation is a pure function of (selector, prefix); without
+  # it every css call re-ran the regex machinery before the
+  # compiled-expression cache could hit. Same bounded-LRU shape.
+  def self.css_expression(selector, prefix)
+    cache = (@css_expressions ||= {})
+    key = "#{prefix}#{selector}"
+    if (hit = cache[key])
+      cache.delete(key)
+      cache[key] = hit # LRU refresh
+      return hit
+    end
+    expr = Leptris::XML::CssToXPath.convert(selector, prefix: prefix)
+    cache.shift while cache.size >= COMPILED_CACHE_LIMIT
+    cache[key] = expr
+    expr
+  end
+
   def xpath(*paths)
     handler, ns, version = parse_search_args(paths)
     raise ArgumentError, "custom XPath handlers not supported" if handler
-    expr = paths.join(" | ")
+    # Single-String shape (the common call): join would mint a
+    # fresh String per call even for one path.
+    expr = paths.one? && paths.first.is_a?(String) ? paths.first
+                                                    : paths.join(" | ")
 
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
@@ -65,7 +86,10 @@ module Leptris::XML::Searchable
   def at_xpath(*paths)
     handler, ns, version = parse_search_args(paths)
     raise ArgumentError, "custom XPath handlers not supported" if handler
-    expr = paths.join(" | ")
+    # Single-String shape (the common call): join would mint a
+    # fresh String per call even for one path.
+    expr = paths.one? && paths.first.is_a?(String) ? paths.first
+                                                    : paths.join(" | ")
 
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
@@ -121,7 +145,7 @@ module Leptris::XML::Searchable
     # Nokogiri semantics: css is receiver-relative — absolute "//"
     # from a Document, descendant ".//" from elements and fragments.
     prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
-    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r, prefix: prefix) }
+    expr = args.map { |r| Leptris::XML::Searchable.css_expression(r, prefix) }
       .join(" | ")
     xpath(expr)
   end
@@ -132,7 +156,7 @@ module Leptris::XML::Searchable
     raise ArgumentError, "version: is XPath-only" if version
     raise ArgumentError, "custom CSS handlers not supported" if handler
     prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
-    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r, prefix: prefix) }
+    expr = args.map { |r| Leptris::XML::Searchable.css_expression(r, prefix) }
       .join(" | ")
     at_xpath(expr)
   end

data/lib/leptris/xml/text.rb

@@ -6,7 +6,7 @@ class Leptris::XML::Text < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr)
+    result = Leptris::XML::FFI.leptris_text_node_get_content(c_ptr)
     if @document
       @content = result
       @content_version = @document.version
@@ -17,7 +17,7 @@ class Leptris::XML::Text < Leptris::XML::Node
   def content=(new_content)
     ensure_writable!
     Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_text_node_set_content(@c_ptr, new_content.to_s))
+      Leptris::XML::FFI.leptris_text_node_set_content(c_ptr, new_content.to_s))
     new_content
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.2
+  version: 1.9.174.3
 platform: ruby
 authors:
 - Ribose Inc.
@@ -87,6 +87,9 @@ files:
 - TODO.perf/16-at-xpath-single-result-seam.md
 - TODO.perf/17-precomputed-fast-path-flags.md
 - TODO.perf/18-inner-html-one-c-pass.md
+- TODO.perf/19-lazy-node-pointer.md
+- TODO.perf/20-css-translation-cache.md
+- TODO.perf/21-key-memo-consult.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md