Making special variables less special in TruffleRuby

The most important thing we're going to need is a way to define variables with custom behaviour from Ruby. There's a function in MRI's C API which allows this, rb_define_hooked_variable, and several macros and other variants that use that. Since we support those function we already had the capability, but we do need to expose it in a nice way. We don't want to add methods to existing classes that might cause clashes so we tend to put things like this into modules under the Truffle name space. We are also going to want to define a lot of read only variables, so it's probably a good idea to make a method for that as well. In TruffleRuby you'll find these methods in Truffle::KernelOperations, but for brevity we'll just put them under Truffle here.

module Truffle
  def self.define_hooked_variable(name, getter, setter, defined = proc { 'global-variable' })
    # Work is done in here.
  end

  def self.define_read_only_global(name, getter)
    setter = -> _ { raise NameError, "#{name} is a read-only variable." }
    define_hooked_variable(name, getter, setter)
  end
end

This method is going to take the name of a variable to be defined, procedures for getting and setting the value, and an optional procedure to be used for defined? $my_variable. If you've never used defined? in Ruby it's a little special. It returns the semantic meaning of the expression that follows it. Simple expressions will just return 'expression', method names will return 'method', and so on. If you try defined? $var then you will get 'global-variable' if $var has been assigned to or nil if it hasn't. Some of Ruby's special variables have more complex behaviour so we need to be able to provide a procedure for that.

Let's see this in action by defining our own hooked variable.

x = nil
Truffle.define_hooked_variable(
  :$my_var,
  -> { x },
  -> v { puts "Setting $my_var to #{v}.",
         x = v })

Now if you try doing $my_var = "something" you'll see a message saying Setting $my_var to something. You should also be able to get back the value you stored by doing $my_var. Now we know this works let's see if we can define some of the simple special variables.

Several special variables are connected to ARGF, they link to properties on that object but can't be written to themselves.

Truffle.define_read_only_global :$<, -> { ARGF }
Truffle.define_read_only_global :$FILENAME, -> { ARGF.filename }

There's also $* which holds the arguments not consumed by the Ruby implementation itself.

Truffle.define_read_only_global :$*, -> { ARGV }

Finally we'll look at $.. This is set by various methods on ARGF and file objects, but it's not actually ARGF.lineno since updating it doesn't actually change that value. Instead we hold it on another instance variable on ARGF like this:

Truffle.define_hooked_variable(
  :$.,
  -> { ARGF.instance_variable_get(:@last_lineno) },
  -> value { value = Truffle::Type.coerce_to value, Fixnum, :to_int
             ARGF.instance_variable_set(:@last_lineno, value) } )

Quite a few variables allow writes to them, but include some extra checks. At first glance, it appears we could simply represent these constraints with a lambda. While this is a nice, clear solution in Ruby, it unfortunately complicates parts of the TruffleRuby runtime written in Java. To help keep things simple for both the Ruby and Java parts of the runtime, we've added Truffle.global_variable_get and Truffle.global_variable_set. and we can then use them like this:

Truffle.define_hooked_variable(
  :$stdout,
  -> { Truffle.global_variable_get(:$stdout) },
  -> v { raise TypeError, "$stdout must have a write method #{v.class} given." unless v.respond_to?(:write)
         Truffle.global_variable_set(:$stdout, v) })

alias $> $stdout

There's a few more like this, and I won't go through them all, but they can all be done as nice simple Ruby.

All the variables I've mentioned so far have a few things in common. They have relatively simple semantics, and they aren't used that that often, or aren't likely to be a real performance bottleneck. But later on we're going to look at some that are used much more heavily and are more complex to implement, so let's talk about what will optimise now.

Next up the difficulty ladder are variables which are local to a thread. To implement $SAFE we'll need a way to return the value for the current thread when it is read and written, as well as checking any new value is valid. This value must not be visible in the normal fiber local variables accessed using Thread#[] or the thread locals accessed from Thread#thread_variable_get, so we'll need something on Truffle::ThreadOperations to do that job.

Truffle.define_hooked_variable(
  :$SAFE,
  -> { Truffle::ThreadOperations.get_thread_local(:$SAFE) },
  -> value { value = Truffle::Type.check_safe_level(value)
             Truffle::ThreadOperations.set_thread_local(:$SAFE, value) }
)

The only new thing we have here is the ability to get or set a value on the current thread. You might assume those methods have to be written in Java, but they're written in Ruby as well. The get method looks something like

def self.get_thread_local(key)
  locals = thread_get_locals(Thread.current)
  object_ivar_get(locals, key)
end

The values local to a thread are stored as a normal object with instance variables, and we could have used Kernel#instance_variable_get on locals, except :$SAFE isn't a valid name for an instance variable in Ruby.

Everything here can be optimised in the same way I described above. Accessing instance variables is extremely fast as long as the owning object always has the same set of variables, and so as long as the key stays constant it will just be a field access in an object. Thread.current will be constant if you only use a single thread, and getting the thread locals is just like getting an instance variable. In reality you'll probably be using more than one thread, but it should still optimise well if the method is copied for each call site.

There's only a few other thread local variables, $! which holds the last raised exception, $? which holds the return code of the last child process, and $@ which is just an alias for $!.backtrace. The remaining ones I want to talk about are all connected with regular expressions, and they are even more complex and subtle.

$~ is more complex than you might realise. It holds the value of the last regular expression match done in a variety of ways, and hence is thread local. But more than that it is also frame local. What do I mean by that? Well, try this code in irb and see what you get.

def a(str)
  /foo/ =~ str
  $~
end

def b(str)
  a(str)
  $~
end

a("There is a foo in this string")
b("There is a foo in this string")

The call to a will return a MatchData object, but the call to b will return nil. Even setting $~ in a won't affect the value we see in b. It's pretty useful because no library call you make can unexpectedly change the value of $~ that you might be relying on, but it is going to make our job implementing it harder.

Let's check global variable reads and hooked variable reads are still good and fast. If you're wondering why I'm not testing writes it's because they must introduce a full memory fence so the result can be seen by other threads (see the global variables section in the proposed Ruby memory model for details), and that really dominates. Let's try a simple benchmark like

$var = 1
def simple_count
  total = 0
  10000.times do
    total += $var
  end
  total
end

We'll run the benchmark on MRI, JRuby, and TruffleRubby, and we'll also run it on TruffleRuby with $var defined as a hooked variable. We do see some noise in these benchmarks and it take a few seconds for TruffleRuby and JRuby's JITs to kick in, so I allow the benchmarks to run for a few seconds and then took the average iterations per second of this peak performance. All numbers have been rounded to two siginificant figures.

What does this really tell us? Well, it tells us that we've worked out $var is constant and we can still successfully do that when it's a hooked variable, and maybe that has allowed the JIT to get really aggressive with our test. Let's try making $var less constant and see what happens.

$r = Random.new

def simple_count
  $var = $r.rand(8)
  total = 0
  10000.times do
    total += $var
  end
  total
end

So we ar seeing some slowdown, but we're still faster than other implementations. The slowdown we see is quite sensitive to the precise benchmark design. Some showed very little slowdown while this case has is 3 times slower with hooked variables.

After this work there's only two special bits of variable support left in our parser. We still look for $1...$N for accessing captured group in $~. They would be trivial to implement in Ruby, but how high is N? If we want to be exactly like MRI then there should be as many variables as there are capture groups in a the regexp last match, but only the first nine will be listed by Kernel#global_variables. We might handle this by introducing a variable_missing method that would be called if the global variable storage has not already been declared, this could then create hooked variables for captured group variables and normal storage for anything else.

The other special handling we still have is for named captures. If you use =~ on a regexp literal, and it has named capture groups, then the equivalently named local variables will be set to the capture groups. We could write most of that in Ruby, but we'd still need to check for named captures in the parser, and making sure it optimised well would probably require some extra work that we haven't done yet.

Since we saw some slow down from hooked variables in performance testing we may want to look more deeply into that and see if it can be reduced or eliminated, and we migth look at rewriting the storage for $~ in Ruby as well.

TruffleRuby lets us implement more of Ruby in Ruby itself while still allowing aggressive optimisation to be done. This can help make our runtime smaller and hopefully make it easier for the community to understand and contribute to our implementation.