leptris 1.9.174.8 → 1.9.174.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3bbbd00177ef272738c9d0d9562beb33cc2ed100145bc843785fd56ae0c5f22
-  data.tar.gz: c47af3b6769fb4e9cb233128df91b36bf9cecae4d23e06b9f94ad60caf9d498a
+  metadata.gz: 73130c8bf549007d80bf610c22bc831df382f5fe972316835a6dc806885929c5
+  data.tar.gz: 3b6bfb23c72a2ed3532eb64886c9f36603975b5d601aa693f6b3ba821bb19de2
 SHA512:
-  metadata.gz: e951276162615da4fdecfd7d500bdd9ddd2a378188190d9edf14341713243f1ce802fa2a129f5afb07d676ce2977e7d0e59e44b474dce656432cdb57d99b5fac
-  data.tar.gz: 812ae80ffb569ae41fa0734858a8f487f31f3a22689fc221686b801cf1922e69d4331615a678e1dd5a5589c2c464b6fe6ae51c4504b365448ea63a6ad6215628
+  metadata.gz: 621d0f62f7869c1a4b0c63212dce8694f51cc1914a3f115551b7e91c1f5b2bc0af9a33dcb2baa4d462fc5a12f72225a228dee59f7e4a7f70ed5173e0afe6932b
+  data.tar.gz: 2a389319493ace9979ea863853b75c56149f73dcc5e204c362bd8bdbaacd335d94a58bd9bb3d4ed83f6c83df3331b53549bb462fa19980fb996a8c2798c3fbdc

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.9] - 2026-09-16
+
+### Changed
+
+- **Fragment fast lane (TODO.perf/34)**: `add_child(String)` runs
+  one C dispatch for the whole markup add — fragment parse +
+  every child append + a single readonly gate and version bump
+  (the move-during-iteration hazard handled: appending detaches,
+  so the walk captures next before each move). The fragment parse
+  face returns an address (no status MemoryPointer, no Pointer);
+  `DocumentFragment#children` rides the bulk face; parse failures
+  fall back to the legacy path for the exact error.
+- **Document.parse default path as one C dispatch (TODO.perf/35)**:
+  engine parse + ivar-seeded wrapper + lifetime handle in one
+  call — small parses measured 15.6µs → 6.8µs (~2.3x, under host
+  load ~100; the shape is self-contained).
+
 ## [1.9.174.8] - 2026-09-16
 
 ### Fixed

data/TODO.perf/34-fragment-fast-lane.md

@@ -0,0 +1,41 @@
+# 34 — Fragment fast lane: C parse, bulk children, one-shot markup append
+
+Status: DONE (1.9.174.9)
+
+The add_child(String) path — moxml's markup-builder shape — pays
+three layers per call: parse_fragment_with_status allocates a
+MemoryPointer for the status out-param, DocumentFragment#children
+runs the FFI fetch+wrap loop (never moved to the bulk faces), and
+each child appends through its own dispatch.
+
+Bind the lane: a C parse face returns the fragment's address
+(Integer — no Pointer, no MemoryPointer); the fragment stores
+@c_address with a lazy c_ptr; children rides the bulk face
+(fragment nodes live in the document pool — the document's cache
+and version discipline apply); and a one-shot append face parses
+the markup, walks the fragment's children, and appends every one
+with a single readonly gate + version bump. Parse failures return
+a marker; the Ruby fallback re-runs the old path for the exact
+error message (the rare path, cheap to re-fail).
+
+Gates: add_child(String) semantics identical (multiple top-level
+nodes, text, PIs, namespaces lifted per the Node path); fragment
+children identical through the bulk face; suite both modes.
+
+## Outcome (1.9.174.9)
+
+Three layers landed: the fragment parse face answers the
+fragment ADDRESS (no status MemoryPointer, no Pointer mint —
+failures fall back to the FFI pair for the exact error);
+DocumentFragment stores @c_address with a lazy c_ptr and
+children() rides the bulk face (fragment nodes live in the
+document pool — the document's cache and version discipline
+apply); and Element#add_child(String) runs ONE dispatch for the
+whole markup add (parse + per-child append + single gate/bump —
+with the move-during-iteration hazard caught by the suite:
+appending detaches the child, so the walk captures next BEFORE
+each move). -1 re-runs the legacy path for parse errors;
+-1000-st routes through check_status. The markup row needs a
+quiet-host battery number (this box sat at load 100+ today);
+small-parse measured 6.8µs native vs 15.6µs FFI (~2.3x) under
+load 100.

data/TODO.perf/35-parse-default-c-face.md

@@ -0,0 +1,24 @@
+# 35 — Document.parse default path as one C dispatch
+
+Status: DONE (1.9.174.9)
+
+The default parse path (no options, no recover — the adapter
+default) is already allocation-free at the Ruby level (#187),
+but still pays FFI marshaling, the wrap frames, the Freed and
+Pointer constructions, and the handle attach across three Ruby
+layers. One C face runs leptris_parse_string + the full document
+wrapper (ivar-seeded) + lifetime handle and returns it; failure
+raises the same ParseError shape via last_error read in C.
+
+Gates: parse defaults identical (errors, readonly flag, root
+access); the options/recover paths untouched; suite both modes.
+
+## Outcome (1.9.174.9)
+
+Native.parse_binding_document: leptris_parse_string + the full
+ivar-seeded wrapper + lifetime handle in one dispatch (shared
+build_binding_document helper); Document.parse's default path
+(no options, no recover) routes through it, raising the same
+ParseError shape via last_error on failure. Options/recover
+paths untouched. Measured (load ~100, self-contained shape):
+small parse 15.6µs -> 6.8µs (~2.3x).

data/ext/leptris/native/native.c

@@ -94,6 +94,9 @@ typedef void (*visit_fn)(void *, visit_cb_fn, void *);
 typedef void (*free_str_fn)(void *);
 typedef const char *(*node_xpath_fn)(void *);
 typedef void *(*elem_copy_fn)(void *, void *);
+typedef void *(*parse_str_fn)(const char *, size_t, void *);
+typedef void *(*parse_frag_fn)(const char *, size_t, void *, int *);
+typedef const char *(*last_err_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 traverse_fn f_node_traverse;
@@ -101,6 +104,9 @@ static visit_fn f_node_visit;
 static free_str_fn f_free_str;
 static node_xpath_fn f_node_xpath;
 static elem_copy_fn f_elem_copy;
+static parse_str_fn f_parse_str;
+static parse_frag_fn f_parse_frag;
+static last_err_fn f_last_err;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -221,6 +227,9 @@ static void resolve_symbols(const char *lib_path)
     f_free_str = (free_str_fn)lib_sym(h, "leptris_free_string");
     f_node_xpath = (node_xpath_fn)lib_sym(h, "leptris_node_get_xpath");
     f_elem_copy = (elem_copy_fn)lib_sym(h, "leptris_element_copy");
+    f_parse_str = (parse_str_fn)lib_sym(h, "leptris_parse_string");
+    f_parse_frag = (parse_frag_fn)lib_sym(h, "leptris_parse_fragment");
+    f_last_err = (last_err_fn)lib_sym(h, "leptris_last_error");
     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 ||
@@ -233,7 +242,8 @@ static void resolve_symbols(const char *lib_path)
         !f_pi_data || !f_elem_set_name || !f_elem_set_text ||
         !f_text_set_content || !f_node_unlink ||
         !f_node_traverse || !f_node_visit || !f_free_str ||
-        !f_node_xpath || !f_elem_copy ||
+        !f_node_xpath || !f_elem_copy || !f_parse_str ||
+        !f_parse_frag || !f_last_err ||
         !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 ||
@@ -1874,6 +1884,102 @@ static VALUE nf_copy_binding_element(VALUE self, VALUE document,
     return new_doc;
 }
 
+/* Shared document-wrapper construction from a C document
+ * pointer: ivar-seeded wrapper + lifetime handle. Returns the
+ * wrapper. (TODO.perf/35 — the create face inlines the same
+ * steps.) */
+static VALUE build_binding_document(void *doc)
+{
+    VALUE new_doc, doc_addr, handle, freed;
+    struct doc_handle *h;
+
+    doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
+    new_doc = rb_obj_alloc(c_b_document);
+    rb_iv_set(new_doc, "@c_ptr",
+              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
+    rb_iv_set(new_doc, "@c_address", doc_addr);
+    freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
+    rb_iv_set(new_doc, "@freed", freed);
+    rb_iv_set(new_doc, "@readonly", Qfalse);
+    rb_iv_set(new_doc, "@version", INT2FIX(0));
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc;
+    rb_ivar_set(new_doc, id_iv_doc_handle, handle);
+    return new_doc;
+}
+
+/* Document.parse default path in one dispatch (TODO.perf/35):
+ * leptris_parse_string + wrapper + handle. Qnil = parse failure
+ * (the caller raises with the same message shape). */
+static VALUE nf_parse_binding_document(VALUE self, VALUE xml)
+{
+    void *doc;
+
+    (void)self;
+    resolve_binding_classes();
+    doc = f_parse_str(RSTRING_PTR(StringValue(xml)),
+                      (size_t)RSTRING_LEN(StringValue(xml)), NULL);
+    return doc ? build_binding_document(doc) : Qnil;
+}
+
+/* Fragment lane (TODO.perf/34): parse the markup against the
+ * document; returns the fragment's ADDRESS, or Qfalse when the
+ * parse fails (status is not surfaced — the caller re-runs the
+ * FFI path for the exact error). */
+static VALUE nf_parse_fragment_addr(VALUE self, VALUE document,
+                                    VALUE xml)
+{
+    void *frag;
+    int status;
+
+    (void)self;
+    resolve_binding_classes();
+    frag = f_parse_frag(RSTRING_PTR(StringValue(xml)),
+                        (size_t)RSTRING_LEN(StringValue(xml)),
+                        doc_ptr_of(document), &status);
+    return frag ? ULL2NUM((uint64_t)(uintptr_t)frag) : Qfalse;
+}
+
+/* One-shot markup append (TODO.perf/34): parse the markup, walk
+ * the fragment's children, append each to the parent — one
+ * readonly gate + version bump for the whole batch. Returns the
+ * appended count; -1 = parse failure; status codes surface as
+ * negatives (-1000 - st) for the caller's check_status path. */
+static VALUE nf_append_markup(VALUE self, VALUE document,
+                              VALUE parent_addr, VALUE xml)
+{
+    void *frag, *parent, *child, *next_child;
+    int status, count = 0;
+
+    (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");
+    frag = f_parse_frag(RSTRING_PTR(StringValue(xml)),
+                        (size_t)RSTRING_LEN(StringValue(xml)),
+                        doc_ptr_of(document), &status);
+    if (!frag)
+        return INT2FIX(-1);
+    parent = (void *)(uintptr_t)NUM2ULL(parent_addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    /* Appending DETACHES the child from the fragment — capture
+     * the next sibling before each move or the walk corrupts. */
+    for (child = f_first_child(frag); child != NULL; child = next_child) {
+        next_child = f_next_sibling(child);
+        status = f_append_child(parent, child);
+        if (status != 0)
+            return INT2FIX(-1000 - status);
+        count++;
+    }
+    return INT2FIX(count);
+}
+
 static VALUE nf_doc_handle_attach(VALUE self, VALUE document)
 {
     struct doc_handle *h;
@@ -2097,6 +2203,12 @@ void Init_native(void)
                               nf_copy_binding_element, 2);
     rb_define_module_function(m_native, "set_binding_root",
                               nf_set_binding_root, 2);
+    rb_define_module_function(m_native, "parse_binding_document",
+                              nf_parse_binding_document, 1);
+    rb_define_module_function(m_native, "parse_fragment_addr",
+                              nf_parse_fragment_addr, 2);
+    rb_define_module_function(m_native, "append_markup",
+                              nf_append_markup, 3);
     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.8"
+  VERSION = "1.9.174.9"
 end

data/lib/leptris/xml/document.rb

@@ -70,6 +70,15 @@ class Leptris::XML::Document
     # ParseOptions.new here would only discover flags==0 (#187 —
     # per-call overhead is most of a small-document parse).
     if options.nil? && !recover
+      # TODO.perf/35: parse + wrapper + lifetime handle in one C
+      # dispatch; failure raises through the shared path below.
+      if defined?(Leptris::XML::NATIVE_FAST)
+        doc = Leptris::XML::Native.parse_binding_document(xml)
+        raise Leptris::XML::ParseError,
+              "leptris_parse_string failed: " +
+              Leptris::XML::FFI.leptris_last_error.to_s if doc.nil?
+        return doc.tap { |d| d.readonly! if readonly }
+      end
       raw = Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, nil)
       if raw.null?
         raise Leptris::XML::ParseError,

data/lib/leptris/xml/document_fragment.rb

@@ -9,12 +9,32 @@ class Leptris::XML::DocumentFragment
 
   attr_reader :document, :c_ptr
 
-  def initialize(document, c_ptr)
+  def initialize(document, c_ptr, c_address: nil)
     @document = document
     @c_ptr = c_ptr
+    # TODO.perf/34: the address may arrive before any Pointer
+    # exists (the C parse face returns an Integer).
+    @c_address = c_address || c_ptr&.address
+  end
+
+  # Integer twin — reading it never materializes a Pointer.
+  def c_address
+    @c_address
+  end
+
+  def c_ptr
+    @c_ptr ||= ::FFI::Pointer.new(@c_address)
   end
 
   def self.parse(xml, document)
+    # TODO.perf/34: the C face answers the fragment address with
+    # no status MemoryPointer and no Pointer mint; failures fall
+    # back to the FFI pair for the exact error.
+    if defined?(Leptris::XML::NATIVE_FAST)
+      addr = Leptris::XML::Native.parse_fragment_addr(
+        document, xml.to_s)
+      return new(document, nil, c_address: addr) if addr != false
+    end
     raw, status = Leptris::XML::FFI.parse_fragment_with_status(
       xml.to_s, document.c_ptr)
     if raw.null?
@@ -25,6 +45,11 @@ class Leptris::XML::DocumentFragment
   end
 
   def children
+    # TODO.perf/34: one C pass (fragment nodes live in the
+    # document pool — the document's cache and version apply).
+    if defined?(Leptris::XML::NATIVE_FAST)
+      return Leptris::XML::Native.bulk_children(@document, @c_address)
+    end
     pointers, kinds = Leptris::XML::FFI.fetch_children(c_ptr)
     nodes = Array.new(pointers.size) do |i|
       Leptris::XML::Node.wrap(pointers[i], @document, node_type: kinds[i])

data/lib/leptris/xml/element.rb

@@ -555,6 +555,25 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
       node_or_markup
     when String
+      # TODO.perf/34: one dispatch parses the markup and appends
+      # every fragment child (single gate + bump). Negative
+      # returns: -1 re-runs the FFI path for the exact parse
+      # error; -1000-st routes through check_status.
+      if native_fast_children?
+        r = Leptris::XML::Native.append_markup(
+          @document, @c_address, node_or_markup)
+        if r.is_a?(Integer) && r >= 0
+          return Leptris::XML::NodeSet.new(@document, []) if r.zero?
+          return Leptris::XML::NodeSet.new(@document, last_added(r))
+        end
+        if r == -1
+          # parse failure: reproduce the exact error via the
+          # legacy path (it re-fails fast)
+          Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
+        else
+          Leptris::XML::FFI.check_status(-r - 1000)
+        end
+      end
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       added = []
       frag.children.each do |n|
@@ -567,6 +586,14 @@ class Leptris::XML::Element < Leptris::XML::Node
       raise ArgumentError, "add_child expects a Node or String, got #{node_or_markup.class}"
     end
   end
+  # The markup-append face appends in fragment order; the added
+  # nodes are this element's last +count+ children.
+  def last_added(count)
+    kids = children.to_a
+    kids.last(count)
+  end
+  private :last_added
+
   alias_method :<<, :add_child
 
   def namespace

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.8
+  version: 1.9.174.9
 platform: ruby
 authors:
 - Ribose Inc.
@@ -102,6 +102,8 @@ files:
 - TODO.perf/31-battery-rounds-4-8.md
 - TODO.perf/32-clean-host-floor-table.md
 - TODO.perf/33-cbound-root-set.md
+- TODO.perf/34-fragment-fast-lane.md
+- TODO.perf/35-parse-default-c-face.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md