singleton method GC.stat

GC 内部の統計情報を Hash で返します。

[PARAM] result_hash:

戻り値のためのハッシュを指定します。省略した場合は新しくハッシュを作成します。result_hash の内容は上書きされます。

[PARAM] key:

得られる統計情報から特定の情報を取得したい場合にキーを Symbol で指定します。

[PARAM] process:

統計情報の対象を指定します。偽(デフォルト)のときは現在の Ractor のオブジェクト空間の統計情報を、真のときはプロセス全体の統計情報を返します。

[EXCEPTION] ArgumentError:

key に未知のキーや、process で選んだ統計情報に含まれないキーを指定した場合に発生します。

[EXCEPTION] NotImplementedError:

デフォルト以外の GC 実装(MMTk など)で process に真を指定した場合に発生します。

process が偽のときの統計情報には、グローバル GC(全 Ractor を止める stop-the-world の GC)の回数を表すキーが 2 つ含まれます。 :global_gc_count は、その Ractor のヒープを回収したグローバル GC の回数です。どの Ractor が開始したかは問いません。 :global_gc_invocation_count は、その Ractor が開始したグローバル GC の回数です。各グローバル GC を開始した Ractor はちょうど 1 つです。 :minor_gc_count と :major_gc_count はその Ractor のヒープに対するローカルな GC の回数で、グローバル GC は含みません。 :count は :minor_gc_count、:major_gc_count、:global_gc_count の合計です。

process が真のとき、デフォルトの GC では、全 Ractor にわたる累積の GC 回数と計測した CPU 時間、全オブジェクト空間が共有するページプールの状態を返します。 GC 回数と CPU 時間には、終了した Ractor のオブジェクト空間の分も含みます。返るキーは :count、:time、:marking_time、:sweeping_time、:minor_gc_count、:major_gc_count、:global_gc_count、:page_pool_arenas、:page_pool_arenas_freed、:page_pool_total_pages、:page_pool_discarded_pages の 11 個だけです。

process が真のときの :global_gc_count はプロセス内のグローバル GC の回数で、止めた Ractor の数によらず 1 回ずつ数えます。 :count は各ローカル GC と各グローバル GC を 1 回ずつ数えるので、:minor_gc_count、:major_gc_count、:global_gc_count の合計になります。 1 回のグローバル GC は全ヒープを回収するので、この :count は Ractor ごとの :count の合計とは一致しません。

:page_pool_arenas は現在マップされているページプールのアリーナの数、:page_pool_arenas_freed はページプールがアンマップしたアリーナの数です。 :page_pool_total_pages はマップされているアリーナ内のページ本体の数、:page_pool_discarded_pages はメモリを OS に返した空きページ本体の数です。

このときの :time はナノ秒単位の値を合計してからミリ秒に変換するので、:marking_time と :sweeping_time の和より 1 ミリ秒大きくなることがあります。これらの時間は GC が使った CPU 時間で、プログラムの停止時間ではありません。時間が累積されるかどうかは GC.measure_total_time の設定に従います。読み出しは各オブジェクト空間が公開している値を合算するだけで、stop-the-world を要求しません。 Process.fork で作った子プロセスは、親プロセスの累積値を引き継ぎます。

GC.count と GC.total_time は、常に現在の Ractor の値を返します。

# 他の Ractor のオブジェクト空間があるので、子 Ractor の GC.start はグローバル GC になる
r = Ractor.new { GC.start; GC.stat(:global_gc_invocation_count) }
p r.value                                  # => 1
p GC.stat(:global_gc_count)                # => 1 (main Ractor のヒープも回収された)
p GC.stat(:global_gc_invocation_count)     # => 0 (main Ractor は開始していない)
p GC.stat(:global_gc_count, process: true) # => 1
p GC.stat(process: true).key?(:page_pool_arenas) # => true
GC.stat(:page_pool_arenas) # ~> unknown key: page_pool_arenas (ArgumentError)

[RETURN]

GC 内部の統計情報を Hash で返します。引数 key を指定した場合は数値を返します。

p GC.stat
# =>
# {
#   count: 0,
#   heap_allocated_pages: 24,
#   heap_sorted_length: 24,
#   heap_allocatable_pages: 0,
#   heap_available_slots: 9783,
#   heap_live_slots: 7713,
#   heap_free_slots: 2070,
#   heap_final_slots: 0,
#   heap_marked_slots: 0,
#   heap_swept_slots: 0,
#   heap_eden_pages: 24,
#   heap_tomb_pages: 0,
#   total_allocated_pages: 24,
#   total_freed_pages: 0,
#   total_allocated_objects: 7796,
#   total_freed_objects: 83,
#   malloc_increase_bytes: 2389312,
#   malloc_increase_bytes_limit: 16777216,
#   minor_gc_count: 0,
#   major_gc_count: 0,
#   remembered_wb_unprotected_objects: 0,
#   remembered_wb_unprotected_objects_limit: 0,
#   old_objects: 0,
#   old_objects_limit: 0,
#   oldmalloc_increase_bytes: 2389760,
#   oldmalloc_increase_bytes_limit: 16777216
# }

戻り値のハッシュは処理系に依存します。これは将来変更になるかもしれません。

本メソッドは CRuby 以外では動作しません。