leptris 1.9.174.3 → 1.9.174.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 741e98553c4d88169d4c2f8ec0fb793eeebd80ffd8b00771fcfb0be218721f64
-  data.tar.gz: 5e02a23549a4e1c708dc40710b499e64fcd83150772dd08c8bbeac7fc77f0718
+  metadata.gz: 3052fa875df89194fa904610e20786deaf2076de881242382afe9bbc9fd7fa0d
+  data.tar.gz: 86806a382948d948d2ec5c2550302a8ae52b976edd224aaff4c130f3a4606f3e
 SHA512:
-  metadata.gz: b1a3b25cd5b770b6edfb06bc2d448dacd691dc7e5af3fb301454fb1057e419c5fc779e4c9556a3f3b4be654ea5ec36be8f8e5c4e0f7ab16af380b6986da3bcb5
-  data.tar.gz: 85e81207c2abaca9a80af5dcfb33ae4e4f83c2ec24950b16d38fcb239bf7fa4d01b40d4d88b7fa19e019ba35a9ce58984c823e3f049fc47492459ebde53aa47b
+  metadata.gz: 81e9fe81a94ddd6d82ef044569b8d43ff5c663ca41cf2a59798660638e4f73cfc23f7aabf4eb3123757e3590d0d7524438f378c6b1bd447a2b39af95bb0089d5
+  data.tar.gz: e161ced4c4ab3634ae6a4fa6ebb0e95e970e1634b72a9d1b4ef5e1ad3800461170a2893bb89477c404f22b992813b7abf66abc083272e851c341affc699488fc

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.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/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). */
@@ -876,6 +953,7 @@ static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
             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(kinds[i]));
             rb_hash_aset(cache, key, node);
         }
@@ -912,15 +990,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 +1078,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 +1118,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 +1207,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 +1233,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 +1689,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.4"
 end

data/lib/leptris/xml/element.rb

@@ -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))
@@ -47,6 +53,12 @@ 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))
+      return new_content
+    end
     ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_text(c_ptr, new_content.to_s))

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,7 @@ 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
     # 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.
@@ -278,9 +281,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 +293,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)
@@ -445,6 +451,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.4
 platform: ruby
 authors:
 - Ribose Inc.
@@ -90,6 +90,9 @@ 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.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md