fast_regexp 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 806b011e667e08fc7b43faf6c2bbd9908e8ad44404e42b4a6cf92f3f48093437
-  data.tar.gz: 6d75b7c522f679843f3c2bb55323a56f84917ba7de8d71ae0863fc7865fbd2d4
+  metadata.gz: e6b732dadd490b380381133c5d755016c834952213d151d909ab3bd4dc0276d6
+  data.tar.gz: c03fa2c959dbd59b65fbafac9dd72fb537131bef777722d9a95d4ad10a6be191
 SHA512:
-  metadata.gz: a5104acf3940699cc3a11bd1919c935f24065ae6d60c7214afc16ec6de4fe7ae153136c4dff6e7fba0115fc3eb73fd988cdc0ef0d103100ec0f5e385909f14c5
-  data.tar.gz: d4854d8aaa0b91a1e0a0ec6ed6bfe5caf76be6cbbb3360d2c7e8548e8ad3d10958febe7b9b12ef1e6e2a37b6dbbfd0a78b9977fd9ecdf7eb96c1b3d47033d732
+  metadata.gz: 1b8b6c63c8af3d0d0863465fa35b75b9d9d64f20c817b5782e3ed40022ab03ff53a414cd22a5843b58a919ac17ce21f8479d3becadd38bebfdfa4cdd92e67014
+  data.tar.gz: 22f5d0a36706934cc3c1b7cf7eb9b8bfef8de839e09c80dba181cb3947fcd92ee2c1ae56f8494c4aa03c850e5e4af7ae656b5d05bea983e137742b58aaead745

data/Cargo.lock

@@ -72,6 +72,7 @@ name = "fast_regexp"
 version = "0.1.0"
 dependencies = [
  "magnus",
+ "rb-sys",
  "regex",
 ]
 

data/README.md

@@ -20,7 +20,7 @@ gem install fast_regexp
 ```
 
 Precompiled native gems are published for **arm64-darwin**, **x86_64-linux**,
-and **aarch64-linux** against Ruby **3.3**, **3.4**, and **4.0** — no Rust
+and **aarch64-linux** against Ruby **3.4** and **4.0** — no Rust
 toolchain required on those platforms.
 
 On any other platform/Ruby combo, Bundler/RubyGems falls back to the source
@@ -39,7 +39,7 @@ Regular expressions should be pre-compiled before use:
 
 ```ruby
 re = Fast::Regexp.new('p.t{2}ern*')
-# => #<Fast::Regexp:...>
+# => #<Fast::Regexp "p.t{2}ern*">
 ```
 
 > [!TIP]
@@ -101,6 +101,9 @@ Fast::Regexp.new('(\w+):(\d+)').scan("ruby:123, rust:456")
 # => [["ruby", "123"], ["rust", "456"]]
 ```
 
+Both `#scan` and `#scan_matches` run on either engine and return identical
+results, including on patterns that fell back to stdlib `::Regexp`.
+
 For per-match positions and pre/post-match access, use `#scan_matches`:
 
 ```ruby
@@ -216,13 +219,28 @@ Fast::Regexp::Set.new(["abc", "def"]).patterns
 
 ## Encoding
 
-Currently, `fast_regexp` expects the haystack to be an UTF-8 string.
+`fast_regexp` expects UTF-8 haystacks — ASCII-8BIT strings work too, and match
+results always come back tagged UTF-8. Matching runs over the raw bytes
+(rust/regex's `regex::bytes`), so searching a haystack that contains invalid
+UTF-8 doesn't raise, where stdlib raises `ArgumentError`:
+
+```ruby
+"abc\xFFdef" =~ /a(.)c/
+# => ArgumentError: invalid byte sequence in UTF-8
 
-It also supports parsing of strings with invalid UTF-8 characters by default. It's achieved via using `regex::bytes` instead of plain `regex` under the hood, so any byte sequence can be matched. The output match is encoded as UTF-8 string.
+Fast::Regexp.new('a(.)c').match("abc\xFFdef")
+# => #<Fast::Regexp::MatchData "abc">
+```
 
-In case unicode awarness of matchers should be disabled, both `Fast::Regexp` and `Fast::Regexp::Set` support `unicode: false` option:
+In the default Unicode-aware mode a `.` or character class won't match
+*across* an invalid byte. To match bytes anywhere, disable Unicode
+awareness — both `Fast::Regexp` and `Fast::Regexp::Set` accept `unicode:`
+(default `true`):
 
 ```ruby
+Fast::Regexp.new('c(.)d', unicode: false).match("abc\xFFdef").to_a
+# => ["c\xFFd", "\xFF"]
+
 Fast::Regexp.new('\w+').match('ю٤夏')[0]
 # => "ю٤夏"
 
@@ -236,26 +254,76 @@ Fast::Regexp::Set.new(['\w', '\d', '\s'], unicode: false).match("ю٤\u2000")
 # => []
 ```
 
+## Ractors
+
+Patterns, sets, and match results support `Ractor.make_shareable` — it
+returns the same object, now frozen. The native extension declares itself
+Ractor-safe at load time, so there is nothing to enable:
+
+```ruby
+re = Ractor.make_shareable(Fast::Regexp.new('(?P<word>\w+)=(?P<num>\d+)'))
+
+workers = Array.new(4) do
+  Ractor.new(re) do |pattern|
+    pattern.match("a=1 b=2")[:word]   # => "a"
+  end
+end
+workers.map { |r| r.respond_to?(:value) ? r.value : r.take }
+# => ["a", "a", "a", "a"]
+```
+
+Ruby 3.4 reads a Ractor's result with `#take`; Ruby 4.0 replaced it with
+`#value`. The `respond_to?` read above runs on both — the same idiom the
+spec suite uses.
+
+What is guaranteed (each point pinned by
+[`spec/fast_regexp/ractor_spec.rb`](spec/fast_regexp/ractor_spec.rb)):
+
+- A shared pattern is fully usable in every worker: `match`, `match?`,
+  `===`, `=~`, `scan`, `scan_matches`, and `sub`/`gsub` in template and
+  block form all work, with the same results as on the main Ractor.
+- Workers can `require "fast_regexp"` concurrently, including as the gem's
+  first load, and can construct their own patterns, matches, and sets —
+  the first construction of every native type works inside a non-main
+  Ractor.
+- Matches are frozen snapshots: the haystack is snapshotted at match time,
+  so mutating it afterwards and then running GC with compaction leaves a
+  shared match's data intact. `MatchData#string` returns that snapshot.
+- Stdlib-fallback patterns are shareable too, and substitute correctly
+  after being frozen or made shareable, without any warm-up call.
+
+Recipes: [Use fast_regexp inside Ractors](docs/how-to/use-in-ractors.md).
+Per-class details: the "Ractor safety" sections of
+[`Fast::Regexp`](docs/reference/fast-regexp.md),
+[`MatchData`](docs/reference/fast-regexp-matchdata.md), and
+[`Set`](docs/reference/fast-regexp-set.md).
+
 ## Documentation
 
 In-depth docs live under [`docs/`](docs/README.md), organized via the
 [Diátaxis](https://diataxis.fr/) framework:
 
 - **Tutorial:** [Getting started](docs/tutorials/getting-started.md)
-- **How-to:** [Migrate from stdlib `::Regexp`](docs/how-to/migrate-from-stdlib-regexp.md), [Handle unsupported syntax](docs/how-to/handle-unsupported-syntax.md)
+- **How-to:** [Migrate from stdlib `::Regexp`](docs/how-to/migrate-from-stdlib-regexp.md), [Handle unsupported syntax](docs/how-to/handle-unsupported-syntax.md), [Use fast_regexp inside Ractors](docs/how-to/use-in-ractors.md)
 - **Reference:** [`Fast::Regexp`](docs/reference/fast-regexp.md), [`MatchData`](docs/reference/fast-regexp-matchdata.md), [`Set`](docs/reference/fast-regexp-set.md)
 - **Explainers:** [Engine fallback](docs/explainers/engine-fallback.md), [Benchmarks](docs/explainers/benchmarks.md)
 
 ## Performance
 
-Matching runs 8–10x stdlib `::Regexp` on a hit or a miss, scanning 2–5x,
-`gsub` with a template 7–13x; reading a `MatchData` costs the same objects
-as `::MatchData`, and `match?`, `=~`, `===` and `Set#match?` allocate
-nothing. Compiling a pattern is the one place rust/regex is slower (it
-builds its automaton up front), so compile once and keep the object. Every
-operation, with the stdlib equivalent beside it, is on the
-[benchmarks page](docs/explainers/benchmarks.md); reproduce with
-`bundle exec ruby benchmark/operations.rb`.
+Measured with `bundle exec ruby benchmark/operations.rb` — one run on
+2026-11-05, Apple M4 Max, `ruby 4.0.9`, fast_regexp 0.9.0 (the full table is
+on the [benchmarks page](docs/explainers/benchmarks.md)):
+
+- `match?` runs 8–9x stdlib `::Regexp`, on a hit and on a 200 KB miss;
+  `scan` 2–5x; `gsub` with a template 7x on a 200 KB haystack — in one
+  object, where stdlib allocates a `String` per match. `Set#match?` over
+  four patterns is 2x a `Regexp.union`.
+- Reading a `MatchData` costs the same objects as `::MatchData`: each
+  accessor allocates exactly what it returns. `match?`, `=~`, `===` and
+  `Set#match?` allocate nothing.
+- Compiling a pattern is the one place rust/regex is slower: it builds its
+  automaton up front (~256 µs for a small pattern in that run, against
+  stdlib's ~1 µs), so compile once and keep the object.
 
 ## Development
 

data/ext/fast_regexp/Cargo.toml

@@ -8,4 +8,5 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = "0.8"
+rb-sys = "0.9"
 regex = "1"

data/ext/fast_regexp/src/lib.rs

@@ -1,19 +1,20 @@
 use magnus::{
     function, gc, method,
     scan_args::{get_kwargs, scan_args},
+    typed_data::Obj,
     value::{Opaque, ReprValue},
     DataTypeFunctions, Error, Integer, Module, Object, RArray, RClass, RHash, RString, Ruby,
     Symbol, TryConvert, TypedData, Value,
 };
 use regex::bytes::{NoExpand, Regex, RegexBuilder, RegexSet, RegexSetBuilder};
 use std::collections::HashMap;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 /// A haystack's bytes, read in place for the duration of one native call.
 ///
 /// Sound because the call hands nothing back to Ruby while the borrow lives:
-/// the GVL is held and no block is yielded, so no Ruby code can mutate the
-/// string, and a GC triggered by the result objects the call builds neither
+/// the current Ractor's GVL is held and no block is yielded; strings shared
+/// with other Ractors are frozen. A GC triggered by result objects neither
 /// frees nor moves it — a method argument is rooted and pinned on the VM
 /// stack for the whole call. Paths that *do* run Ruby code mid-call (the
 /// block forms of `sub`/`gsub`) read a frozen snapshot instead; see
@@ -42,61 +43,47 @@ struct RegexInner {
     regex: Regex,
     /// `name -> capture index`. Empty when the pattern has no named captures.
     names: HashMap<String, usize>,
-    /// Capture-group names in index order (`None` for unnamed groups).
-    name_index: Vec<Option<String>>,
-    /// `name_index` as one Ruby Array of interned frozen Strings (nil for
-    /// unnamed groups), so `names` and `named_captures` hand out the same
-    /// String objects on every call. Built on first use, from a method of a
-    /// live wrapper, so something marks it from the moment it exists; built
-    /// into the Array as each name is interned, because the interning table
-    /// holds its strings only weakly and a GC between two interns would
-    /// otherwise free the first. Marked by every wrapper holding this `Arc`.
-    ruby_names: OnceLock<Opaque<RArray>>,
+    /// Frozen Array of interned frozen Strings in capture order (nil for
+    /// unnamed groups). Built before publication so all Ruby state remains
+    /// immutable when the regex or a match is shared between Ractors.
+    ruby_names: Opaque<RArray>,
 }
 
 impl RegexInner {
-    fn from_pattern(pattern: &str, unicode: bool) -> Result<Self, Error> {
+    fn from_pattern(ruby: &Ruby, pattern: &str, unicode: bool) -> Result<Self, Error> {
         let regex = RegexBuilder::new(pattern)
             .unicode(unicode)
             .build()
             .map_err(|e| arg_error(e.to_string()))?;
 
         let mut names = HashMap::new();
-        let mut name_index = Vec::with_capacity(regex.captures_len());
+        let ruby_names = ruby.ary_new_capa(regex.captures_len());
         for (idx, name) in regex.capture_names().enumerate() {
-            name_index.push(name.map(|n| {
-                names.insert(n.to_owned(), idx);
-                n.to_owned()
-            }));
+            match name {
+                Some(name) => {
+                    names.insert(name.to_owned(), idx);
+                    // Root each interned string immediately: the interning
+                    // table holds it weakly, and the next push may run GC.
+                    ruby_names.push(ruby.str_new(name).to_interned_str())?;
+                }
+                None => ruby_names.push(())?,
+            }
         }
+        ruby_names.freeze();
 
         Ok(Self {
             regex,
             names,
-            name_index,
-            ruby_names: OnceLock::new(),
+            ruby_names: ruby_names.into(),
         })
     }
 
     fn mark(&self, marker: &gc::Marker) {
-        if let Some(names) = self.ruby_names.get() {
-            marker.mark(*names);
-        }
+        marker.mark(self.ruby_names);
     }
 
-    /// The interned names Array (see the field), built on first use.
     fn ruby_names(&self, ruby: &Ruby) -> RArray {
-        ruby.get_inner(*self.ruby_names.get_or_init(|| {
-            let names = ruby.ary_new_capa(self.name_index.len());
-            for name in &self.name_index {
-                let pushed = match name {
-                    Some(name) => names.push(ruby.str_new(name).to_interned_str()),
-                    None => names.push(()),
-                };
-                pushed.expect("pushing onto a fresh, unfrozen Array");
-            }
-            Opaque::from(names)
-        }))
+        ruby.get_inner(self.ruby_names)
     }
 
     /// Capture-group names in declaration order, unnamed groups skipped.
@@ -117,7 +104,13 @@ impl RegexInner {
 }
 
 #[derive(TypedData)]
-#[magnus(class = "Fast::Regexp::Native", free_immediately, size, mark)]
+#[magnus(
+    class = "Fast::Regexp::Native",
+    free_immediately,
+    size,
+    mark,
+    frozen_shareable
+)]
 pub struct FastRegexp(Arc<RegexInner>);
 
 impl DataTypeFunctions for FastRegexp {
@@ -127,7 +120,7 @@ impl DataTypeFunctions for FastRegexp {
 }
 
 impl FastRegexp {
-    pub fn new(args: &[Value]) -> Result<Self, Error> {
+    pub fn new(ruby: &Ruby, args: &[Value]) -> Result<Obj<Self>, Error> {
         let args = scan_args::<(String,), (), (), (), RHash, ()>(args)?;
         let kwargs = get_kwargs::<_, (), (Option<bool>,), ()>(args.keywords, &[], &["unicode"])?;
 
@@ -135,7 +128,12 @@ impl FastRegexp {
         let (unicode,) = kwargs.optional;
         let unicode = unicode.unwrap_or(true);
 
-        Ok(Self(Arc::new(RegexInner::from_pattern(&pattern, unicode)?)))
+        let inner = RegexInner::from_pattern(ruby, &pattern, unicode)?;
+        let names = inner.ruby_names(ruby);
+        let wrapped = ruby.obj_wrap(Self(Arc::new(inner)));
+        // Keep the Array rooted on this stack until the wrapper can mark it.
+        std::hint::black_box(names);
+        Ok(wrapped)
     }
 
     fn match_data(&self, haystack: RString, captures: Vec<CaptureOffset>) -> FastMatchData {
@@ -326,7 +324,8 @@ impl FastRegexp {
     class = "Fast::Regexp::Native::MatchData",
     free_immediately,
     size,
-    mark
+    mark,
+    frozen_shareable
 )]
 pub struct FastMatchData {
     haystack: Opaque<RString>,
@@ -518,7 +517,7 @@ impl FastMatchData {
     }
 }
 
-#[magnus::wrap(class = "Fast::Regexp::Set", free_immediately, size)]
+#[magnus::wrap(class = "Fast::Regexp::Set", free_immediately, size, frozen_shareable)]
 pub struct FastRegexpSet(RegexSet);
 
 impl FastRegexpSet {
@@ -553,6 +552,8 @@ impl FastRegexpSet {
 
 #[magnus::init]
 pub fn init(ruby: &Ruby) -> Result<(), Error> {
+    // All shared Rust state is Sync; retained Ruby objects are immutable.
+    unsafe { rb_sys::rb_ext_ractor_safe(true) };
     let object_class = ruby.class_object();
     // Fast::Regexp and Fast::Regexp::MatchData must already be defined by
     // lib/fast_regexp.rb before this extension is required — the Ruby façade
@@ -604,5 +605,11 @@ pub fn init(ruby: &Ruby) -> Result<(), Error> {
     regexp_set_class.define_method("match?", method!(FastRegexpSet::is_match, 1))?;
     regexp_set_class.define_method("patterns", method!(FastRegexpSet::patterns, 0))?;
 
+    // Magnus caches these classes and disables their allocators on first use.
+    // Complete that setup here, before workers can construct native objects.
+    FastRegexp::class(ruby);
+    FastMatchData::class(ruby);
+    FastRegexpSet::class(ruby);
+
     Ok(())
 }

data/lib/fast_regexp/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   class Regexp
-    VERSION = "0.8.0"
+    VERSION = "0.9.0"
   end
 end

data/lib/fast_regexp.rb

@@ -157,6 +157,10 @@ module Fast
       raise ArgumentError, "backend must be one of #{BACKENDS.inspect}" unless BACKENDS.include?(backend)
       @pattern = pattern
       @backend = compile_backend(pattern, original, backend, opts)
+      if stdlib?
+        # Prepare $N-to-name translation before the pattern can be frozen.
+        @stdlib_name_by_index = @backend.named_captures.flat_map { |n, idxs| idxs.map { |i| [i, n] } }.to_h.freeze
+      end
     end
 
     def fast? = @backend.is_a?(Native)
@@ -193,7 +197,9 @@ module Fast
     end
 
     def scan(haystack)
-      @backend.scan(coerce_string(haystack))
+      haystack = coerce_string(haystack)
+      return @backend.scan(haystack) if fast?
+      haystack.scan(@backend)
     end
 
     def scan_matches(haystack)
@@ -300,13 +306,6 @@ module Fast
       raise(fallback_from ? ArgumentError.new(fallback_from.message) : e)
     end
 
-    # Maps positional capture indices to names for the stdlib backend so we
-    # can translate `$N` to `\k<name>` (Ruby's gsub ignores `\N` for named
-    # groups). Only invoked from the stdlib path.
-    def stdlib_name_by_index
-      @stdlib_name_by_index ||= @backend.named_captures.flat_map { |n, idxs| idxs.map { |i| [i, n] } }.to_h
-    end
-
     # Translate rust/regex replacement syntax ($N, ${name}, $$) into Ruby
     # syntax (\N, \k<name>, $) for the stdlib fallback path.
     def stdlib_replacement(template, literal)
@@ -317,7 +316,7 @@ module Fast
         case token
         when "$" then "$"
         when /\A\d+\z/
-          name = stdlib_name_by_index[token.to_i]
+          name = @stdlib_name_by_index[token.to_i]
           name ? "\\k<#{name}>" : "\\#{token}"
         else "\\k<#{token[1..-2]}>"
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_regexp
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Eric Jacobs