Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
97 lines (68 sloc) 3.88 KB

TruffleRuby Additional Functionality

TruffleRuby is intended to be usable as a standard Ruby implementation that runs programs developed on other implementations, but it also provides additional functionality beyond that of other implementations.

Also see the document describing our compatibility with other Ruby implementations.

Detecting if you are running on TruffleRuby

You can use the --version command-line option. TruffleRuby will report for example:

truffleruby ..., like ruby ..., GraalVM CE Native [x86_64-darwin]

In Ruby code, you can look at the standard RUBY_ENGINE constant, which will be 'truffleruby'. In C code TRUFFLERUBY is defined.

It is also possible to use feature-detection instead of looking at RUBY_ENGINE. For example if you are writing an application that uses TruffleRuby's interoperability with Java you could test for defined?(Java), which will be set when in hosted mode on the JVM but not in native mode.

TruffleRuby is an integral part of GraalVM, so the version number of TruffleRuby is always the same as the version of GraalVM that contains it. If you are using TruffleRuby outside of GraalVM, such as a standard JVM, the version will be '0.0'. You can find the version number of GraalVM and TruffleRuby using the standard RUBY_ENGINE_VERSION constant.

TruffleRuby methods and classes

TruffleRuby provides these non-standard methods and classes that provide additional functionality in the TruffleRuby module.

TruffleRuby.jit? reports if the GraalVM Compiler is available and will be used.

TruffleRuby.native? reports if TruffleRuby is compiled as a native image.

TruffleRuby.cexts? reports if TruffleRuby has the GraalVM LLVM Runtime for C extensions available.

TruffleRuby.revision reports the source control revision used to build TruffleRuby.

TruffleRuby.full_memory_barrier ensures lack of reordering of loads or stores before the barrier with loads or stores after the barrier.

TruffleRuby.synchronized(object) { } will run the block while holding an implicit lock per object instance.

Atomic references

atomic_reference = TruffleRuby::AtomicReference.new(value=nil) creates a new atomic reference with a reference to a given object.

atomic_reference.get gets the value of an atomic reference, returning the value.

atomic_reference.set(new_value) sets the value of an atomic reference and causes a memory barrier on writes involving new_value.

atomic_reference.get_and_set(new_value) sets the value of an atomic reference, returns the previous value, and causes a memory barrier on writes involving new_value.

atomic_reference.compare_and_set(expected_value, new_value) sets the value of an atomic reference, only if it currently has the expected value, returning a boolean to say whether or not it was set, and causes a memory barrier on writes involving new_value. For numeric objects it will get the current value and then check that the current value is also a numeric and that it is equal to the expected value by calling ==, then perform an atomic compare and set.

AtomicReference is marshalable.

Polyglot programming

The Polyglot and Java modules provides access to the polyglot programming functionality of GraalVM. They are described in a separate document.

Unsupported additional functionality

You may be able to find some other modules and methods not listed here that look interesting, such as Truffle::POSIX or Truffle::FFI. Additional modules and methods not listed in this document are designed to support the implementation of TruffleRuby and should not be used. They may be modified or made not visible to user programs in the future, and you should not use them.

Extra macros, functions, and variables in TruffleRuby C extension headers beyond those provided by MRI, such as those starting with rb_tr_*, are unsupported and should not be used by any C extension.

You can’t perform that action at this time.