leptris 1.9.162.8 → 1.9.162.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec940fa88dc62b9bd98c0268fb7769274c2b919cc34b63d15b8b9f846b4f6374
-  data.tar.gz: b8167cf9190c65b87d6cc91dd7c8a949343187eff563758c0b6c9c4c07c5c541
+  metadata.gz: 245dd6ccedb905fe340d1ed3117b8a0fd8cc37cfc39c5cb0d3412c1f84dbee80
+  data.tar.gz: f91b66d536994043a4dad8bbf7cf8801b3779bff2d620a2725bf4057f7f3e4bb
 SHA512:
-  metadata.gz: 3bbe8b668a992020233f5a7c5f9a26aed7701a227db29cf15e5e80209df45e5be0fbe0f32a9de6459dd9ebfb2e4f4c134c99c8282501a7291e7a8a1924118011
-  data.tar.gz: 39d84a702970ad1c02b369c3114c2d3abf0efbf98ffd5dd55e0c178326f68f9af1ac8946f84918a69b1fbc610e287f14c875feab8d24a339c7d01845a38a8ce0
+  metadata.gz: 1447bfb2999b6dbd50053281883fadfb45d3730ea8b67990fecaf24ce35cd219b479523a1e0e7b65b1e8f255769a8a77fdc3f82b7daba3b94e167f847dbd8bac
+  data.tar.gz: add08727ca40f2cf397e5e0a256629c2cd5a7f25f5a21ec07fed80241dd4b78b1b89432717cc1edbce081ecae5203a4fbddfd52572220c1a9d37dd5c7ac9b529

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.162.9] - 2026-09-14
+
+### Performance
+
+- **TODO.perf/01 — ext-accelerated default reads**: with the
+  native layer loaded, the DEFAULT binding classes' hot reads
+  (`Element#name`, `#content`, `#prefix`, `#[]`'s engine lookups)
+  call the ext directly (one C-API dispatch + UTF-8 string build —
+  no FFI marshaling): name 276->84ns, attribute 373->199ns per
+  read. Warm loops are memo-served and unaffected; the win lands
+  on cold one-shot passes (fresh doc, single read per node):
+  13-25% on the #187 workload shape. Scope-owned (iterparse)
+  elements stay on the FFI path (pool addresses recycle).
+- **TODO.perf/02 — auto-enable**: `require "leptris"` quietly
+  activates the native acceleration when the compiled bundle is
+  present (platform gems). Falls back to pure FFI when absent
+  (ruby-variant on TruffleRuby/JRuby). `LEPTRIS_NO_NATIVE=1`
+  forces the FFI path. The explicit `native_layer` require remains
+  the parallel-API entry for NativeNode builders.
+
 ## [1.9.162.8] - 2026-09-14
 
 ### Added

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

@@ -1,6 +1,13 @@
 # 01 — Ext-accelerated default reads (no FFI marshaling on hot paths)
 
-Status: TODO
+Status: SHIPPED (1.9.162.9) — name/content/prefix/[]-cold-path ride
+the ext when the bundle is loaded. Per-read 276->84ns (3.3x,
+pre-address) / attr 373->199ns. HONEST GATE FINDING: warm loops
+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.
 
 The default binding's hot reads each pay FFI per-call marshaling
 (:string returns allocate through FFI, args marshal through the

data/TODO.perf/02-auto-enable-native-layer.md

@@ -1,6 +1,10 @@
 # 02 — Auto-enable the native layer when the bundle is present
 
-Status: TODO
+Status: SHIPPED (1.9.162.9) — require "leptris" quietly
+probes for the native bundle and activates when present.
+LEPTRIS_NO_NATIVE=1 forces the FFI path (suite exercises both).
+The explicit native_layer require remains the parallel-API entry
+for NativeNode builders.
 
 Today `require "leptris/xml/native_layer"` is opt-in. End-state:
 `require "leptris"` quietly probes for the vendored native.bundle

data/ext/leptris/native/native.c

@@ -21,6 +21,7 @@ typedef int (*children_ex_fn)(void *, void **, int *, int);
 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 const char *(*element_text_fn)(void *);
 typedef void *(*doc_create_fn)(void);
 typedef void *(*elem_create_fn)(void *, const char *);
@@ -37,6 +38,7 @@ static children_ex_fn f_children_ex;
 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 element_text_fn f_element_text;
 static doc_create_fn f_doc_create;
 static elem_create_fn f_elem_create;
@@ -94,6 +96,7 @@ static void resolve_symbols(const char *lib_path)
     f_node_type = (node_type_fn)lib_sym(h, "leptris_node_get_type");
     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_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");
@@ -105,7 +108,8 @@ static void resolve_symbols(const char *lib_path)
     if (!f_elem_name || !f_text_content || !f_attr ||
         !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_create_child || !f_append_child || !f_set_root || !f_doc_free ||
+        !f_elem_prefix)
         rb_raise(rb_eRuntimeError, "libleptris symbols missing");
 }
 
@@ -115,7 +119,7 @@ static VALUE nn_name(VALUE self)
     const char *s;
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
     s = f_elem_name(n->ptr);
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_content(VALUE self)
@@ -127,7 +131,7 @@ static VALUE nn_content(VALUE self)
      * nodes carry it directly. */
     s = f_node_type(n->ptr) == 0 ? f_element_text(n->ptr)
                                  : f_text_content(n->ptr);
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_attribute(VALUE self, VALUE name)
@@ -136,7 +140,7 @@ static VALUE nn_attribute(VALUE self, VALUE name)
     const char *s;
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
     s = f_attr(n->ptr, StringValueCStr(name));
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_allocate(VALUE klass)
@@ -355,6 +359,43 @@ static VALUE nn_address(VALUE self)
     return ULL2NUM((uint64_t)(uintptr_t)n->ptr);
 }
 
+/* ---- 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
+ * marshaling. Addresses come from FFI::Pointer#address (a Ruby
+ * ivar read on the ffi gem's Pointer). */
+static VALUE nf_name(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_elem_name((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_element_text(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_element_text((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_attribute(VALUE self, VALUE addr, VALUE name)
+{
+    const char *s;
+    (void)self;
+    s = f_attr((void *)(uintptr_t)NUM2ULL(addr), StringValueCStr(name));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_prefix(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_elem_prefix((void *)(uintptr_t)NUM2ULL(addr));
+    return (s && *s) ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
 static VALUE nn_from(VALUE klass, VALUE document, VALUE element)
 {
     /* Element address comes through the binding's #c_ptr address;
@@ -383,7 +424,7 @@ static VALUE leptris_native_resolve_rb(VALUE self, VALUE lib_path)
 
 void Init_native(void)
 {
-    VALUE m_leptris, m_xml;
+    VALUE m_leptris, m_xml, m_native;
 
     m_leptris = rb_define_module("Leptris");
     m_xml = rb_define_module_under(m_leptris, "XML");
@@ -411,4 +452,10 @@ void Init_native(void)
     rb_define_method(c_native_node, "node_type", nn_type_sym, 0);
     rb_define_singleton_method(c_native_node, "resolve!",
                                leptris_native_resolve_rb, 1);
+
+    m_native = rb_define_module_under(m_xml, "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);
 }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/element.rb

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
 class Leptris::XML::Element < Leptris::XML::Node
+  # TODO.perf/01: with the native bundle loaded, hot reads go
+  # through the ext (one C-API dispatch + rb_str_new_cstr — no FFI
+  # marshaling; ~3x per read). defined? is near-free when absent.
+  # Scope-owned (iterparse-yield) elements stay on the FFI path:
+  # their pool addresses recycle across yields and their lifetime
+  # rules ride the IterationScope seam — the ext fast path is for
+  # document-owned trees.
+  def native_fast?
+    defined?(Leptris::XML::NATIVE_FAST) && !scope_owned?
+  end
+
   def name
     return @name if @name
     ensure_alive!
-    @name = Leptris::XML::FFI.leptris_element_name(@c_ptr)
+    @name = if native_fast?
+              Leptris::XML::Native.fast_name(@c_ptr.address)
+            else
+              Leptris::XML::FFI.leptris_element_name(@c_ptr)
+            end
   end
   alias_method :node_name, :name
 
@@ -19,7 +34,11 @@ class Leptris::XML::Element < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_element_text(@c_ptr)
+    result = if native_fast?
+               Leptris::XML::Native.fast_element_text(@c_ptr.address)
+             else
+               Leptris::XML::FFI.leptris_element_text(@c_ptr)
+             end
     if @document
       @content = result
       @content_version = @document.version
@@ -60,7 +79,11 @@ 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 = Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+        v = if native_fast?
+                 Leptris::XML::Native.fast_attribute(@c_ptr.address, name)
+               else
+                 Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+               end
         values[name] = v
         return v
       end
@@ -203,7 +226,12 @@ class Leptris::XML::Element < Leptris::XML::Node
   # or nil when the element has none.
   def prefix
     ensure_alive!
-    Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+    if native_fast?
+      Leptris::XML::Native.fast_prefix(@c_ptr.address)
+    else
+      result = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+      result if result && !result.empty?
+    end
   end
 
   # The written qualified name — "foo:child" with a prefix, the

data/lib/leptris/xml/native_layer.rb

@@ -37,6 +37,10 @@ module Leptris::XML::Native
   end
 end
 
+# TODO.perf/01: accelerate the DEFAULT binding classes while the
+# bundle is loaded (name/content/prefix/[] hot reads).
+Leptris::XML::NATIVE_FAST = true
+
 candidates = Leptris::XML::Native.lib_candidates
 resolved = candidates.any? do |path|
   begin

data/lib/leptris.rb

@@ -31,3 +31,18 @@ rescue LoadError => e
     (Underlying error: #{e.message})
   MSG
 end
+
+# TODO.perf/02: auto-enable the native acceleration layer when the
+# compiled bundle is present (platform gems). Quietly falls back
+# to pure FFI when absent (ruby-variant on TruffleRuby/JRuby,
+# custom builds). LEPTRIS_NO_NATIVE=1 forces the FFI path (the
+# suite uses it to exercise both surfaces). The explicit
+# `require "leptris/xml/native_layer"` remains the parallel-API
+# entry for NativeNode builders.
+unless ENV["LEPTRIS_NO_NATIVE"] == "1"
+  begin
+    require "leptris/xml/native_layer"
+  rescue LoadError
+    nil
+  end
+end

metadata

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