Bug #22216: Special variables (ex. Regexp backref and IO lastline) are thread-unsafe in some cases, incompatible with Ractor

• Status: Open
• Assignee: -
• Target version: -
• Backport: 3.3: UNKNOWN, 3.4: UNKNOWN, 4.0: UNKNOWN

[headius (Charles Nutter)]

Problem

Several Regexp-matching methods currently write (and sometimes read) the implicit "backref" $~ variable in the local frame (and related variables like $').

Several IO methods read or write the "last line" $_ variable in the same way.

In both cases, the result is a mutable object, which makes these variables already problematic for ractors.

Making matters worse, the frame might be shared if a proc is captured and used across threads or ractors, and there's no static way to inspect a piece of code to know if it expects to read or write these variables. Where procs can be rejected by a proc for accessing captured state, there's no such check possible for these variables.

All of these facts make the backref and lastline variables fundamentally incompatible with Ractor.

Possible remedies

A wholesale removal of these variables would solve the problem, but there's a lot of code that depends on them... much of that code without even realizing it, since they might not access the variables directly. In some cases, the dependencies are internal and part of the behavior of core methods.

Hard errors when using methods that read or write these variables would avoid introducing threading problems into a Ractor, but would also break a large number of commonly-used methods.

There have been experiments to make these variables both frame and thread-local, but they have never been made standard. Updates to backref and lastline are visible across threads and already can lead to concurrency issues even on CRuby.

Deprecating the implicit behavior and making it opt-in (or opt-out?), perhaps with keyword arguments or file pragmas, might be a halfway measure. It would probably not be an easy transition.

I don't know the right path forward, but I believe this issue needs to be discussed.

JRuby perspective

We continue to mimic CRuby behavior, which has led to our users occasionally running into issues when a proc accesses these variables across threads. Our recommendation: "don't do that".

We also have had our frustrations optimizing around these variables, since they implicitly require access across calls. Because we cannot statically detect when they will be used, we essentially treat all method names that might potentially access them as deopt triggers. It's not ideal.

I'd like to hear ideas for how to make these variables less "magic", less implicit and easier to deal with across calls (and across threads/ractors).

[byroot (Jean Boussier)]

Updates to backref and lastline are visible across threads and already can lead to concurrency issues even on CRuby.

I've always considered this a bug. If possible they should definitely be scoped to the current thread (or rather fiber?).

Because we cannot statically detect when they will be used

I would also love if we could statically know when they're used or not.

One of my pet peeves is that case str; when /foo/, is noticeably slower because Regexp#=== has to create a MatchData which is very often useless.

Please correct me if I'm wrong, but the only thing that prevent such static analysis is eval right? I've had a bunch of discussion over the years about how we could take inspiration of JavaScript, and nerf eval if it is aliased, which would allow to statically detect eval usage and only deoptimize these methods.

Such nerfed eval wouldn't have accept to $ special variables, allowing to statically analyze whether they need to be computed and set in the first place.

But there might be some considerations I'm missing here.

[headius (Charles Nutter)]

I've always considered this a bug. If possible they should definitely be scoped to the current thread (or rather fiber?).

I prototyped this for JRuby some years ago, and I believe Rubinius (and perhaps TruffleRuby) implemented it this way. For JRuby we opted not to ship that behavior because it could be very visible, and there could be cases where someone expects to simply read a previously set $~ or $_. We err on the side of matching CRuby.

It's definitely doable, though.

Please correct me if I'm wrong, but the only thing that prevent such static analysis is eval right?

Well, that and the fact that you don't know if you're calling the #[]= method on a String or a Hash when you pass in a Regexp, or if the gsub you're calling is the core method that requires special frame storage.

Statically analyzing offline is probably doable, but at runtime we don't have any guarantees of what method we're actually calling.

JIT can do this at runtime, but then also needs to be able to deopt if someone throws a new type in.

nerf eval if it is aliased, which would allow to statically detect eval usage

JRuby takes a more conservative approach: we warn if you alias method names known to require access to the caller's frame.

$ jruby -w -e 'class Foo; alias my_eval eval; end'
-e:1: warning: Foo#eval accesses caller method's state and should not be aliased

If you do proceed with such an alias and then make calls to the aliased eval, you'll get unexpected results since we can no longer detect it's "THE eval".

Nerfing it is an interesting strategy, though. We could implement that by replacing the aliased eval with the nerfed version, so it would still function but only have access to its own new frame.

FWIW we do this for all methods that have such "special" behavior.

$ jruby -w -e 'class Foo < String; alias blah gsub; end'
-e:1: warning: Foo#gsub accesses caller method's state and should not be aliased

They could be similarly "nerfed" as an alternative.

Generally people don't alias these methods, because usually aliasing is done along with wrapping, which breaks access to the caller's frame anyway.

But the problem still stands: you can't know just by looking at Ruby code (sans type hints or JIT profiles) whether a given method might access the caller's frame in "special" ways.

[byroot (Jean Boussier)]

But the problem still stands: you can't know just by looking at Ruby code (sans type hints or JIT profiles) whether a given method might access the caller's frame in "special" ways.

I don't want to derail the discussion too much, but in short my idea was the opposite.

At least in MRI, if we ignore eval it's easy to know if a method access these special variables (getspecial instruction), so we could have a call info flag that tells whether the caller access any sort of "special" variables. Methods like Regexp#=== could then read the call info and skip updating these variables.

[headius (Charles Nutter)]

it's easy to know if a method access these special variables (getspecial instruction),

That is not sufficient. There are methods that read and write these special variables without the user ever accessing the literal globals.

You can look in the JRuby codebase to see where we have marked up core methods with metadata indicating they either read or write one of these variables. A few of them do both, in which case you must prepare that frame storage just in case.

Example: https://github.com/jruby/jruby/blob/master/core/src/main/java/org/jruby/RubyIO.java#L1897

Our list may not be exhaustive.

And then there's Kernel#send and related calls which are also supposed to be able to access the callers frame, including these implicit variables.

[headius (Charles Nutter)]

Oh, it's also worth pointing out that there are Regexp method equivalents of each of the special backref variables (last_match etc). They are less commonly used, I believe, and usually called directly on Regexp, but that's another example that can access the implicit variable without being ethically detectable.

[headius (Charles Nutter)]

ethically detectable

statically detectable

[ko1 (Koichi Sasada)]

I agree that the current behavior is a Ractor bug. In fact, this is one of the blockers preventing us from removing the "experimental" warning from Ractor. These variables should be thread-local.

The main implementation challenge is how to manage the lifetimes of Procs and Threads.

I use the term “svar” (short for “special variables”), following CRuby's implementation terminology.

(1) If we manage per-thread svars in each Proc or binding, we need a dictionary (or a list) for each Proc:

$~ = ...
# Conceptually compiled into:
binding.svar[current_thread].$~ = ...

(2) If we manage per-thread svars in each Thread, we need a dictionary for each Thread:

$~ = ...
# Conceptually compiled into:
Thread.current.svar[binding_or_proc].$~ = ...

In either case, we need to manage the lifetimes of the dictionary keys and values, which seems complicated. I am also not sure which approach would allow for a more efficient implementation.

If we assume that this is a rare case, option (1) may be acceptable, and we could leave stale dictionary keys behind when threads terminate.

[Eregon (Benoit Daloze)]

TruffleRuby already make these always thread-local, and there has been 0 compatibility issue reported about that.

It's basically option (1) mentioned by @ko1 (Koichi Sasada), i.e. a dictionary/ThreadLocal object on the frame, but with the optimization that if only 1 Thread has written to it then we have a direct field for the value:
https://github.com/truffleruby/truffleruby/blob/33598a0447c4cd0b56eb56b80e81b094ea5bf74a/src/main/java/org/truffleruby/language/threadlocal/ThreadAndFrameLocalStorage.java
(used here)

[Eregon (Benoit Daloze)]

To give a bit more details, TruffleRuby then always reserves one slot in the frame for svar's, and lazily allocate the storage for them on first access:
https://github.com/truffleruby/truffleruby/blob/33598a0447c4cd0b56eb56b80e81b094ea5bf74a/src/main/java/org/truffleruby/language/threadlocal/SpecialVariableStorage.java#L34-L38

[Eregon (Benoit Daloze)]

in each Proc or binding

A small precision here which might be helpful is svars are only stored on method frames, never on block frames. So it's per method frame and Proc are unaffected (they just access the encapsulating method frame's svars).

[jhawthorn (John Hawthorn)]

I've wanted to fix this for a while. We should do what TruffleRuby does and others have described. Of the options ko1 proposed, I think with both these tables need to hold weak references (making them essentially the same thing) otherwise we risk leaking Thread objects (in option 1) or methods/environments (option 2). If they are weak references, it's probably easier to do option 2 since that won't require synchronization on the table.

One question Jean posed that I don't see discussion about is whether this should be Thread-local or Fiber-local. My gut instinct was to prefer Fiber-local, but I think it will cause incompatibilities via Enumerator.new or ex. gsub with no block.

[Eregon (Benoit Daloze)]

jhawthorn (John Hawthorn) wrote in #note-11:

One question Jean posed that I don't see discussion about is whether this should be Thread-local or Fiber-local. My gut instinct was to prefer Fiber-local, but I think it will cause incompatibilities via Enumerator.new or ex. gsub with no block.

I think it should be Fiber-local, otherwise $~ and friends might be set unexpectedly after a Fiber switch, especially with a Fiber scheduler which might transfer/resume/yield in non-obvious places.

TruffleRuby uses a Fiber local (specifically a java.lang.ThreadLocal and since Fibers have their own Java Thread those are the same thing).

[jhawthorn (John Hawthorn)]

I think I'm somewhat sold on it being Fiber-local. There may be some incompatibilities, but the existing behaviour is already strange.

Here's the first case I was worried about. If you get an Enumerator with lazy or an iterating method without a block, $1 will change in the calling method.

$ ruby -ve 'g = "hello".gsub(/(.)/); g.next; p $1'
ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [arm64-darwin25]
"h"

$ ruby -ve 'g = "hello".gsub(/(.)/); g.next; p $1'
truffleruby 33.0.1 (2026-01-20), like ruby 3.3.7, Oracle GraalVM Native [arm64-darwin23]
nil

However Ruby 4.0 behaves a bit strange with this once we move the test code into a method

$ ruby -ve 'def t; g = "hello".gsub(/(.)/); g.next; p $1; end; t'
ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [arm64-darwin25]
nil

However, I think this is a bug (one I spotted elsewhere through another path and had already intended on fixing). We can change the behaviour by making the block escape before making the enumerator (the implementation issue is that the ifunc's svar_lep is stale, pointing to the stack rather than the escaped env on the heap).

$ ruby -ve 'def t; proc{}; g = "hello".gsub(/(.)/); g.next; p $1; end; t'
ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [arm64-darwin25]
"h"

Since this is already inconsistent, that seems like an opportunity to make the switch to Fiber local?

Here's a less broken case on CRuby that has different behaviour on truffle (avoids an ifunc so doesn't have the same issue). I could see someone actually writing this and shows a compatibility issue we might face:

def report
  access_log = [
    %{127.0.0.1 - - [04/Aug/2026:10:00:00 -0700] "GET /index.html HTTP/1.1" 200 1043},
    %{10.2.3.4 - - [04/Aug/2026:10:00:01 -0700] "POST /login HTTP/1.1" 302 0},
  ]

  e = access_log.lazy.select { |line| line =~ /"(\w+) (\S+) HTTP/ }
  loop do
    e.next
    puts "#{$1} #{$2}"
  end
end
report

$ ruby -v svar_access_log3.rb
ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [arm64-darwin25]
GET /index.html
POST /login

$ ruby -v svar_access_log3.rb
truffleruby 33.0.1 (2026-01-20), like ruby 3.3.7, Oracle GraalVM Native [arm64-darwin23]

[jhawthorn (John Hawthorn)]

I've started prototyping this in https://github.com/ruby/ruby/pull/18200 (needs testing and benchmarking still)

[jhawthorn (John Hawthorn)]

• Subject changed from Regexp backref and IO lastline are incompatible with Ractor to Special variables (ex. Regexp backref and IO lastline) are thread-unsafe in same cases, incompatible with Ractor

Just a note on the Ractor-incompatibility, I think that's actually a much smaller problem. We should only hit that via Ractor.shareable_proc, which is a point we can set svar as we want (or is a flag we could check for). We could fix this just for ractors easily, but I think we want to improve that for Threads (and hopefully Fibers) at the same time so changing the title to reflect that.

[jhawthorn (John Hawthorn)]

• Subject changed from Special variables (ex. Regexp backref and IO lastline) are thread-unsafe in same cases, incompatible with Ractor to Special variables (ex. Regexp backref and IO lastline) are thread-unsafe in some cases, incompatible with Ractor

[jhawthorn (John Hawthorn)]

Here's an example I think folks would expect to be thread safe, but fails on current CRuby after just a few iterations (thanks to the Thread.pass)

def test_it
  proc { |str|
    str =~ /(.)(.)(.)/
    Thread.pass # Comment this out to make it pass (usually)
    ret = [$1, $2, $3]
    ret
  }
end

def assert_equal(a, b)
  raise "#{a.inspect} != #{b.inspect}" unless a == b
end

test = test_it()
th = []
th << Thread.new do
  1000.times { assert_equal test.call("abc"), %w[a b c] }
end
th << Thread.new do
  1000.times { assert_equal test.call("123"), %w[1 2 3] }
end
th.each(&:join)

[matz (Yukihiro Matsumoto)]

I agree with the direction, and I agree these should be Fiber-local.

What I am not ready to decide is the rule for cases like the one in #note-13. Reading $1 after e.next is code people actually write, and I would rather not break it. I want a rule that keeps it working, not an exception list.

One idea to consider: a fiber inherits its parent's storage, except non-blocking fibers, which get their own. Sibling fibers under a scheduler are where the visibility problem in #note-12 actually is. A plain Fiber.new resumed by its parent does not run concurrently with it, so sharing there is safe and matches today's behavior.

What do you think of that?

Also, please settle the stale svar_lep bug in #note-13 first. Until that is fixed we do not have a stable baseline to compare against.

Matz.

[Eregon (Benoit Daloze)]

matz (Yukihiro Matsumoto) wrote in #note-18:

Reading $1 after e.next is code people actually write

Given that does not work on Ruby 4.0 (3rd snippet of #note-13) and there has been no bug report about that, it seems a strong indication people don't use such code.

I think simplicity is best, inheriting storage between Fibers would add lots of complexity and make it much harder to understand the model semantically.
That last part is not just to be nice, everyone has been confused for years with the existing semantics for svars, I think it's a great time to clean them up and just be Fiber-local + method-frame-local.

[headius (Charles Nutter)]

Popping back in to say I support the Fiber-isolated direction here but don't have strong opinions about the potential breaking cases. I've disliked supporting these variables for years so anything we can do to limit their scope is ok by me.

inheriting storage between Fibers would add lots of complexity

If this is not already a pattern for other Fiber state, I agree it would be unnecessary complexity.