leptris 1.9.174.3 → 1.9.174.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 741e98553c4d88169d4c2f8ec0fb793eeebd80ffd8b00771fcfb0be218721f64
-  data.tar.gz: 5e02a23549a4e1c708dc40710b499e64fcd83150772dd08c8bbeac7fc77f0718
+  metadata.gz: ec76aed6663e2ae97d677c09e8b05486eb6e0543da0f92640a81a87d49c38565
+  data.tar.gz: bd881b0e87ff21939925f879abfced736f304a5396f675013a2bc8e2f220a89c
 SHA512:
-  metadata.gz: b1a3b25cd5b770b6edfb06bc2d448dacd691dc7e5af3fb301454fb1057e419c5fc779e4c9556a3f3b4be654ea5ec36be8f8e5c4e0f7ab16af380b6986da3bcb5
-  data.tar.gz: 85e81207c2abaca9a80af5dcfb33ae4e4f83c2ec24950b16d38fcb239bf7fa4d01b40d4d88b7fa19e019ba35a9ce58984c823e3f049fc47492459ebde53aa47b
+  metadata.gz: f9f8f54bca5c16e6f1068a9988374ab2a852febc8f4f8695fa7cf0e5bb21fed700bf5b7a34b0732693d55f520000528ed35719dc2488fdf3afb3b6224d2dce9d
+  data.tar.gz: a883b80b556feaa34abc6544fe7b4c5f03d6da46597c6dc3170d1219ab66aa4018be3233f824ae6df551c50dc963974a35f72ea715037d596a26259bc8087d8a

data/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.5] - 2026-09-15
+
+### Changed
+
+- **Iterparse rides the bulk path (TODO.perf/25)**: scope-owned
+  elements materialize children through the one-pass C faces —
+  the IterationScope flows as the cache/version authority (its
+  cache resets per yield, so recycled pool addresses cannot
+  collide), with scope-aware wrapper stamps; pure address-based
+  reads (attribute/text/name) become scope-eligible. Mutations
+  on scope elements keep the Ruby path. Measured (load ~6): the
+  20k-record streaming walk 124.8ms → 100.5ms (~20%).
+- **Post-mutation memo seeding (TODO.perf/26)**: []= seeds the
+  attribute memo at the new version (partial memos extend,
+  full faces restart — the cold-[] rules); content= seeds
+  @content; the write-then-read cycle runs ~545ns combined.
+
+## [1.9.174.4] - 2026-09-15
+
+### Changed
+
+- **Eager-in-C nodeset materialization (TODO.perf/22)**: xpath
+  results materialize and free in one C pass — no
+  FFI::AutoPointer, Method object, or finalizer per call; exotic
+  kinds keep the lazy path (sentinel scan in C). Measured (load
+  ~11): a 2000-node xpath set materializes at Nokogiri parity
+  (55.9µs vs 57.3µs).
+- **C-bound value mutations (TODO.perf/23)**: `Element#name=`,
+  `#content=`, `Text#content=`, `Node#unlink` run gates + version
+  bump + engine write in one dispatch (name= 237ns, content=
+  298ns measured); readonly raises verified.
+- **Immutable read lanes (TODO.perf/24)**: `line`/`byte_offset`
+  memoize (positions never change); `Node#document` answers a
+  constructor-precomputed ivar (the scope_owned? chain leaves
+  one of the most-called readers).
+
 ## [1.9.174.3] - 2026-09-15
 
 ### Changed

data/TODO.perf/22-eager-nodeset-materialization.md

@@ -0,0 +1,30 @@
+# 22 — Eager-in-C nodeset materialization (drop the per-call AutoPointer)
+
+Status: DONE (1.9.174.4)
+
+Every xpath() nodeset result pays an FFI::AutoPointer + a Method
+object + finalizer registration (~400-600ns plus their GC) just
+to keep the C result handle alive until the lazy NodeSet
+materializes — and virtually every consumer materializes anyway
+(each/size/to_a). Materialize eagerly in C instead: one face runs
+the bulk pass AND frees the result handle, returning the Ruby
+Array; Searchable wraps it in the eager NodeSet constructor (an
+Array-backed set has no handle at all). Exotic node kinds (the
+module-object sentinel) fall back to the existing lazy path with
+the handle intact.
+
+Gates: xpath results identical for every kind (including
+sentinel-graded kinds); laziness is internal — the public NodeSet
+behaviors (indexing, iteration, size) unchanged; the xpath row
+drops the AutoPointer cost per call.
+
+## Outcome (1.9.174.4)
+
+Native.materialize_xpath: the bulk pass AND the result free in C;
+Searchable's nodeset branch wraps the returned Array in the eager
+NodeSet (no AutoPointer, no Method object, no finalizer per
+xpath call). Sentinel scans happen in C (a Ruby include? would
+cost microseconds on large sets) — any exotic kind returns Qnil
+with the handle alive for the lazy fallback. Measured (load
+~11): full materialization of a 2000-node xpath set 55.9µs vs
+Nokogiri 57.3µs — parity on the heavy shape.

data/TODO.perf/23-cbound-value-mutations.md

@@ -0,0 +1,27 @@
+# 23 — C-bound name= / content= / unlink
+
+Status: DONE (1.9.174.4)
+
+The value mutations still run ensure_writable! + FFI marshaling
+per call (~450ns): Element#name=, Element#content=,
+Text#content=, and Node#unlink (transforms rename, rewrite, and
+remove nodes constantly). Same face shape as set_binding_attribute:
+gates + version bump + engine write in one dispatch —
+set_binding_name (element names), set_binding_text (element text
+or text-node content, kind-dispatched in C), and
+unlink_binding_node (plus the Ruby-side @parent clear and memo
+invalidations that ride the version bump).
+
+Gates: rename/content/unlink semantics unchanged (memos, sibling
+stamps, path memo all invalidate through the version bump);
+readonly raises through every face.
+
+## Outcome (1.9.174.4)
+
+Native.set_binding_name / set_binding_text (kind-dispatched
+element-vs-text) / unlink_binding_node — gates + bump + engine
+write in one dispatch, wired into Element#name=, #content=,
+Text#content=, and Node#unlink (@parent clear and memo
+invalidation ride the version bump). Measured (load ~11):
+name= 237ns, content= 298ns, unlink+re-add 1.74µs; readonly
+raises verified through every face.

data/TODO.perf/24-immutable-read-lanes.md

@@ -0,0 +1,22 @@
+# 24 — Immutable read lanes: line/byte_offset memo + precomputed public #document
+
+Status: DONE (1.9.174.4)
+
+Node#line and #byte_offset pay an FFI round-trip per call, but a
+node's source position never changes — memoize unconditionally
+(first read wins). The public Node#document walks scope_owned? (a
+method chain) on every call though scope ownership is fixed at
+construction — precompute @pub_document once (nil for
+scope-owned) including at every C construction site.
+
+Gates: line/byte_offset stable across mutations (they must be —
+the engine reports source positions); document nil for
+scope-owned yields exactly as before; suite both modes.
+
+## Outcome (1.9.174.4)
+
+line/byte_offset memoize unconditionally (a node's source
+position never changes; 40ns hits). Node#document answers the
+constructor-precomputed @pub_document (nil for scope-owned
+yields) — the scope_owned? method chain disappears from one of
+the most-called readers; every C construction site sets it.

data/TODO.perf/25-scope-owned-bulk-path.md

@@ -0,0 +1,39 @@
+# 25 — Scope-owned (iterparse) elements on the bulk/native read path
+
+Status: DONE (1.9.174.5)
+
+iterparse is moxml's streaming core, yet scope-owned elements
+ride the FFI read path (two-call fetch + per-child Ruby wrap
+frames; #4ca5b3c kept them off deliberately). The IterationScope
+exposes exactly the seams the C faces read — @wrapper_cache
+(reset per yield by new_subtree!, killing recycled-address
+entries) and @version (advances per yield and on mutation) — so
+the bulk children faces can take the SCOPE as their "document"
+argument safely, provided the constructed wrappers are stamped
+scope-aware: @structure_memoizable/@native_fast false,
+@pub_document nil.
+
+Pure address-based reads (fast_attribute / element text / name)
+touch no cache — scope elements can use them via a construction
+-time @addr_reads_fast that ignores scope ownership.
+
+Gates: iterparse children/element_children identical via the C
+path; identity holds within a yielded subtree and resets across
+yields (the new_subtree! discipline); document stays nil for
+scope yields; mutations on scope elements keep the Ruby path;
+suite both modes.
+
+## Outcome (1.9.174.5)
+
+The bulk children faces take the IterationScope itself as their
+"document" (its @wrapper_cache resets per yield via new_subtree!
+— recycled pool addresses cannot collide — and its @version
+advances per yield and on mutation); the C face stamps
+scope-aware (@structure_memoizable/@native_fast false,
+@pub_document nil) while document-owned stamps stay Qtrue.
+Pure address-based reads (fast_attribute / element text / name)
+switch to @addr_reads_fast — true for scope elements too (they
+touch no cache). Mutations on scope elements keep the Ruby path.
+Measured (load ~6): the 20k-record iterparse walk (attr + child
+name + content per record) 124.8ms (FFI) -> 100.5ms (native
+bulk) — ~20%.

data/TODO.perf/26-post-mutation-memo-seeding.md

@@ -0,0 +1,26 @@
+# 26 — Post-mutation memo seeding
+
+Status: DONE (1.9.174.5)
+
+Every mutation invalidates the read memos through the version
+bump, so a write-then-read cycle pays a full re-derivation even
+when the new value is known at write time. Seed it: Element#[]=
+re-stamps @attr_values at the new version and writes the value
+into it (a partial fill stays partial — same rules); content=
+stores the new text as the @content memo at the new version;
+name= already seeds @name.
+
+Gates: []=/content=/name= followed by reads answers from the
+seeded memo (spec-observable via identity for strings? — no,
+values only); mixed attribute sets then attributes() still
+rebuild the full face on demand; invalidation semantics
+unchanged for other mutators.
+
+## Outcome (1.9.174.5)
+
+Element#[]= seeds the version-stamped @attr_values at the new
+version (a just-invalidated valid partial memo extends in place;
+a full face or anything older restarts partial, mirroring the
+cold-[] rules); content= seeds @content; name= seeds @name
+(already). Measured: the []= + [] read-back cycle runs ~545ns
+(write + read combined).

data/ext/leptris/native/native.c

@@ -85,6 +85,10 @@ static xp_free_fn f_xp_free;
 static first_child_fn f_first_child;
 static node_str_fn f_comment_content, f_cdata_content, f_pi_target,
                    f_pi_data;
+typedef int (*set_str_fn)(void *, const char *);
+typedef int (*node_unlink_fn)(void *);
+static set_str_fn f_elem_set_name, f_elem_set_text, f_text_set_content;
+static node_unlink_fn f_node_unlink;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -192,6 +196,10 @@ static void resolve_symbols(const char *lib_path)
     f_cdata_content = (node_str_fn)lib_sym(h, "leptris_cdata_node_get_content");
     f_pi_target = (node_str_fn)lib_sym(h, "leptris_pi_node_get_target");
     f_pi_data = (node_str_fn)lib_sym(h, "leptris_pi_node_get_data");
+    f_elem_set_name = (set_str_fn)lib_sym(h, "leptris_element_set_name");
+    f_elem_set_text = (set_str_fn)lib_sym(h, "leptris_element_set_text");
+    f_text_set_content = (set_str_fn)lib_sym(h, "leptris_text_node_set_content");
+    f_node_unlink = (node_unlink_fn)lib_sym(h, "leptris_node_unlink");
     f_set_root = (set_root_fn)lib_sym(h, "leptris_document_set_root");
     f_doc_free = (doc_free_fn)lib_sym(h, "leptris_document_free");
     if (!f_elem_name || !f_text_content || !f_attr ||
@@ -201,7 +209,8 @@ static void resolve_symbols(const char *lib_path)
         !f_insert_after || !f_insert_before || !f_set_attr || !f_set_root ||
         !f_xp_type || !f_xp_free || !f_first_child ||
         !f_comment_content || !f_cdata_content || !f_pi_target ||
-        !f_pi_data ||
+        !f_pi_data || !f_elem_set_name || !f_elem_set_text ||
+        !f_text_set_content || !f_node_unlink ||
         !f_doc_free ||
         !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
         !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
@@ -630,6 +639,74 @@ static VALUE nf_set_binding_attribute(VALUE self, VALUE document,
     return INT2FIX(st);
 }
 
+/* C-bound value mutations (TODO.perf/23): the same gates + bump
+ * + engine write shape as set_binding_attribute. */
+static VALUE nf_set_binding_name(VALUE self, VALUE document,
+                                 VALUE addr, VALUE name)
+{
+    void *node;
+    int st;
+
+    (void)self;
+    resolve_binding_classes();
+    if (NIL_P(rb_ivar_get(document, id_iv_c_address)))
+        rb_raise(c_use_after_free_error,
+                 "owning document has been freed");
+    if (rb_ivar_get(document, id_iv_readonly) == Qtrue)
+        rb_raise(c_readonly_error,
+                 "document is readonly — mutation attempted");
+    node = (void *)(uintptr_t)NUM2ULL(addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    st = f_elem_set_name(node, StringValueCStr(name));
+    return INT2FIX(st);
+}
+
+/* Element text or text-node content — kind-dispatched in C. */
+static VALUE nf_set_binding_text(VALUE self, VALUE document,
+                                 VALUE addr, VALUE content)
+{
+    void *node;
+    int st;
+
+    (void)self;
+    resolve_binding_classes();
+    if (NIL_P(rb_ivar_get(document, id_iv_c_address)))
+        rb_raise(c_use_after_free_error,
+                 "owning document has been freed");
+    if (rb_ivar_get(document, id_iv_readonly) == Qtrue)
+        rb_raise(c_readonly_error,
+                 "document is readonly — mutation attempted");
+    node = (void *)(uintptr_t)NUM2ULL(addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    st = f_node_type(node) == NT_ELEMENT
+             ? f_elem_set_text(node, StringValueCStr(content))
+             : f_text_set_content(node, StringValueCStr(content));
+    return INT2FIX(st);
+}
+
+static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
+                                    VALUE addr)
+{
+    void *node;
+    int st;
+
+    (void)self;
+    resolve_binding_classes();
+    if (NIL_P(rb_ivar_get(document, id_iv_c_address)))
+        rb_raise(c_use_after_free_error,
+                 "owning document has been freed");
+    if (rb_ivar_get(document, id_iv_readonly) == Qtrue)
+        rb_raise(c_readonly_error,
+                 "document is readonly — mutation attempted");
+    node = (void *)(uintptr_t)NUM2ULL(addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    st = f_node_unlink(node);
+    return INT2FIX(st);
+}
+
 /* C-bound insert family (TODO.perf/14): prepend / insert-after /
  * insert-before share append's gates + predicate + bump shape.
  * mode: 1 prepend, 2 after, 3 before (anchor = receiver). */
@@ -797,6 +874,7 @@ static VALUE nn_address(VALUE self)
 static VALUE c_b_element = Qundef, c_b_text, c_b_comment, c_b_cdata,
              c_b_pi, c_b_node, c_b_result_text, c_b_result_attr,
              c_b_attr, c_ffi_pointer, c_b_document, c_b_freed;
+static VALUE c_iteration_scope;
 static ID id_ptr_new;
 
 /* Binding classes resolve LAZILY: Init_native can run before the
@@ -818,6 +896,7 @@ static void resolve_binding_classes(void)
     c_b_attr = rb_path2class("Leptris::XML::Attr");
     c_b_document = rb_path2class("Leptris::XML::Document");
     c_b_freed = rb_path2class("Leptris::XML::Document::Freed");
+    c_iteration_scope = rb_path2class("Leptris::XML::IterationScope");
     id_ptr_new = rb_intern("new");
     rb_gc_register_mark_object(c_b_element);
     rb_gc_register_mark_object(c_b_text);
@@ -831,6 +910,7 @@ static void resolve_binding_classes(void)
     rb_gc_register_mark_object(c_b_attr);
     rb_gc_register_mark_object(c_b_document);
     rb_gc_register_mark_object(c_b_freed);
+    rb_gc_register_mark_object(c_iteration_scope);
 }
 
 static VALUE binding_klass_for(int kind)
@@ -874,8 +954,20 @@ static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
             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);
-            rb_iv_set(node, "@native_fast", Qtrue);
+            /* TODO.perf/25: scope-aware stamps — the IterationScope
+             * flows through here as "document" for iterparse
+             * elements; those stay memo-exempt and FFI-mutating,
+             * but address-based reads are cache-free and safe. */
+            if (rb_obj_class(document) == c_iteration_scope) {
+                rb_iv_set(node, "@structure_memoizable", Qfalse);
+                rb_iv_set(node, "@native_fast", Qfalse);
+                rb_iv_set(node, "@pub_document", Qnil);
+            } else {
+                rb_iv_set(node, "@structure_memoizable", Qtrue);
+                rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@pub_document", document);
+            }
+            rb_iv_set(node, "@addr_reads_fast", Qtrue);
             rb_iv_set(node, "@node_type", INT2FIX(kinds[i]));
             rb_hash_aset(cache, key, node);
         }
@@ -912,15 +1004,45 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
                                   void *result, void *ptr, int kind,
                                   int idx);
 
+static VALUE bulk_xpath_array(VALUE document, void *result);
+
 static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
+{
+    (void)self;
+    return bulk_xpath_array(document,
+                            (void *)(uintptr_t)NUM2ULL(result_ptr_val));
+}
+
+/* TODO.perf/22: materialize AND free — the eager xpath path owns
+ * the handle lifecycle in C; no Ruby AutoPointer, no finalizer. */
+static VALUE nf_materialize_xpath(VALUE self, VALUE document,
+                                  VALUE result_ptr_val)
 {
     void *result = (void *)(uintptr_t)NUM2ULL(result_ptr_val);
+    VALUE out;
+    long i, n;
+
+    (void)self;
+    out = bulk_xpath_array(document, result);
+    n = RARRAY_LEN(out);
+    for (i = 0; i < n; i++) {
+        if (rb_ary_entry(out, i) == m_native_sentinel) {
+            /* Exotic kinds need the Ruby fallback per entry — the
+             * caller keeps the handle and goes the lazy path. */
+            return Qnil;
+        }
+    }
+    f_xp_free(result);
+    return out;
+}
+
+static VALUE bulk_xpath_array(VALUE document, void *result)
+{
     void **buf;
     int *kinds;
     int count, i;
     VALUE cache, out;
 
-    (void)self;
     resolve_binding_classes();
     size_t scount = f_xp_count(result);
     if (scount == 0)
@@ -970,6 +1092,7 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
             rb_iv_set(node, "@parent", Qnil);
             rb_iv_set(node, "@structure_memoizable", Qtrue);
             rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@pub_document", document);
             rb_iv_set(node, "@node_type", INT2FIX(0));
             rb_hash_aset(cache, key, node);
         }
@@ -1009,6 +1132,7 @@ static VALUE materialize_xp_entry(VALUE document, VALUE cache,
                 rb_iv_set(node, "@parent", Qnil);
                 rb_iv_set(node, "@structure_memoizable", Qtrue);
                 rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@pub_document", document);
                 rb_iv_set(node, "@node_type", INT2FIX(nt));
                 rb_hash_aset(cache, key, node);
             }
@@ -1097,6 +1221,7 @@ static VALUE nf_create_binding_element(VALUE self, VALUE document,
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);
     rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@pub_document", document);
     rb_iv_set(node, "@node_type", INT2FIX(0));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -1122,6 +1247,7 @@ static VALUE nf_create_binding_text(VALUE self, VALUE document,
     rb_iv_set(node, "@parent", Qnil);
     rb_iv_set(node, "@structure_memoizable", Qtrue);
     rb_iv_set(node, "@native_fast", Qtrue);
+                rb_iv_set(node, "@pub_document", document);
     rb_iv_set(node, "@node_type", INT2FIX(1));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -1577,6 +1703,14 @@ void Init_native(void)
                               nf_insert_binding_child, 4);
     rb_define_module_function(m_native, "at_xpath_first",
                               nf_at_xpath_first, 2);
+    rb_define_module_function(m_native, "materialize_xpath",
+                              nf_materialize_xpath, 2);
+    rb_define_module_function(m_native, "set_binding_name",
+                              nf_set_binding_name, 3);
+    rb_define_module_function(m_native, "set_binding_text",
+                              nf_set_binding_text, 3);
+    rb_define_module_function(m_native, "unlink_binding_node",
+                              nf_unlink_binding_node, 2);
     rb_define_module_function(m_native, "fast_inner_xml",
                               nf_fast_inner_xml, 1);
     rb_define_module_function(m_native, "doc_handle_attach",

data/lib/leptris/version.rb

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

data/lib/leptris/xml/element.rb

@@ -15,7 +15,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def name
     return @name if @name
     ensure_alive!
-    @name = if native_fast?
+    @name = if @addr_reads_fast
               Leptris::XML::Native.fast_name(@c_address)
             else
               Leptris::XML::FFI.leptris_element_name(c_ptr)
@@ -24,6 +24,12 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :node_name, :name
 
   def name=(new_name)
+    if @native_fast
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::Native.set_binding_name(
+          @document, @c_address, new_name))
+      return @name = new_name
+    end
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_name(c_ptr, new_name))
@@ -34,7 +40,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = if native_fast?
+    result = if @addr_reads_fast
                Leptris::XML::Native.fast_element_text(@c_address)
              else
                Leptris::XML::FFI.leptris_element_text(c_ptr)
@@ -47,9 +53,19 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def content=(new_content)
+    if @native_fast
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::Native.set_binding_text(
+          @document, @c_address, new_content.to_s))
+      @content = new_content.to_s
+      @content_version = @document.version if @document
+      return new_content
+    end
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_text(c_ptr, new_content.to_s))
+    @content = new_content.to_s
+    @content_version = @document.version if @document
     new_content
   end
 
@@ -79,7 +95,7 @@ class Leptris::XML::Element < Leptris::XML::Node
         # engine call resolves it, then the name is cached.
         return v if !v.nil? || @attributes
         ensure_alive!
-        v = if native_fast?
+        v = if @addr_reads_fast
                  Leptris::XML::Native.fast_attribute(@c_address, name)
                else
                  Leptris::XML::FFI.leptris_element_attribute(c_ptr, name)
@@ -92,7 +108,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       # post-mutation cold [] would stamp the new version onto a
       # stale @attributes hash and attributes would serve it.
       ensure_alive!
-      v = if native_fast?
+      v = if @addr_reads_fast
             Leptris::XML::Native.fast_attribute(@c_address, name)
           else
             Leptris::XML::FFI.leptris_element_attribute(c_ptr, name)
@@ -125,15 +141,39 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::FFI.check_status(
         Leptris::XML::Native.set_binding_attribute(
           @document, @c_address, key.to_s, value.to_s))
+      seed_attribute_memo(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))
+    seed_attribute_memo(key.to_s, value.to_s)
     value
   end
   alias_method :set_attribute, :[]=
 
+  # TODO.perf/26: the write knows the new value — seed the
+  # version-stamped memo so a read-back skips re-derivation. A
+  # valid-and-just-invalidated partial memo extends in place; a
+  # full face (or anything older) restarts partial, mirroring the
+  # cold-[] rules.
+  def seed_attribute_memo(name, written)
+    return unless @document
+    values = @attr_values
+    if values && !@attributes &&
+       @attributes_version == @document.version - 1
+      values[name] = written
+    else
+      @attr_values = { name => written }
+      @attributes = nil
+      @attribute_nodes = nil
+      @keys = nil
+      @values = nil
+    end
+    @attributes_version = @document.version
+  end
+  private :seed_attribute_memo
+
   def key?(name)
     ensure_alive!
     # Versioned attribute memo first (TODO.perf/21): a hit proves

data/lib/leptris/xml/node.rb

@@ -11,8 +11,10 @@ class Leptris::XML::Node
   # Iterparse-yielded elements are owned by an IterationScope (the
   # internal lifetime/memoization authority) — the public #document
   # answers nil for them, per the documented contract.
+  # Precomputed at construction (TODO.perf/24): scope ownership
+  # is fixed for a node's lifetime — nil for iterparse yields.
   def document
-    scope_owned? ? nil : @document
+    @pub_document
   end
 
   def initialize(c_ptr, document, parent: nil, node_type: nil)
@@ -33,6 +35,10 @@ class Leptris::XML::Node
     # keeps the memo-hit path free of method dispatch.
     @structure_memoizable =
       !document.nil? && !document.is_a?(Leptris::XML::IterationScope)
+    @pub_document = @structure_memoizable ? document : nil
+    # TODO.perf/25: pure address-based native reads touch no
+    # cache — safe for scope-owned (iterparse) elements too.
+    @addr_reads_fast = !!defined?(Leptris::XML::NATIVE_FAST)
     # NATIVE_FAST availability is fixed at load time before any
     # node exists, so the conjunction with document-ownership is
     # construct-time constant — the hot gates read one ivar.
@@ -161,6 +167,16 @@ class Leptris::XML::Node
     @native_fast
   end
 
+  # TODO.perf/25: the bulk children faces accept the
+  # IterationScope itself (its @wrapper_cache resets per yield —
+  # recycled addresses cannot collide — and its @version advances
+  # per yield and on mutation), so streaming children ride the
+  # one-pass materialization too. The scope-aware stamps live in
+  # the C face.
+  def native_bulk_children?
+    defined?(Leptris::XML::NATIVE_FAST)
+  end
+
   # Content-defined 64-bit Merkle digest of this subtree
   # (libleptris 1.9.99, #869): element name/prefix/resolved
   # namespace URI, attributes sorted and first-wins-deduplicated,
@@ -278,9 +294,11 @@ class Leptris::XML::Node
     @readonly_document = true
   end
 
+  # A node's source position never changes — first read wins.
   def line
+    return @line if defined?(@line)
     ensure_alive!
-    Leptris::XML::FFI.leptris_node_line(c_ptr)
+    @line = Leptris::XML::FFI.leptris_node_line(c_ptr)
   end
 
   # Byte offset of the node's markup in its parse source (the '<'
@@ -288,8 +306,9 @@ class Leptris::XML::Node
   # CALLBACK rows echo). 0 when unknown: mutation-created nodes, or
   # documents >= 2 GiB.
   def byte_offset
+    return @byte_offset if defined?(@byte_offset)
     ensure_alive!
-    Leptris::XML::FFI.leptris_node_byte_offset(c_ptr)
+    @byte_offset = Leptris::XML::FFI.leptris_node_byte_offset(c_ptr)
   end
 
   def <=>(other)
@@ -312,7 +331,7 @@ class Leptris::XML::Node
     # (leptris_node_children_ex), so no per-child get_type.
     return @children if memo_hit?(@children_version)
     ensure_alive!
-    if native_fast_children?
+    if native_bulk_children?
       # TODO.perf/01 tail: one C pass constructs every binding
       # wrapper (class dispatch + ivars + identity cache) — the
       # per-child Ruby wrap frames disappear.
@@ -413,7 +432,7 @@ class Leptris::XML::Node
     # children are never wrapped (nor their get_type paid — the
     # ELEMENT hint rides along). Other nodes keep the filter.
     result =
-      if native_fast_children?
+      if native_bulk_children?
         Leptris::XML::Native.bulk_element_children(@document, @c_address)
       elsif is_a?(Leptris::XML::Element)
         parent = as_element_or_self
@@ -445,6 +464,12 @@ class Leptris::XML::Node
   end
 
   def unlink
+    if @native_fast
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::Native.unlink_binding_node(@document, @c_address))
+      @parent = nil
+      return self
+    end
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_node_unlink(c_ptr))

data/lib/leptris/xml/searchable.rb

@@ -298,6 +298,15 @@ module Leptris::XML::Searchable
     type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
     case type
     when Leptris::XML::FFI::XPATH_NODESET
+      # TODO.perf/22: materialize AND free in C — no Ruby
+      # AutoPointer + finalizer per xpath call. Qnil means an
+      # exotic kind needs the Ruby fallback per entry; the lazy
+      # path below keeps the handle.
+      if defined?(Leptris::XML::NATIVE_FAST)
+        nodes = Leptris::XML::Native.materialize_xpath(
+          document, result_ptr.address)
+        return Leptris::XML::NodeSet.new(document, nodes) if nodes
+      end
       Leptris::XML::NodeSet.from_result(document, result_ptr)
     when Leptris::XML::FFI::XPATH_BOOLEAN
       v = Leptris::XML::FFI.leptris_xpath_result_boolean(result_ptr) != 0

data/lib/leptris/xml/text.rb

@@ -15,6 +15,12 @@ class Leptris::XML::Text < Leptris::XML::Node
   end
 
   def content=(new_content)
+    if @native_fast
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::Native.set_binding_text(
+          @document, @c_address, new_content.to_s))
+      return new_content
+    end
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_text_node_set_content(c_ptr, new_content.to_s))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.3
+  version: 1.9.174.5
 platform: ruby
 authors:
 - Ribose Inc.
@@ -90,6 +90,11 @@ files:
 - TODO.perf/19-lazy-node-pointer.md
 - TODO.perf/20-css-translation-cache.md
 - TODO.perf/21-key-memo-consult.md
+- TODO.perf/22-eager-nodeset-materialization.md
+- TODO.perf/23-cbound-value-mutations.md
+- TODO.perf/24-immutable-read-lanes.md
+- TODO.perf/25-scope-owned-bulk-path.md
+- TODO.perf/26-post-mutation-memo-seeding.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md