module RubyVM::YJIT

要約

YJIT (Yet Another Ruby JIT) の制御・情報取得のためのモジュールです。

YJIT は CRuby に組み込まれた JIT (Just-in-time compiler) コンパイラで、 Ruby 3.1 で実験的機能として導入されました([feature#18229])。 Ruby 3.2 で「実験的」の位置づけが外れ、Ruby 3.3 では実行時に有効化する RubyVM::YJIT.enable が追加されるなど、以降のバージョンでも統計収集(--yjit-stats)やコンパイルログ(--yjit-log)まわりの機能追加が続いています。

有効化するには以下のいずれかの方法を使います。

• コマンドラインオプション --yjit
• 環境変数 RUBY_YJIT_ENABLE
• (Ruby 3.3 以降) RubyVM::YJIT.enable による実行時の有効化

このモジュールは、YJIT が対応していないプラットフォームでは定義されないことがあります。

なお、Ruby 4.0 で導入された新しい JIT コンパイラである ZJIT は RubyVM::ZJIT という別のモジュールで提供されており、 RubyVM::YJIT とは別物です。

目次

特異メソッド

• code_gc
• dump_exit_locations
• enable
• enabled?
• log
• log_enabled?
• max_compile_time_ns
• max_compile_time_ns=
• reset_stats!
• runtime_stats
• stats_enabled?
• stats_string
• total_compile_time_ns

特異メソッド

code_gc -> nilRuby 3.2 から[permalink][rdoc][edit]

() → void

コンパイル済みのコードを破棄してメモリを解放します。以降、必要に応じて再度コンパイルが行われます。

dump_exit_locations(filename) -> IntegerRuby 3.2 から[permalink][rdoc][edit]

(untyped filename) → void

--yjit-trace-exits を指定して収集した、サイドイグジット(exit)が発生した位置の情報を Marshal 形式で filename にダンプします。ダンプしたファイルは Stackprof で読み込んで解析できます。

[PARAM] filename:

ダンプ先のファイル名。

[RETURN]

ファイルに書き込んだバイト数を返します。

[EXCEPTION] ArgumentError:

--yjit-trace-exits が有効になっていない場合に発生します。

enable(stats: false, log: false, mem_size: nil, call_threshold: nil) -> boolRuby 3.3 から[permalink][rdoc][edit]

(?stats: false | true | :quiet) → void

実行時に YJIT を有効化します。

[PARAM] stats:

統計収集の設定です。false なら収集しません。true なら収集し、終了時に結果を表示します。:quiet なら収集しますが、終了時には表示しません。

[PARAM] log:

コンパイルログ収集の設定です。指定できる値は stats と同様です。 (Ruby 3.4 で追加されたキーワード引数です)

[PARAM] mem_size:

YJIT が使用するメモリ量の上限を MB 単位(1 から 2048 の範囲)で指定します。 nil の場合はデフォルト値を使います。(Ruby 4.0 で追加されたキーワード引数です)

[PARAM] call_threshold:

JIT コンパイルを開始するまでのメソッド呼び出し回数のしきい値を指定します。 nil の場合はデフォルト値を使います。(Ruby 4.0 で追加されたキーワード引数です)

[RETURN]

有効化したときは true を返します。すでに YJIT が有効な場合や、 ZJIT (RubyVM::ZJIT) が有効になっている場合は false を返します。

[EXCEPTION] ArgumentError:

mem_size や call_threshold に不正な値を指定した場合に発生します。

RubyVM::YJIT.enable # => true

JIT の有効・無効はビルドオプションや実行環境に依存するため、実行結果は環境によって異なります。

[SEE_ALSO] RubyVM::YJIT.enabled?

enabled? -> boolRuby 3.1 から[permalink][rdoc][edit]

() → bool

YJIT が有効かどうかを返します。

RubyVM::YJIT.enabled? # => false

JIT の有効・無効はコマンドラインオプションや環境変数など実行環境に依存するため、実行結果は環境によって異なります。

[SEE_ALSO] RubyVM::YJIT.enable

log -> [[Time, String]] | nilRuby 3.4 から[permalink][rdoc][edit]

--yjit-log で収集したコンパイルログを返します。配列の各要素は、コンパイルした日時とコンパイル対象を表す文字列との組です。ログ収集が無効な場合は nil を返します。

[SEE_ALSO] RubyVM::YJIT.log_enabled?, RubyVM::YJIT.enable

log_enabled? -> boolRuby 3.4 から[permalink][rdoc][edit]

--yjit-log が指定されているなど、コンパイルログの収集が有効かどうかを返します。

[SEE_ALSO] RubyVM::YJIT.log, RubyVM::YJIT.enable

max_compile_time_ns -> IntegerRuby 4.1 から[permalink][rdoc][edit]

YJIT がコンパイルに使ってよい時間の上限をナノ秒単位で返します。 RubyVM::YJIT.total_compile_time_ns がこの値を超えると、上限が引き上げられるまで YJIT はコンパイルを止めます。 0 は無制限を表し、デフォルトは 0 です。

上限は best-effort で扱われるため、コンパイルが止まっているはずの間にもコンパイルすることがあります。 JIT のウォームアップの速さを制御し、コンパイルの負荷をより長い時間に分散させるための機能です([feature#22236])。たとえば、リクエストや一定の周期ごとにコンパイル時間の予算を割り当てたいときは、 RubyVM::YJIT.max_compile_time_ns = RubyVM::YJIT.total_compile_time_ns + 20_000_000 のように、現在の合計に予算を足した値を設定します。

YJIT が有効でなければ 0 を返します。

例

p RubyVM::YJIT.max_compile_time_ns # => 0

[SEE_ALSO] RubyVM::YJIT.max_compile_time_ns=, RubyVM::YJIT.total_compile_time_ns

max_compile_time_ns=(ns)Ruby 4.1 から[permalink][rdoc][edit]

YJIT がコンパイルに使ってよい時間の上限をナノ秒単位で設定します。意味は RubyVM::YJIT.max_compile_time_ns を参照してください。 0 を指定すると無制限になります。

RubyVM::YJIT.enable やコマンドラインオプション --yjit で YJIT を有効にしてから使います。

[PARAM] ns:

上限(ナノ秒)。Integer 以外は Integer に変換されます(1.5 は 1 になります)。負の値は渡さないでください(符号なし整数として扱われ、非常に大きな値になります)。

[RETURN]

設定した値を返します。

[EXCEPTION] TypeError:

ns に文字列など Integer に変換できないものを指定した場合に発生します。

例

RubyVM::YJIT.enable
RubyVM::YJIT.max_compile_time_ns = 10
p RubyVM::YJIT.max_compile_time_ns # => 10

[SEE_ALSO] RubyVM::YJIT.max_compile_time_ns, RubyVM::YJIT.total_compile_time_ns

reset_stats! -> nilRuby 3.1 から[permalink][rdoc][edit]

() → void

--yjit-stats で収集した統計情報を破棄します。

[SEE_ALSO] RubyVM::YJIT.runtime_stats, RubyVM::YJIT.stats_enabled?

runtime_stats(key = nil) -> Hash | object | nilRuby 3.1 から[permalink][rdoc][edit]

(?context: bool) → Hash[untyped, untyped]?

--yjit-stats コマンドラインオプションを指定して収集した統計情報を返します。

[PARAM] key:

Symbol を指定すると、そのキーに対応する値のみを返します。 (Ruby 3.4 で追加された引数です)

[RETURN]

key を指定しない場合は統計情報のハッシュを返します。key を指定した場合は対応する値を返します。統計収集が無効な場合は nil を返します。

[EXCEPTION] TypeError:

key に Symbol 以外(nil を除く)を指定した場合に発生します。

統計情報の内容(キー)はバージョンによって増減します。詳細はビルド時の設定やコマンドラインオプションに依存するため、本ページでは個々のキーの説明は省略します。

[SEE_ALSO] RubyVM::YJIT.stats_enabled?, RubyVM::YJIT.reset_stats!

stats_enabled? -> boolRuby 3.1 から[permalink][rdoc][edit]

() → bool

--yjit-stats が指定されているなど、統計情報の収集が有効かどうかを返します。

[SEE_ALSO] RubyVM::YJIT.runtime_stats, RubyVM::YJIT.reset_stats!, RubyVM::YJIT.enable

stats_string -> StringRuby 3.3 から[permalink][rdoc][edit]

() → String

RubyVM::YJIT.runtime_stats の内容を人が読める形式に整形した文字列を返します。 --yjit-stats が有効なとき以外は空文字列を返します。

[SEE_ALSO] RubyVM::YJIT.runtime_stats

total_compile_time_ns -> IntegerRuby 4.1 から[permalink][rdoc][edit]

YJIT がコンパイルに使った実時間の合計をナノ秒単位で返します。値は単調に増加します。YJIT が有効でなければ 0 を返します。

例

RubyVM::YJIT.enable
2000.times { |i| i.to_s }
p RubyVM::YJIT.total_compile_time_ns > 0 # => true

[SEE_ALSO] RubyVM::YJIT.max_compile_time_ns, RubyVM::YJIT.max_compile_time_ns=, RubyVM::YJIT.runtime_stats