moxml 0.5.23 → 0.5.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c88f88d6ab8eafea4b11c8007e7b667e1413bfc60715142ef280af00c1909de
-  data.tar.gz: 8302e755e10fa582f9349c443fc91ed63ddd684ce24c45f0baedd88f0541c16f
+  metadata.gz: 7962623114db23fce306ee38745c51ccf85fe8333c60a274322eb3d5a6dd6270
+  data.tar.gz: 00b614eed4a674d4ad43a1cbf1f4dd0483de2e929b7e78728c4aab7106662b56
 SHA512:
-  metadata.gz: b7067b38f81a13bd29e1c542f66bd99636f594f91a754997744419549e259c0267a69daea3ab147410e425f243e9ddc807441860df8d91f00644b93f5608fd2e
-  data.tar.gz: 662df0f63b4600b923eeedf4747b04bbd71a3a0cd732d25f2ca4fccaf6b563b710f09d8fd470497434962aa024c1e9354f718ebd8b793649a4aa06033149852b
+  metadata.gz: 9e49d1c70a4332def347256eccf22f7defa256eaec8290987a73079daa0bcfed0f141f4862a9b457fbbc6f606be5386c3d5717e35e767b1088d2e7f88e0fde5d
+  data.tar.gz: d3ad61616f0b7bf163fef6333c59595bbce7b40dc96fd01c7a64f8bf2e8db2419102f3633444d1a54453bff7f6ad170051f75c9756e1c406233e25716426f3c7

data/.github/workflows/rake.yml

@@ -54,7 +54,8 @@ jobs:
       - name: Run rubocop
         run: bundle exec rubocop
 
-      - name: Run performance gates
+      - name: Run performance gates (YJIT)
         env:
           RUN_PERFORMANCE: "1"
+          RUBY_YJIT_ENABLE: "1"
         run: bundle exec rake spec:performance

data/docs/_pages/performance.adoc

@@ -33,3 +33,34 @@ doc.xpath('//title')
 root.xpath('./*/title')
 ----
 
+
+=== Run with YJIT
+
+The wrapper layer is Ruby-dispatch-heavy — exactly what YJIT compiles
+well. Enable it for any throughput-sensitive workload (Ruby >= 3.3;
+production-ready since then):
+
+[source,bash]
+----
+RUBY_YJIT_ENABLE=1 ruby your_app.rb   # or: ruby --yjit
+----
+
+Measured against raw engine calls on a 52KB fixture (leptris,
+min-of-N, 100 warm reads): without YJIT the facade adds +23% on tree
+walks and +43% on warm attribute reads; **with YJIT those become
+-12% (faster than the binding's own walk) and +10%**, and `.name`
+reads reach parity. Parse, serialize and duplicate are C-bound
+either way. No semantic surface changes — it is a runtime flag.
+
+Consumers on CRuby 3.3+ (canon's pretty-print pipeline, batch
+conversion) should treat it as the default; moxml's own CI
+performance gates run with YJIT enabled.
+
+=== Prefer bulk paths for per-node conversion
+
+Per-node Ruby iteration pays the wrapper tax per element. When the
+goal is conversion rather than manipulation, the bulk paths move the
+loop into C: `materialize_fields` streams the flattened record
+fields from one C call and measures faster than an equivalent
+raw-Nokogiri DOM walk. See
+link:conversion-apis[Conversion and memory lifecycle APIs].

data/lib/moxml/attribute.rb

@@ -10,6 +10,7 @@ module Moxml
       # Mutation return contract (Adapter::Base): returns the native
       # to keep tracking — same object for in-place adapters, fresh
       # object for value-object adapters (leptris).
+      context.bump_namespace_scope_generation
       @native = adapter.set_attribute_name(@native, new_name)
     end
 
@@ -32,6 +33,7 @@ module Moxml
     end
 
     def value=(new_value)
+      context.bump_namespace_scope_generation
       adapter.set_attribute_value(@native, new_value)
     end
 

data/lib/moxml/element.rb

@@ -3,10 +3,14 @@
 module Moxml
   class Element < Node
     def name
-      adapter.node_name(@native)
+      # The adapter read is an FFI call plus (on several adapters) a
+      # defensive string copy; names only change through name= and
+      # native adoption, both of which clear this.
+      @name ||= adapter.node_name(@native)
     end
 
     def name=(value)
+      @name = nil
       adapter.set_node_name(@native, value)
     end
 
@@ -42,6 +46,7 @@ module Moxml
     # attributes only; prefixed names replace by namespace URI and
     # require a declared prefix. Cache coherence is the resolver's.
     def []=(name, value)
+      context.bump_namespace_scope_generation
       Moxml::AttributeResolver.assign(self, name, normalize_xml_value(value))
     end
 
@@ -49,13 +54,30 @@ module Moxml
     # bare names match only no-namespace attributes; prefixed names
     # resolve through in-scope declarations to expanded names.
     def [](name)
-      Moxml::AttributeResolver.resolve(self, name)&.value
+      cache = attribute_read_cache
+      key = name.to_s
+      unless cache.key?(key)
+        cache[key] = Moxml::AttributeResolver.resolve(self, key)
+      end
+      cache[key]&.value
     end
 
     def attribute(name)
       Moxml::AttributeResolver.resolve(self, name)
     end
 
+    # Resolution reads the element.s in-scope namespaces, so the
+    # cache rides the context.s namespace-scope generation clock —
+    # every attribute or namespace mutation anywhere bumps it.
+    def attribute_read_cache
+      generation = context.namespace_scope_generation
+      if @attribute_cache_generation != generation
+        @attribute_cache = {}
+        @attribute_cache_generation = generation
+      end
+      @attribute_cache
+    end
+
     # Returns attribute value by name (used by XPath engine)
     def get(attr_name)
       self[attr_name]
@@ -70,6 +92,7 @@ module Moxml
     end
 
     def remove_attribute(name)
+      context.bump_namespace_scope_generation
       Moxml::AttributeResolver.remove(self, name)
       self
     end
@@ -223,9 +246,13 @@ module Moxml
       children
     end
 
-    # Called by Attribute#remove to invalidate the cached attributes
+    # Called by Attribute#remove and the attribute mutators. Clears
+    # the attribute list and the resolved-read cache, and bumps the
+    # context generation so cross-wrapper reads recompute.
     def invalidate_attribute_cache!
       @attributes = nil
+      @attribute_cache = nil
+      context.bump_namespace_scope_generation
     end
 
     # Clear the namespace caches and bump the context's scope

data/lib/moxml/entity.rb

@@ -49,6 +49,34 @@ module Moxml
     # marker gsub's full-buffer copy entirely.
     NON_STANDARD_ENTITY_RE = /&(?!amp;|lt;|gt;|quot;|apos;)(#{NAME_PATTERN});/
 
+    # True when a NON-standard named entity exists somewhere (the
+    # gsub would then be needed). The leptris binding's C probe
+    # (leptris-ruby#124) answers in one pass at memcmp speed; it is
+    # resolved lazily because adapters load on demand. Otherwise:
+    # the cheap `&` pre-filter, then the Ruby regex.
+    def nonstandard_entity?(str)
+      probe = c_entity_probe
+      if probe
+        probe.call(str, str.bytesize) == 1
+      else
+        str.include?("&") && str.match?(NON_STANDARD_ENTITY_RE)
+      end
+    end
+
+    def c_entity_probe
+      if @c_entity_probe.nil?
+        @c_entity_probe =
+          if defined?(::Leptris::XML::FFI) &&
+              ::Leptris::XML::FFI.respond_to?(:leptris_str_has_nonstandard_entity)
+            ::Leptris::XML::FFI.method(:leptris_str_has_nonstandard_entity)
+          else
+            false
+          end
+      end
+      @c_entity_probe || nil
+    end
+    module_function :nonstandard_entity?, :c_entity_probe
+
     NAMED_DECODE_MAP = {
       "amp" => "&", "lt" => "<", "gt" => ">",
       "quot" => '"', "apos" => "'"
@@ -87,11 +115,12 @@ module Moxml
       # Fast path: no `&` means no entity references to mark — skip
       # the regex scan and string allocation entirely. The vast
       # majority of XML payloads contain no entity references.
-      return [str, false] unless str.include?("&")
       # Second fast path: only predefined entities — the gsub would
       # pass every match through unchanged, so skip its full-buffer
-      # copy too.
-      return [str, false] unless str.match?(NON_STANDARD_ENTITY_RE)
+      # copy too. When the leptris binding is loaded, its C probe
+      # (leptris-ruby#124) answers in one memcmp-class pass; the
+      # binding loads lazily, so the probe is resolved on first use.
+      return [str, false] unless nonstandard_entity?(str)
 
       marked = false
       processed = str.gsub(NAME_RE) do |match|

data/lib/moxml/node.rb

@@ -25,10 +25,18 @@ module Moxml
         context.unregister_wrapper(@native)
         @native = new_native
         context.register_wrapper(new_native, self)
+        clear_native_memo!
       end
       self
     end
 
+    # Wrapper-local memos derived from the native (name, attribute
+    # reads) die with the native they were computed from.
+    def clear_native_memo!
+      @name = nil
+      @attribute_cache = nil
+    end
+
     def document
       Document.wrap(adapter.document(@native), context)
     end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.23"
+  VERSION = "0.5.25"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.23
+  version: 0.5.25
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API