TruffleRuby追加機能

TruffleRubyは、他の実装で開発されたプログラムを実行する標準的なRuby実装として使用することを意図していますが、他の実装にはない追加機能も提供します。

他のRuby実装との互換性については、互換性ガイドを参照してください。

TruffleRuby上で実行しているかどうかを検出する #

--versionコマンドラインオプションを使用できます。TruffleRubyは、例えば以下のように報告します。

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

Rubyコードでは、標準のRUBY_ENGINE定数を確認できます。これは'truffleruby'になります。CコードではTRUFFLERUBYが定義されています。

RUBY_ENGINEを確認する代わりに、機能検出を使用することも可能です。

TruffleRubyのバージョン番号は、標準のRUBY_ENGINE_VERSION定数を使用して取得できます。

TruffleRubyメソッドとクラス #

TruffleRubyは、TruffleRubyモジュールに追加機能を提供する、これらの非標準メソッドとクラスを提供します。

TruffleRuby.jit?は、GraalVMコンパイラが利用可能で、使用されるかどうかを報告します。
TruffleRuby.native?は、TruffleRubyがネイティブ実行ファイルとしてコンパイルされているかどうかを報告します。
TruffleRuby.cexts?は、TruffleRubyにC拡張機能用のGraalVM LLVMランタイムが利用可能かどうかを報告します。
TruffleRuby.revisionは、TruffleRubyのビルドに使用されたソースコード管理リビジョンを文字列として報告します。CRuby 2.7+と同様にRUBY_REVISIONとしても利用できます。
TruffleRuby.full_memory_barrierは、バリアの前にあるロードまたはストアと、バリアの後にあるロードまたはストアの並べ替えがないことを保証します。
TruffleRuby.graalvm_homeは、GraalVMホームを返します。GraalVMの外で実行されている場合（例：ネイティブスタンドアロン）はnilを返します。
TruffleRuby.synchronized(object) { }は、オブジェクトインスタンスごとに暗黙的なロックを保持しながらブロックを実行します。

アトミック参照 #

atomic_reference = TruffleRuby::AtomicReference.new(value=nil)は、指定されたオブジェクトへの参照を持つ新しいアトミック参照を作成します。
atomic_reference.getは、アトミック参照の値を取得し、値を返します。
atomic_reference.set(new_value)は、アトミック参照の値を設定し、new_valueを含む書き込みに関するメモリバリアを引き起こします。
atomic_reference.get_and_set(new_value)は、アトミック参照の値を設定し、前の値を返し、new_valueを含む書き込みに関するメモリバリアを引き起こします。
atomic_reference.compare_and_set(expected_value, new_value)は、現在期待値を持っている場合のみ、アトミック参照の値を設定し、設定されたかどうかを示すブール値を返し、new_valueを含む書き込みに関するメモリバリアを引き起こします。数値オブジェクトの場合、現在の値を取得し、現在の値が数値であり、==を呼び出すことで期待値と等しいことを確認してから、アトミックな比較と設定を実行します。
AtomicReferenceはマーシャリング可能です。

並行マップ #

TruffleRuby::ConcurrentMapは、Hashのようなキーと値のデータ構造であり、キーの比較には#hashと#eql?、値の比較には同一性を用います。Hashとは異なり、順序付けられていません。TruffleRuby::ConcurrentMapのすべてのメソッドはスレッドセーフですが、完全に同期された実装よりも高い並行性を持つ必要があります。concurrent-rubyなどのgemで使用することを目的としており、直接使用するのではなく、このgemを介して使用してください。

map = TruffleRuby::ConcurrentMap.new([initial_capacity: ...], [load_factor: ...])
map[key] = new_value
map[key]
map.compute_if_absent(key) { computed_value } キーが見つからない場合、ブロックを実行して結果を保存します。ブロックは最大1回実行されます。計算された値を返します。
map.compute_if_present(key) { |current_value| computed_value } キーが見つかった場合、ブロックを実行して結果を保存します。ブロックがnilを返す場合、そのキーのエントリは削除されます。ブロックは最大1回実行されます。最終的な値を返し、ブロックがnilを返した場合はnilを返します。
map.compute(key) { |current_value| computed_value } ブロックを実行し、現在の値がある場合はそれを渡します。またはnilを渡し、結果を保存します。ブロックがnilを返す場合、そのキーのエントリは削除されます。計算された値を返します。
map.merge_pair(key, new_value) { |existing_value| merged_value } キーが見つからない場合、またはnilの場合、新しい値を保存します。そうでない場合は、ブロックを呼び出して結果を保存するか、ブロックがnilを返した場合はエントリを削除します。そのエントリの最終的な値を返します。ブロックがnilを返した場合はnilを返します。
map.replace_pair(key, expected_value, new_value) キーの値を置き換えますが、既存の値がexpected_valueと同じである場合のみ（同一性で比較）。値が置き換えられたかどうかを返します。
map.replace_if_exists(key, value) キーが見つかった場合のみ、キーの値を置き換えます。キーが存在する場合はvalueを返し、そうでない場合はnilを返します。
map.get_and_set(key, new_value) キーの値を設定し、前の値を返します。
map.key?(key) マップにキーが含まれているかどうかを返します。
map.delete(key) 存在する場合、マップからキーを削除します。値を返し、存在しない場合はnilを返します。
map.delete_pair(key, expected_value) キーを削除しますが、既存の値がexpected_valueと同じである場合のみ（同一性で比較）。キーが削除されたかどうかを返します。
map.clear マップからすべてエントリを削除します。
map.size マップのエントリ数を返します。
map.get_or_default(key, default_value)
map.each_pair { |key, value| ... }

FFI #

TruffleRubyには、Ruby-FFIバックエンドが含まれています。これは透過的であるはずです。通常の方法でffi gemをインストールするだけで、TruffleRubyのFFIバックエンドを使用します。TruffleRubyにはFFI gemのデフォルトバージョンも含まれているため、gemがインストールされていなくても、require "ffi"はTruffleRubyで常に機能します。

ポリグロットプログラミング #

PolyglotとJavaモジュールは、GraalVMのポリグロットプログラミング機能へのアクセスを提供します。ポリグロットプログラミングガイドで説明されています。

サポートされていない追加機能 #

Truffle::POSIXやTruffle::FFIなど、ここにリストされていない興味深いモジュールやメソッドを見つけることができる場合があります。このドキュメントにリストされていない追加のモジュールとメソッドは、TruffleRubyの実装をサポートするために設計されており、使用しないでください。将来、変更されるか、ユーザープログラムに対して非表示になる可能性があり、使用しないでください。

MRIによって提供されるもの以外のTruffleRuby C拡張ヘッダー内の追加マクロ、関数、変数（rb_tr_*で始まるものなど）はサポートされておらず、C拡張では使用しないでください。