leptris 1.9.162.9 → 1.9.163.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 245dd6ccedb905fe340d1ed3117b8a0fd8cc37cfc39c5cb0d3412c1f84dbee80
-  data.tar.gz: f91b66d536994043a4dad8bbf7cf8801b3779bff2d620a2725bf4057f7f3e4bb
+  metadata.gz: c7718cf666bbec3e128c6dd2458d85e59f58757654b67021137e931e92271d19
+  data.tar.gz: 9cece9a47663dcc7c0665201beac6914edc30f08d3680d9ba8bfee64bb2819bd
 SHA512:
-  metadata.gz: 1447bfb2999b6dbd50053281883fadfb45d3730ea8b67990fecaf24ce35cd219b479523a1e0e7b65b1e8f255769a8a77fdc3f82b7daba3b94e167f847dbd8bac
-  data.tar.gz: add08727ca40f2cf397e5e0a256629c2cd5a7f25f5a21ec07fed80241dd4b78b1b89432717cc1edbce081ecae5203a4fbddfd52572220c1a9d37dd5c7ac9b529
+  metadata.gz: 49695f1c96011b812601dfaa6a200403523563737bdb1e470d9f8d5c67fb9e3e6948ede1fef108a2a344df68ef31d69ac931a3f2363d173b7ac7546673ca9340
+  data.tar.gz: a02fe7e50a379fe9d84d1a705234d6c49fba0c52fcf6c4867899ae91aa7b2bc618590bed20bf01a518a6d83b268e440e0beab58f2752eb6d6808a68bdef3b46b

data/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.163.2] - 2026-09-14
+
+### Added
+
+- **TODO.perf/05 — NativeNode surface**: `#attributes` (the
+  flat name=>value hash in one C walk — the `[]` shape, not the
+  binding's Attr-valued hash), `#line`, `#byte_offset` (binding
+  parity). Binding classes inside the ext now resolve lazily —
+  `Init_native` can run before the binding's autoload entries
+  load, and `require "leptris/xml/native_layer"` standalone
+  crashed on undefined `FFI::Pointer` before the ffi require was
+  made explicit.
+
+## [1.9.163.1] - 2026-09-14
+
+### Performance
+
+- **TODO.perf/04 — ext-bound serialization**: `to_xml`/`inner_html`
+  run the whole sized-buffer cycle in C (options on the stack, probe
+  the largest owned buffer first so large documents serialize once,
+  grow-only scratch under the GVL). inner_html per-call batch
+  **84 -> 50 ms (1.7x)**; document serialization at parity (single
+  call both paths); `encoding:` keeps the FFI options path.
+
+## [1.9.163.0] - 2026-09-14
+
+### Performance
+
+- **TODO.perf/01 complete — bulk children for binding wrappers**:
+  with the native layer auto-loaded (1.9.162.9's TODO.perf/02),
+  `Node#children` and `#element_children` construct every binding
+  wrapper in ONE C pass (class dispatch, ivars, identity-cache
+  check/store — the per-child Ruby wrap frames disappear). Cold
+  one-shot walk (fresh doc, element_children + name/[]/content
+  per node): **9.2 -> 1.2 ms (~8x)**. Warm paths unchanged
+  (memoized); scope-owned iterparse elements stay on the FFI path.
+- **TODO.perf/03 — bulk XPath result materialization**: NodeSet
+  materializes through one C pass (kind dispatch with synthetic
+  text/attribute value capture in-C; node-type consult for real
+  Text/CDATA under XPATH's TEXT). One-shot xpath rows gain ~1.4x
+  on the materialization slice (the call is parse-dominated);
+  >512-entry results and rare kinds keep the per-index fallback.
+
 ## [1.9.162.9] - 2026-09-14
 
 ### Performance

data/TODO.perf/01-ext-accelerated-default-reads.md

@@ -7,7 +7,10 @@ cannot see it (memos serve after first touch) — the gate is the
 COLD one-shot pass (fresh doc, one read per node): 13-25% on the
 #187 shape. UTF-8 encoding via rb_utf8_str_new_cstr (suite specs
 run both paths in one process: native_layer_spec sets the flag
-mid-suite). Remaining: children bulk for binding classes.
+mid-suite). COMPLETE (1.9.163.0): bulk children + bulk element_children for
+binding wrappers (one C pass: class dispatch + ivars + identity
+cache) — cold one-shot walk 9.2->1.2ms (7.8x, element_children +
+name/[]/content). Both TODO items done.
 
 The default binding's hot reads each pay FFI per-call marshaling
 (:string returns allocate through FFI, args marshal through the

data/TODO.perf/03-bulk-xpath-result-materialization.md

@@ -1,6 +1,11 @@
 # 03 — Bulk XPath result materialization
 
-Status: TODO
+Status: SHIPPED (1.9.163.0) — one C pass (kind dispatch incl.
+synthetic text/attr value capture, node-type consult for real
+Text/CDATA under XPATH text, identity cache). HONEST FINDING: the
+xpath one-shot is parse-dominated; the materialization slice gains
+~1.4x. >512-entry results and rare kinds fall back to the per-index
+path. No warm-path change.
 
 NodeSet#fetch materializes results per node (wrap per item +
 ResultText/ResultAttr captures). The #185 profile counted

data/TODO.perf/04-ext-bound-serialization.md

@@ -1,6 +1,10 @@
 # 04 — Serialization buffer cycle in C
 
-Status: TODO
+Status: SHIPPED (1.9.163.1) — the sized-buffer cycle runs in C
+(probe largest owned buffer first: single serialization for
+big docs; grow-only scratch under the GVL). inner_html 84->50ms
+(1.7x per-call batch); doc serialize at parity with the FFI seam
+(both single-call); encoding: paths keep the FFI options path.
 
 FFI.serialize_into_string does the two-call sized protocol
 (needed probe, then copy) with Ruby-side buffer management per

data/TODO.perf/05-native-surface-completion.md

@@ -1,6 +1,13 @@
 # 05 — Complete the NativeNode read surface
 
-Status: TODO
+Status: SHIPPED (1.9.163.2) — #attributes (one C walk, string
+values — deliberately the flat [] shape, not the binding's
+Attr-valued hash), #line, #byte_offset with binding parity. Also:
+binding classes in the ext resolve LAZILY (Init may run before
+autoload loads Element — the standalone native_layer require
+crashed before; fixed) and native_layer requires ffi first.
+Remaining cold: writes stay FFI by design; attribute_nodes/
+namespaces deferred until a consumer asks.
 
 Missing on NativeNode vs Element: #attributes (bulk attr hash),
 #attribute_nodes, #namespaces / #prefix, #line / #byte_offset,

data/TODO.perf/06-perf-battery-native-legs.md

@@ -1,6 +1,12 @@
 # 06 — Native-layer legs in the perf battery + drift record
 
-Status: TODO
+Status: SHIPPED (1.9.163.2) — benchmark/native_vs_binding.rb runs
+the walk/read/serialize rows through both surfaces under the
+TODO.restructure/17 load gate. Honest findings recorded: warm rows
+favor the binding's memoization (attr 0.08 vs 0.30 ms; the native
+API pays per-call dispatch with no memo layer); cold one-shot
+favors the native API (1.81 vs 2.39 ms — on TOP of the binding's
+own bulk/fast acceleration); serialize at parity.
 
 benchmark/ gains native-layer legs (walk/build/attr rows via
 NativeNode beside the binding rows) so the drift record tracks

data/ext/leptris/native/native.c

@@ -17,11 +17,23 @@
 typedef const char *(*elem_name_fn)(void *);
 typedef const char *(*text_content_fn)(void *);
 typedef const char *(*attr_fn)(void *, const char *);
-typedef int (*children_ex_fn)(void *, void **, int *, int);
+typedef size_t (*children_ex_fn)(void *, void **, int *, size_t);
 typedef int (*node_type_fn)(void *);
 typedef void *(*next_sibling_fn)(void *);
 typedef void *(*parent_fn)(void *);
 typedef const char *(*elem_prefix_fn)(void *);
+typedef size_t (*xp_count_fn)(void *);
+typedef size_t (*xp_nodes_ex_fn)(void *, void **, int *, size_t);
+typedef int (*xp_node_kind_fn)(void *, int);
+typedef const char *(*xp_node_name_fn)(void *, int);
+typedef const char *(*xp_node_value_fn)(void *, int);
+typedef size_t (*serialize_into_fn)(void *, char *, size_t, void *, void *);
+typedef void *(*attr_first_fn)(void *);
+typedef void *(*attr_next_fn)(void *);
+typedef const char *(*attr_name_fn)(void *);
+typedef const char *(*attr_value_fn)(void *, void *);
+typedef unsigned int (*node_line_fn)(void *);
+typedef size_t (*node_offset_fn)(void *);
 typedef const char *(*element_text_fn)(void *);
 typedef void *(*doc_create_fn)(void);
 typedef void *(*elem_create_fn)(void *, const char *);
@@ -39,6 +51,18 @@ static node_type_fn f_node_type;
 static next_sibling_fn f_next_sibling;
 static parent_fn f_parent;
 static elem_prefix_fn f_elem_prefix;
+static xp_count_fn f_xp_count;
+static xp_nodes_ex_fn f_xp_nodes_ex;
+static xp_node_kind_fn f_xp_node_kind;
+static xp_node_name_fn f_xp_node_name;
+static xp_node_value_fn f_xp_node_value;
+static serialize_into_fn f_doc_serialize, f_elem_serialize;
+static attr_first_fn f_attr_first;
+static attr_next_fn f_attr_next;
+static attr_name_fn f_attr_name;
+static attr_value_fn f_attr_value;
+static node_line_fn f_node_line;
+static node_offset_fn f_node_offset;
 static element_text_fn f_element_text;
 static doc_create_fn f_doc_create;
 static elem_create_fn f_elem_create;
@@ -49,7 +73,8 @@ static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
 static VALUE c_native_node;
-static ID id_wrapper_cache;
+static ID id_wrapper_cache;   /* native_cache: NativeNode identity */
+static ID id_binding_cache;   /* wrapper_cache: binding Node identity */
 
 #define NT_ELEMENT 0
 
@@ -97,6 +122,19 @@ static void resolve_symbols(const char *lib_path)
     f_next_sibling = (next_sibling_fn)lib_sym(h, "leptris_node_next_sibling");
     f_parent = (parent_fn)lib_sym(h, "leptris_node_parent");
     f_elem_prefix = (elem_prefix_fn)lib_sym(h, "leptris_element_prefix");
+    f_xp_count = (xp_count_fn)lib_sym(h, "leptris_xpath_result_count");
+    f_xp_nodes_ex = (xp_nodes_ex_fn)lib_sym(h, "leptris_xpath_result_get_nodes_ex");
+    f_xp_node_kind = (xp_node_kind_fn)lib_sym(h, "leptris_xpath_result_node_kind");
+    f_xp_node_name = (xp_node_name_fn)lib_sym(h, "leptris_xpath_result_node_name");
+    f_xp_node_value = (xp_node_value_fn)lib_sym(h, "leptris_xpath_result_node_value");
+    f_doc_serialize = (serialize_into_fn)lib_sym(h, "leptris_document_serialize_into");
+    f_elem_serialize = (serialize_into_fn)lib_sym(h, "leptris_element_serialize_into");
+    f_attr_first = (attr_first_fn)lib_sym(h, "leptris_element_first_attribute");
+    f_attr_next = (attr_next_fn)lib_sym(h, "leptris_attribute_next");
+    f_attr_name = (attr_name_fn)lib_sym(h, "leptris_attribute_get_name");
+    f_attr_value = (attr_value_fn)lib_sym(h, "leptris_attribute_get_value");
+    f_node_line = (node_line_fn)lib_sym(h, "leptris_node_line");
+    f_node_offset = (node_offset_fn)lib_sym(h, "leptris_node_byte_offset");
     f_element_text = (element_text_fn)lib_sym(h, "leptris_element_text");
     f_doc_create = (doc_create_fn)lib_sym(h, "leptris_document_create");
     f_elem_create = (elem_create_fn)lib_sym(h, "leptris_element_create");
@@ -109,7 +147,11 @@ static void resolve_symbols(const char *lib_path)
         !f_children_ex || !f_node_type || !f_next_sibling || !f_parent ||
         !f_element_text || !f_doc_create || !f_elem_create || !f_text_create ||
         !f_create_child || !f_append_child || !f_set_root || !f_doc_free ||
-        !f_elem_prefix)
+        !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
+        !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
+        !f_doc_serialize || !f_elem_serialize || !f_attr_first ||
+        !f_attr_next || !f_attr_name || !f_attr_value ||
+        !f_node_line || !f_node_offset)
         rb_raise(rb_eRuntimeError, "libleptris symbols missing");
 }
 
@@ -152,18 +194,47 @@ static VALUE nn_allocate(VALUE klass)
 /* Bulk children: one native pass; cache check/store inline; the
  * document's wrapper_cache (a Ruby Hash keyed by address) provides
  * identity for nodes seen through other paths. */
+/* Two-call children fetch (#202): children_ex copies
+ * min(total, cap); a saturated fill means the list may be longer —
+ * query the true count (buf NULL) and refetch grown. */
+static int fetch_children_two_call(void *node, void ***buf_out,
+                                   int **kinds_out)
+{
+    size_t cap = 512;
+    void *b = ruby_xmalloc(cap * sizeof(void *));
+    int *k = ruby_xmalloc((int)cap * sizeof(int));
+    size_t count = f_children_ex(node, b, k, cap);
+    if (count == cap) {
+        size_t total = f_children_ex(node, NULL, NULL, 0);
+        if (total > cap) {
+            ruby_xfree(b);
+            ruby_xfree(k);
+            cap = total;
+            b = ruby_xmalloc(cap * sizeof(void *));
+            k = ruby_xmalloc((int)cap * sizeof(int));
+            count = f_children_ex(node, b, k, cap);
+        }
+    }
+    *buf_out = b;
+    *kinds_out = k;
+    return (int)count;
+}
+
 static VALUE nn_children(VALUE self)
 {
     struct native_node *n;
-    void *buf[512];
-    int kinds[512];
+    void **buf;
+    int *kinds;
     int count, i;
     VALUE cache, out;
 
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
-    count = f_children_ex(n->ptr, buf, kinds, 512);
-    if (count <= 0)
+    count = fetch_children_two_call(n->ptr, &buf, &kinds);
+    if (count <= 0) {
+        ruby_xfree(buf);
+        ruby_xfree(kinds);
         return rb_ary_new2(0);
+    }
 
     cache = rb_funcall(n->document, id_wrapper_cache, 0);
     out = rb_ary_new2(count);
@@ -181,6 +252,8 @@ static VALUE nn_children(VALUE self)
         }
         rb_ary_push(out, child);
     }
+    ruby_xfree(buf);
+    ruby_xfree(kinds);
     return out;
 }
 
@@ -203,15 +276,18 @@ static VALUE nn_type_sym(VALUE self)
 static VALUE nn_element_children(VALUE self)
 {
     struct native_node *n;
-    void *buf[512];
-    int kinds[512];
+    void **buf;
+    int *kinds;
     int count, i;
     VALUE cache, out;
 
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
-    count = f_children_ex(n->ptr, buf, kinds, 512);
-    if (count <= 0)
+    count = fetch_children_two_call(n->ptr, &buf, &kinds);
+    if (count <= 0) {
+        ruby_xfree(buf);
+        ruby_xfree(kinds);
         return rb_ary_new2(0);
+    }
 
     cache = rb_funcall(n->document, id_wrapper_cache, 0);
     out = rb_ary_new();
@@ -230,6 +306,8 @@ static VALUE nn_element_children(VALUE self)
         }
         rb_ary_push(out, child);
     }
+    ruby_xfree(buf);
+    ruby_xfree(kinds);
     return out;
 }
 
@@ -352,6 +430,43 @@ static VALUE nn_set_root(VALUE klass, VALUE document, VALUE element)
     return element;
 }
 
+/* NativeNode surface completion (TODO.perf/05): bulk attribute
+ * hash (name => value, one C walk, no per-attr Ruby frames) and
+ * the position readers. */
+static VALUE nn_attributes(VALUE self)
+{
+    struct native_node *n;
+    VALUE hash;
+    void *attr;
+
+    TypedData_Get_Struct(self, struct native_node, &nn_type, n);
+    hash = rb_hash_new();
+    attr = f_attr_first(n->ptr);
+    while (attr) {
+        const char *name = f_attr_name(attr);
+        const char *value = f_attr_value(n->ptr, attr);
+        rb_hash_aset(hash,
+                     name ? rb_utf8_str_new_cstr(name) : Qnil,
+                     value ? rb_utf8_str_new_cstr(value) : Qnil);
+        attr = f_attr_next(attr);
+    }
+    return hash;
+}
+
+static VALUE nn_line(VALUE self)
+{
+    struct native_node *n;
+    TypedData_Get_Struct(self, struct native_node, &nn_type, n);
+    return UINT2NUM(f_node_line(n->ptr));
+}
+
+static VALUE nn_byte_offset(VALUE self)
+{
+    struct native_node *n;
+    TypedData_Get_Struct(self, struct native_node, &nn_type, n);
+    return ULL2NUM((uint64_t)f_node_offset(n->ptr));
+}
+
 static VALUE nn_address(VALUE self)
 {
     struct native_node *n;
@@ -359,6 +474,289 @@ static VALUE nn_address(VALUE self)
     return ULL2NUM((uint64_t)(uintptr_t)n->ptr);
 }
 
+/* ---- Bulk children for BINDING wrappers (TODO.perf/01 tail) ----
+ * One C pass: children_ex + binding-class dispatch + ivar set +
+ * identity-cache check/store. Returns a Ruby Array of Element/
+ * Text/... wrappers — Node#children swaps this in when the ext
+ * is loaded. Class constants and FFI::Pointer resolve once at
+ * Init; the per-node Ruby frames (wrap/construct/memo/alive)
+ * disappear. */
+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_ffi_pointer;
+static ID id_ptr_new;
+
+/* Binding classes resolve LAZILY: Init_native can run before the
+ * binding's autoload entries load (require "leptris" flow) —
+ * rb_path2class at Init time raises for undefined constants. */
+static void resolve_binding_classes(void)
+{
+    if (c_b_element != Qundef)
+        return;
+    c_b_element = rb_path2class("Leptris::XML::Element");
+    c_b_text = rb_path2class("Leptris::XML::Text");
+    c_b_comment = rb_path2class("Leptris::XML::Comment");
+    c_b_cdata = rb_path2class("Leptris::XML::CDATA");
+    c_b_pi = rb_path2class("Leptris::XML::ProcessingInstruction");
+    c_b_node = rb_path2class("Leptris::XML::Node");
+    c_b_result_text = rb_path2class("Leptris::XML::ResultText");
+    c_b_result_attr = rb_path2class("Leptris::XML::ResultAttr");
+    c_ffi_pointer = rb_path2class("FFI::Pointer");
+    id_ptr_new = rb_intern("new");
+    rb_gc_register_mark_object(c_b_element);
+    rb_gc_register_mark_object(c_b_text);
+    rb_gc_register_mark_object(c_b_comment);
+    rb_gc_register_mark_object(c_b_cdata);
+    rb_gc_register_mark_object(c_b_pi);
+    rb_gc_register_mark_object(c_b_node);
+    rb_gc_register_mark_object(c_b_result_text);
+    rb_gc_register_mark_object(c_b_result_attr);
+    rb_gc_register_mark_object(c_ffi_pointer);
+}
+
+static VALUE binding_klass_for(int kind)
+{
+    switch (kind) {
+    case 0: return c_b_element;
+    case 1: return c_b_text;
+    case 2: return c_b_comment;
+    case 3: return c_b_cdata;
+    case 4: return c_b_pi;
+    default: return c_b_node;
+    }
+}
+
+static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
+                                int elements_only)
+{
+    void **buf;
+    int *kinds;
+    int count, i;
+    VALUE cache, out;
+
+    count = fetch_children_two_call((void *)(uintptr_t)NUM2ULL(parent_addr),
+                                    &buf, &kinds);
+    if (count <= 0) {
+        ruby_xfree(buf);
+        ruby_xfree(kinds);
+        return rb_ary_new2(0);
+    }
+
+    cache = rb_funcall(document, id_binding_cache, 0);
+    out = rb_ary_new2(elements_only ? 8 : count);
+    for (i = 0; i < count; i++) {
+        VALUE key, node;
+        if (elements_only && kinds[i] != 0)
+            continue;
+        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, "@document", document);
+            rb_iv_set(node, "@parent", Qnil);
+            rb_iv_set(node, "@node_type", INT2FIX(kinds[i]));
+            rb_hash_aset(cache, key, node);
+        }
+        rb_ary_push(out, node);
+    }
+    ruby_xfree(buf);
+    ruby_xfree(kinds);
+    return out;
+}
+
+static VALUE nf_bulk_children(VALUE self, VALUE document, VALUE parent_addr)
+{
+    (void)self;
+    resolve_binding_classes();
+    return bulk_children_impl(document, parent_addr, 0);
+}
+
+static VALUE nf_bulk_element_children(VALUE self, VALUE document,
+                                      VALUE parent_addr)
+{
+    (void)self;
+    resolve_binding_classes();
+    return bulk_children_impl(document, parent_addr, 1);
+}
+
+/* ---- Bulk XPath result materialization (TODO.perf/03) ----------
+ * One C pass over leptris_xpath_result_get_nodes_ex: binding-class
+ * dispatch (XPATH_NODE space: 0 element, 1 attribute, 2 text,
+ * 3 other), value capture for synthetic text/attribute items
+ * while the result handle is alive, identity-cache check/store
+ * for elements. Returns the Ruby Array. */
+static VALUE m_native_sentinel; /* module object = fallback marker */
+
+static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
+{
+    void *result = (void *)(uintptr_t)NUM2ULL(result_ptr_val);
+    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)
+        return rb_ary_new2(0);
+
+    buf = ruby_xmalloc(scount * sizeof(void *));
+    kinds = ruby_xmalloc(scount * sizeof(int));
+    scount = f_xp_nodes_ex(result, buf, kinds, scount);
+    count = (int)scount;
+    if (count <= 0) {
+        ruby_xfree(buf);
+        ruby_xfree(kinds);
+        return rb_ary_new2(0);
+    }
+    cache = rb_funcall(document, id_binding_cache, 0);
+    out = rb_ary_new2(count);
+    for (i = 0; i < count; i++) {
+        VALUE node, key;
+        const char *s;
+        if (buf[i] == NULL)
+            continue;
+        key = ULL2NUM((uint64_t)(uintptr_t)buf[i]);
+        switch (kinds[i]) {
+        case 0: /* element */
+            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(c_b_element);
+                rb_iv_set(node, "@c_ptr", ptr);
+                rb_iv_set(node, "@document", document);
+                rb_iv_set(node, "@parent", Qnil);
+                rb_iv_set(node, "@node_type", INT2FIX(0));
+                rb_hash_aset(cache, key, node);
+            }
+            break;
+        case 1: /* synthetic attribute */
+            {
+                const char *name = f_xp_node_name(result, i);
+                const char *value = f_xp_node_value(result, i);
+                VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
+                node = rb_obj_alloc(c_b_result_attr);
+                rb_iv_set(node, "@c_ptr", ptr);
+                rb_iv_set(node, "@document", document);
+                rb_iv_set(node, "@attr_name",
+                          name ? rb_utf8_str_new_cstr(name) : Qnil);
+                rb_iv_set(node, "@attr_value",
+                          value ? rb_utf8_str_new_cstr(value) : Qnil);
+            }
+            break;
+        case 2: /* text-kind: synthetic sequence carrier, or a real
+                 * Text/CDATA node (XPath reports both as TEXT) —
+                 * dispatch on the node's own type like Node.wrap. */
+            {
+                int nt = f_node_type(buf[i]);
+                if (nt == 8) { /* NODE_SYNTHETIC_TEXT */
+                    s = f_xp_node_value(result, i);
+                    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, "@document", document);
+                    rb_iv_set(node, "@value",
+                              s ? rb_utf8_str_new_cstr(s) : Qnil);
+                } else {
+                    VALUE ptr = rb_funcall(c_ffi_pointer, id_ptr_new, 1, key);
+                    node = rb_hash_aref(cache, key);
+                    if (NIL_P(node)) {
+                        node = rb_obj_alloc(binding_klass_for(nt));
+                        rb_iv_set(node, "@c_ptr", ptr);
+                        rb_iv_set(node, "@document", document);
+                        rb_iv_set(node, "@parent", Qnil);
+                        rb_iv_set(node, "@node_type", INT2FIX(nt));
+                        rb_hash_aset(cache, key, node);
+                    }
+                }
+            }
+            break;
+        default: /* other: rare — signal Ruby fallback for this index */
+            rb_ary_push(out, m_native_sentinel);
+            continue;
+        }
+        rb_ary_push(out, node);
+    }
+    ruby_xfree(buf);
+    ruby_xfree(kinds);
+    return out;
+}
+
+/* ---- Ext-bound serialization (TODO.perf/04) ---------------------
+ * The whole sized-buffer cycle in C: build SerializeOptions on
+ * the stack, call (buf, cap, NULL status, opts), grow if needed,
+ * return a UTF-8 String. No FFI marshaling, no Ruby buffer
+ * management per to_xml call. */
+struct serialize_opts {
+    int indent;
+    int xml_declaration;
+    const char *encoding;
+};
+
+/* Grow-only scratch for large serializations. Safe under the GVL:
+ * synchronous C calls hold it, so no two Ruby threads run this
+ * concurrently. */
+static char *ser_buf;
+static size_t ser_cap;
+
+static VALUE fast_serialize(serialize_into_fn fn, void *node,
+                            int indent, int xml_declaration)
+{
+    struct serialize_opts opts;
+    char stack_buf[4096];
+    size_t needed;
+
+    char *probe;
+    size_t probe_cap;
+
+    opts.indent = indent;
+    opts.xml_declaration = xml_declaration;
+    opts.encoding = NULL;
+    /* Probe the largest buffer we own: a big scratch from a prior
+     * call usually fits (single serialization); cold calls start
+     * on the stack buffer. */
+    if (ser_cap > sizeof(stack_buf)) {
+        probe = ser_buf;
+        probe_cap = ser_cap;
+    } else {
+        probe = stack_buf;
+        probe_cap = sizeof(stack_buf);
+    }
+    needed = fn(node, probe, probe_cap, NULL, &opts);
+    if (needed == 0)
+        return rb_utf8_str_new_cstr("");
+    if (needed <= probe_cap)
+        return rb_utf8_str_new(probe, needed - 1);
+    if (needed > ser_cap) {
+        ser_buf = ruby_xrealloc(ser_buf, needed);
+        ser_cap = needed;
+    }
+    needed = fn(node, ser_buf, ser_cap, NULL, &opts);
+    return needed > 0 ? rb_utf8_str_new(ser_buf, needed - 1)
+                      : rb_utf8_str_new_cstr("");
+}
+
+static VALUE nf_fast_document_xml(VALUE self, VALUE addr,
+                                  VALUE indent, VALUE decl)
+{
+    (void)self;
+    return fast_serialize(f_doc_serialize,
+                          (void *)(uintptr_t)NUM2ULL(addr),
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+}
+
+static VALUE nf_fast_element_xml(VALUE self, VALUE addr,
+                                 VALUE indent, VALUE decl)
+{
+    (void)self;
+    return fast_serialize(f_elem_serialize,
+                          (void *)(uintptr_t)NUM2ULL(addr),
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+}
+
 /* ---- Address-based fast readers (TODO.perf/01) -----------------
  * The DEFAULT binding classes call these when the bundle is
  * loaded: one C-API dispatch + rb_utf8_str_new_cstr — no FFI
@@ -432,6 +830,7 @@ void Init_native(void)
     rb_undef_alloc_func(c_native_node);
 
     id_wrapper_cache = rb_intern("native_cache");
+    id_binding_cache = rb_intern("wrapper_cache");
 
     rb_define_singleton_method(c_native_node, "from", nn_from, 2);
     rb_define_singleton_method(c_native_node, "create_element", nn_create_element, 2);
@@ -441,6 +840,9 @@ void Init_native(void)
     rb_define_method(c_native_node, "append_child", nn_append_child, 1);
     rb_define_method(c_native_node, "add_child", nn_append_child, 1);
     rb_define_method(c_native_node, "address", nn_address, 0);
+    rb_define_method(c_native_node, "attributes", nn_attributes, 0);
+    rb_define_method(c_native_node, "line", nn_line, 0);
+    rb_define_method(c_native_node, "byte_offset", nn_byte_offset, 0);
     rb_define_method(c_native_node, "name", nn_name, 0);
     rb_define_method(c_native_node, "content", nn_content, 0);
     rb_define_method(c_native_node, "attribute", nn_attribute, 1);
@@ -454,8 +856,17 @@ void Init_native(void)
                                leptris_native_resolve_rb, 1);
 
     m_native = rb_define_module_under(m_xml, "Native");
+    m_native_sentinel = m_native;
     rb_define_module_function(m_native, "fast_name", nf_name, 1);
     rb_define_module_function(m_native, "fast_element_text", nf_element_text, 1);
     rb_define_module_function(m_native, "fast_attribute", nf_attribute, 2);
     rb_define_module_function(m_native, "fast_prefix", nf_prefix, 1);
+    rb_define_module_function(m_native, "bulk_children", nf_bulk_children, 2);
+    rb_define_module_function(m_native, "bulk_element_children",
+                              nf_bulk_element_children, 2);
+    rb_define_module_function(m_native, "bulk_xpath", nf_bulk_xpath, 2);
+    rb_define_module_function(m_native, "fast_document_xml",
+                              nf_fast_document_xml, 3);
+    rb_define_module_function(m_native, "fast_element_xml",
+                              nf_fast_element_xml, 3);
 }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/native_layer.rb

@@ -14,6 +14,8 @@
 # installs without the compiled bundle (ruby-platform gem) raise
 # a clear LoadError from the require.
 
+require "ffi" unless defined?(::FFI::Library)
+
 begin
   # The compiled bundle (feature "leptris/xml/native" resolves
   # native.bundle). A sanctioned require exception: a .bundle

data/lib/leptris/xml/node.rb

@@ -52,7 +52,12 @@ class Leptris::XML::Node
       cache = document.wrapper_cache
       address = c_ptr.address
       if (cached = cache[address])
-        return cached
+        # The shared cache also holds NativeNodes (opt-in layer).
+        # Only return a hit when it is a binding Node subclass —
+        # otherwise fall through and construct the binding wrapper
+        # (both views of the same C node can coexist; the native
+        # entry stays under its own key-path via NativeNode.from).
+        return cached if cached.is_a?(Leptris::XML::Node)
       end
     end
 
@@ -125,6 +130,13 @@ class Leptris::XML::Node
 
   def element?;  type == Leptris::XML::FFI::NODE_ELEMENT;  end
 
+  # The ext bulk path applies to document-owned trees only:
+  # scope-owned (iterparse) elements ride the IterationScope seam.
+  def native_fast_children?
+    defined?(Leptris::XML::NATIVE_FAST) &&
+      !@document.is_a?(Leptris::XML::IterationScope)
+  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,
@@ -228,6 +240,18 @@ 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?
+      # 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)
+      result = Leptris::XML::NodeSet.new(@document, nodes)
+      if @document
+        @children = result
+        @children_version = @document.version
+      end
+      return result
+    end
     parent = as_element_or_self
     pointers, kinds = Leptris::XML::FFI.fetch_children(@c_ptr)
     nodes = Array.new(pointers.size) do |i|
@@ -303,7 +327,9 @@ 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 is_a?(Leptris::XML::Element)
+      if native_fast_children?
+        Leptris::XML::Native.bulk_element_children(@document, @c_ptr.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::Node.wrap(ptr, @document, parent: parent,

data/lib/leptris/xml/node_set.rb

@@ -71,6 +71,11 @@ class Leptris::XML::NodeSet
 
   # Sequence/map/array items ride synthetic text nodes whose value
   # only the live result handle can serve — capture it now.
+  def native_fast?
+    defined?(Leptris::XML::NATIVE_FAST)
+  end
+  private :native_fast?
+
   def text_item_value(kind, index)
     case kind
     when Leptris::XML::FFI::XPATH_NODE_TEXT
@@ -95,7 +100,37 @@ class Leptris::XML::NodeSet
     unless @array
       return self unless @result_ptr
       n = length
-      if n > 0
+      if n > 0 && native_fast?
+        # TODO.perf/03: one C pass materializes the whole result —
+        # class dispatch, synthetic text/attr value capture, and
+        # element identity-cache check/store in the ext. Qundef
+        # slots (rare non-element/attr/text kinds) and the >512
+        # remainder fall back to the per-index path below.
+        fast = Leptris::XML::Native.bulk_xpath(
+          @document, @result_ptr.to_i)
+        nodes = []
+        fast.each_with_index do |node, i|
+          if node.equal?(Leptris::XML::Native)
+            ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+            next if ptr.null?
+            nodes << Leptris::XML::Node.wrap(
+              ptr, @document,
+              result_value: text_item_value(
+                Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, i), i))
+          else
+            nodes << node
+          end
+        end
+        (fast.length...n).each do |i|
+          ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+          next if ptr.null?
+          nodes << Leptris::XML::Node.wrap(
+            ptr, @document,
+            result_value: text_item_value(
+              Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, i), i))
+        end
+        @array = nodes
+      elsif n > 0
         # Batch-fetch all node pointers through the FFI seam
         # (leptris_xpath_result_get_nodes_ex copies every node kind,
         # not just elements); the batch accessor under-copies

data/lib/leptris/xml/serialization.rb

@@ -32,6 +32,18 @@ module Leptris::XML::Serialization
   # cycle lives at the FFI seam (FFI.serialize_into_string); this
   # module owns only options selection and construction.
   def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
+    # TODO.perf/04: the common shape (no encoding) runs the whole
+    # sized-buffer cycle in the ext — one C dispatch, no options
+    # marshaling, no Ruby buffer management.
+    if defined?(Leptris::XML::NATIVE_FAST) && encoding.nil?
+      decl = !no_decl
+      return Leptris::XML::Native.fast_element_xml(
+        c_ptr.address, indent.to_i, decl) if
+        ffi_function == ELEMENT_SERIALIZE_INTO
+      return Leptris::XML::Native.fast_document_xml(
+        c_ptr.address, indent.to_i, decl) if
+        ffi_function == DOCUMENT_SERIALIZE_INTO
+    end
     opts =
       if indent.to_i.zero? && !no_decl && encoding.nil?
         DEFAULT_OPTIONS
@@ -47,6 +59,8 @@ module Leptris::XML::Serialization
   # loop: no kwargs, no options rebuild, no method allocation —
   # one FFI fast-path dispatch per child.
   def self.element_xml_default(c_ptr)
+    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true) if
+      defined?(Leptris::XML::NATIVE_FAST)
     Leptris::XML::FFI.serialize_into_string(
       ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.162.9
+  version: 1.9.163.2
 platform: ruby
 authors:
 - Ribose Inc.