leptris 1.9.174.4 → 1.9.174.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3052fa875df89194fa904610e20786deaf2076de881242382afe9bbc9fd7fa0d
-  data.tar.gz: 86806a382948d948d2ec5c2550302a8ae52b976edd224aaff4c130f3a4606f3e
+  metadata.gz: ec76aed6663e2ae97d677c09e8b05486eb6e0543da0f92640a81a87d49c38565
+  data.tar.gz: bd881b0e87ff21939925f879abfced736f304a5396f675013a2bc8e2f220a89c
 SHA512:
-  metadata.gz: 81e9fe81a94ddd6d82ef044569b8d43ff5c663ca41cf2a59798660638e4f73cfc23f7aabf4eb3123757e3590d0d7524438f378c6b1bd447a2b39af95bb0089d5
-  data.tar.gz: e161ced4c4ab3634ae6a4fa6ebb0e95e970e1634b72a9d1b4ef5e1ad3800461170a2893bb89477c404f22b992813b7abf66abc083272e851c341affc699488fc
+  metadata.gz: f9f8f54bca5c16e6f1068a9988374ab2a852febc8f4f8695fa7cf0e5bb21fed700bf5b7a34b0732693d55f520000528ed35719dc2488fdf3afb3b6224d2dce9d
+  data.tar.gz: a883b80b556feaa34abc6544fe7b4c5f03d6da46597c6dc3170d1219ab66aa4018be3233f824ae6df551c50dc963974a35f72ea715037d596a26259bc8087d8a

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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

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

@@ -874,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
@@ -895,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);
@@ -908,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)
@@ -951,9 +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);
         }

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.174.4"
+  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)
@@ -40,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)
@@ -57,11 +57,15 @@ class Leptris::XML::Element < Leptris::XML::Node
       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
 
@@ -91,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)
@@ -104,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)
@@ -137,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

@@ -36,6 +36,9 @@ class Leptris::XML::Node
     @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.
@@ -164,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,
@@ -318,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.
@@ -419,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.4
+  version: 1.9.174.5
 platform: ruby
 authors:
 - Ribose Inc.
@@ -93,6 +93,8 @@ files:
 - 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