leptris 1.9.280.0 → 1.9.280.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f047f95472eb2eb6a147568db650edcbdcbe77e8411004258ea6ea6df30d52c7
-  data.tar.gz: e634e41351c2f5889c70fc378c839342e91737b844ef91bd359e920205a4b5d4
+  metadata.gz: f8c9a359271bb60e62c4a6fb8e210c725d02b332df53f804411498c82acd1056
+  data.tar.gz: 5e196178a59975549b08e1c3b54c8d5377d463d430ad8bceef5df410a5ea4e83
 SHA512:
-  metadata.gz: b31e125da3457aedab626e6cc7762b2a04c25d68e5f3d8fa63250a7ba979e786686e810525cd39146aaf0a032b8638e42582619e4d5ffd0e1ad6481f9ca0b389
-  data.tar.gz: 1cf1e08be3e722f0d29fa4f278dc3513f9b11bf9c43e59c6d2bce5f33ee8dcd853b9e91cb2a92af7103f495884bc9dd6bd8d7bb174ae61812eb4233c67e4f13e
+  metadata.gz: f4bbbdb0079f57fb234636a4ec03000a44a67ac6f80ea852fc4ba3bac9c0faddce6231900f137c8c9596369f4ea552120be792670da103f5169f2d796c891a56
+  data.tar.gz: 6a96c92cba79412fd69d32bc33482cd8b208808ded2b7d554539f7322647a9c6852e1531342fd428f7fe5826a94ccbfc428e4d094faca3d251dcdb2bddfb6aec

data/CHANGELOG.md

@@ -1,3 +1,60 @@
+## [1.9.280.1] - 2026-09-30
+
+### Added
+
+- Ractor support (#ractor): documents can be parsed, queried,
+  mutated, and GC-freed inside child ractors, end to end. Five
+  blockers cleared:
+  - The native ext declares `rb_ext_ractor_safe(true)` — it keeps
+    no unsynchronized shared mutable state (class caches are
+    GC-marked immortals; wrapper hashes mutate only along the
+    engine's per-document path).
+  - The UTF8_STRING converter is a MODULE, not a
+    Class.new instance: the instance form deadlocks the first
+    mapped conversion inside a child Ractor; singleton methods
+    on a module dispatch cleanly.
+  - The legacy `UTF8_RETURNS` re-wrapper is gone. It redefined
+    every string-returning attach through a `method(name)`
+    capture (`define_singleton_method` with a Proc defined in
+    the loading ractor) — exactly the shape that raises
+    "defined with an un-shareable Proc in a different Ractor" in
+    a child. The UTF8_STRING converter already tags those 26
+    functions' results UTF-8 (a double no-op), so the wrapper
+    was deleted, not ported.
+  - windows-11-arm only: ffi attaches aarch64-mingw-ucrt
+    functions through un-shareable Proc wrappers (its libffi
+    #905 workaround), breaking every attached call from a child
+    Ractor there. `Leptris::XML::FFI` now freezes itself on that
+    platform — ffi's `Library#freeze` redefines the wrappers via
+    `FFI.shareable_proc` (verified by a full suite run with the
+    freeze forced on; it is a no-op elsewhere). ffi's freeze
+    redemption itself needs `Ractor.shareable_proc` (Ruby 3.5+),
+    so on that platform with older Rubies the ractor specs skip
+    — attached calls from child ractors are impossible there
+    until the runtime catches up.
+  - `Searchable`'s compiled-expression and CSS translation
+    caches moved from module ivars to `Ractor.current[]`-keyed
+    storage: the old shape raises `Ractor::IsolationError` from
+    non-main ractors, the compiled FFI handles could never
+    cross a boundary anyway, and in the main ractor the sharing
+    is unchanged (one cache across its threads). Engines without
+    Ractor keep the ivar.
+- Note for ractor users: a child ractor's autoload requests
+  are serviced by the main ractor, and a main blocked in
+  `Ractor#take` is not schedulable — under load that pairing can
+  wedge (CRuby ractor-barrier race). Exercise the API once in
+  the main ractor (or `Leptris::XML.parse` something trivial)
+  before spawning ractors against a cold load.
+
+### Performance
+
+- No measurable cost on the serial path: same attaches, same
+  converter, cache lookups trade one ivar read for a storage
+  read. Parallel parsing scales near-linearly instead — 4
+  ractors parse 4x20 documents in ~1/3 the serial time (0.06s
+  vs 0.18s on 4 cores).
+
+
 ## [1.9.279.0] - 2026-09-30
 
 ### Fixed

data/ext/leptris/native/native.c

@@ -2937,6 +2937,12 @@ LEPTRIS_INIT_EXPORT void Init_native(void)
 {
     VALUE m_leptris, m_xml, m_native;
 
+    /* Ractor support: this ext keeps no unsynchronized shared mutable
+     * state — class caches are GC-marked immortals (never freed), the
+     * per-document wrapper hashes are keyed by document and every
+     * entry mutates only under the engine's document path. */
+    rb_ext_ractor_safe(true);
+
     m_leptris = rb_define_module("Leptris");
     m_xml = rb_define_module_under(m_leptris, "XML");
     c_native_node = rb_define_class_under(m_xml, "NativeNode", rb_cObject);

data/lib/leptris/version.rb

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

data/lib/leptris/xml/ffi.rb

@@ -13,21 +13,30 @@ module Leptris
       # therefore uses this converter: same NUL-terminated copy
       # semantics as :string, tagged UTF-8. Input arguments keep
       # plain :string (Ruby-to-C reads bytes regardless of tag).
-      UTF8_STRING = Class.new do
-        include ::FFI::DataConverter
-
-        def from_native(ptr, _ctx)
+      # A MODULE, not a Class.new instance: the instance form
+      # (include DataConverter + tap) deadlocks the first mapped
+      # conversion inside a child Ractor, while singleton methods
+      # on a module dispatch cleanly (#ractor).
+      UTF8_STRING = Module.new do
+        extend ::FFI::DataConverter
+
+        def self.from_native(ptr, _ctx)
           return nil if ptr.null? || ptr.address.zero?
 
           ptr.read_string.force_encoding(Encoding::UTF_8)
         end
 
-        def to_native(value, _ctx)
+        def self.to_native(value, _ctx)
           return nil if value.nil?
 
           ::FFI::MemoryPointer.from_string(value.to_s)
         end
-      end.new.tap { |c| c.native_type(::FFI::Type::POINTER) }
+
+        def self.native_type(t = nil)
+          t ? (@native_type = t) : (@native_type ||= ::FFI::Type::POINTER)
+        end
+      end
+
 
       # The per-OS vendor directory of the ruby-platform gem
       # (zero-setup TruffleRuby/JRuby, #160): binaries for the
@@ -1392,40 +1401,6 @@ attach_function :leptris_parse_string,
       # XML_PARSE_DTDATTR opt-in parity.
       LEPTRIS_PARSE_DTDATTR = 2
 
-      # The headers' contract is UTF-8 for every C string, but FFI's
-      # read_string hands back ASCII-8BIT — the platform default
-      # leaks through the seam. Every string-returning attached
-      # function this binding CALLS is wrapped here so its result
-      # arrives as UTF-8; mirror-only attachments stay raw (add the
-      # name here when a call site starts using its string).
-      UTF8_RETURNS = %i[
-        leptris_version
-        leptris_status_string leptris_last_error
-        leptris_document_last_error leptris_document_encoding
-        leptris_document_pi_target leptris_document_pi_data
-        leptris_document_comment_content
-        leptris_element_name leptris_element_text leptris_element_prefix
-        leptris_element_namespace
-        leptris_element_attribute leptris_element_attribute_ns
-        leptris_attribute_get_name leptris_attribute_get_value
-        leptris_attribute_namespace_uri
-        leptris_element_namespace_decl_prefix
-        leptris_element_namespace_decl_uri
-        leptris_text_node_get_content leptris_comment_node_get_content
-        leptris_cdata_node_get_content
-        leptris_pi_node_get_target leptris_pi_node_get_data
-        leptris_pull_attr_name leptris_pull_attr_value
-      ].freeze
-      private_constant :UTF8_RETURNS
-
-      UTF8_RETURNS.each do |name|
-        raw = method(name)
-        define_singleton_method(name) do |*args|
-          str = raw.call(*args)
-          str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
-        end
-      end
-
       # Reads an libleptris-owned char* result and frees it as one unit,
       # so a call site can neither leak nor double-free.
       def self.read_owned_string(ptr)
@@ -1731,6 +1706,15 @@ attach_function :leptris_parse_string,
         end
         ptr
       end
+
+      # ffi attaches aarch64-mingw-ucrt functions through un-shareable
+      # Proc wrappers (the libffi #905 workaround in ffi/function.rb),
+      # which breaks every attached call from a child Ractor on
+      # windows-11-arm. Library#freeze redefines those wrappers via
+      # FFI.shareable_proc — the ffi gem's own Ractor redemption path
+      # for this platform (#ractor). Everything is attached above, at
+      # load time, so freezing closes no live door.
+      freeze if RUBY_PLATFORM == "aarch64-mingw-ucrt"
     end
   end
 end

data/lib/leptris/xml/searchable.rb

@@ -14,8 +14,20 @@ module Leptris::XML::Searchable
   # evaluations keep their dedicated string entries.
   COMPILED_CACHE_LIMIT = 64
 
+  # Cache storage (Ractor): module/class ivars are off-limits to
+  # non-main ractors (Ractor::IsolationError), and the compiled
+  # handles are FFI pointers that can never cross a ractor boundary
+  # anyway. Ractor#[] storage preserves the old sharing shape in
+  # the main ractor (one cache across its threads) and gives every
+  # child ractor its own. Engines without Ractor keep the ivar.
+  def self.cache_store(name)
+    return (@cache_stores ||= {})[name] ||= {} unless defined?(Ractor)
+
+    Ractor.current[name] ||= {}
+  end
+
   def self.compiled_expression(expr)
-    cache = (@compiled_expressions ||= {})
+    cache = cache_store(:compiled_expressions)
     if (hit = cache[expr])
       cache.delete(expr)
       cache[expr] = hit # LRU refresh
@@ -34,7 +46,7 @@ module Leptris::XML::Searchable
   # it every css call re-ran the regex machinery before the
   # compiled-expression cache could hit. Same bounded-LRU shape.
   def self.css_expression(selector, prefix)
-    cache = (@css_expressions ||= {})
+    cache = cache_store(:css_expressions)
     key = "#{prefix}#{selector}"
     if (hit = cache[key])
       cache.delete(key)

metadata

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