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はGraalVMの不可欠な部分であるため、TruffleRubyのバージョン番号は、常に、含まれているGraalVMのバージョンと同じになります。標準JVMなど、GraalVMの外部でTruffleRubyを使用している場合、バージョンは'0.0'になります。GraalVMおよびTruffleRubyのバージョン番号は、標準のRUBY_ENGINE_VERSION定数を使用して確認できます。

TruffleRubyのメソッドおよびクラス

TruffleRubyには、TruffleRubyモジュールの追加機能を提供する、次の非標準のメソッドおよびクラスが用意されています:

• TruffleRuby.jit?は、GraalVMコンパイラが使用可能で、使用されるかどうかを報告します。

• TruffleRuby.native?は、TruffleRubyがネイティブ実行可能ファイルとしてコンパイルされているかどうかを報告します。

• TruffleRuby.cexts?は、TruffleRubyにGraalVM LLVM Runtime for C拡張機能があるかどうかを報告します。

• TruffleRuby.revisionは、TruffleRubyを構築するために使用されたソース制御リビジョンを文字列として報告します。CRuby 2.7+と同様に、RUBY_REVISIONとしても使用できます。

• TruffleRuby.full_memory_barrierは、バリアー前のロードまたは格納がバリアー後のロードまたは格納と入れ替えられることが確実に防止されます。

• TruffleRuby.graalvm_homeは、GraalVMホーム、またはGraalVMの外部(TruffleRubyスタンドアロンなど)で実行されている場合は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拡張機能では使用しないでください。