GC: config・stat_heap・total_time 系の 5 メソッドを追加

[Watson1978]

概要

Ruby 4.0 に存在するのにリファレンスに項目が無い [c:GC] のメソッド 5 個を追加しました。

追加したメソッド

Ruby 3.1 で追加:

• GC.total_time — GC にかかった時間の合計 (ナノ秒)
• GC.measure_total_time / GC.measure_total_time= — 時間計測の有無

Ruby 3.2 で追加:

• GC.stat_heap — サイズプールごとの統計情報

Ruby 3.4 で追加:

• GC.config — GC の設定の取得と変更

登場バージョンの確認

2.7 / 3.0 / 3.1 / 3.2 / 3.3 / 3.4 / 4.0 の実機で GC.singleton_methods(false) を比較しました。

2.7.8:  []
3.0.7:  []
3.1.6:  [:measure_total_time, :measure_total_time=, :total_time]
3.2.11: [:measure_total_time, :measure_total_time=, :stat_heap, :total_time]
3.3.12: [:measure_total_time, :measure_total_time=, :stat_heap, :total_time]
3.4.10: [:config, :measure_total_time, :measure_total_time=, :stat_heap, :total_time]
4.0.6:  [:config, :measure_total_time, :measure_total_time=, :stat_heap, :total_time]

記述の方針

• measure_total_time と measure_total_time= は getter/setter の対なので、
  docs/HowToWriteMethodEntry.md にならい 1 つのエントリにまとめました。
• 配置は関連するメソッドの近くにしました。stat_heap は GC.stat の直後、
  total_time と measure_total_time は latest_gc_info の後、
  config は設定系の GC.auto_compact= の後です。

サンプルコードについて

GC.stat_heap が返すハッシュは、キー自体がバージョンによって異なります。

3.2.11: {:slot_size=>40, :heap_allocatable_pages=>1, ..., :heap_tomb_pages=>0, ...}
4.0.6:  {slot_size: 40, heap_live_slots: 14698, heap_free_slots: 1676, ...}

値も環境依存なので、例ではハッシュ全体を出さず、キーの一覧と特定の値だけを示しました。

p GC.stat_heap.keys           # => [0, 1, 2, 3, 4]
p GC.stat_heap(0, :slot_size) # => 40

この形なら 3.2 から 4.0 まで出力が変わらないことを実機で確認しています
(Hash の inspect 表記が 3.4 で変わる問題も同時に避けられます)。
GC.config は 3.4 からのメソッドなので、例の出力は新しい表記のみで済みます。

GC.total_time の返り値は環境や実行状況で変わるため、その旨を本文に書きました。

検証

• 記載したサンプルコードは対象となる全バージョンで実行し、出力を確認しました。
• rake check_blank_lines / check_indent_in_samplecode / check_single_space_indent
• bitclust update --markdowntree=manual/api を 3.0 / 3.1 / 3.2 / 3.3 / 3.4 / 4.0 で実行し、
  エラーが出ないこと、および登録されるメソッドが 0 / 3 / 4 / 4 / 5 / 5 件と
  上記の追加バージョンどおりになることを確認しました。

🤖 Generated with Claude Code

[znz]

レビューしました。since の版分け・出力表記とも正確で、マージ可と考えます。 1 点だけ非ブロッキングの参考情報です。

検証(実機 3.0.7 / 3.1.7 / 3.2.11 / 3.3.12 / 3.4.10 / 4.0.6 + bitclust ミニ描画)

• since: config=3.4・stat_heap=3.2・total_time/measure_total_time=3.1 を各版で確認。NEWS の GC.config(3.4)・GC.total_time(3.1, Feature #10917)とも一致。
• GC.stat_heap: stat_heap.keys は 3.2〜4.0 で [0, 1, 2, 3, 4]、stat_heap(0, :slot_size) は 40、存在しないプール番号は ArgumentError、を全版で確認(記載どおり・版差なし)。
• GC.config: 引数なしの出力 {rgengc_allow_full_mark: true, implementation: "default"}(3.4 の新 inspect 表記)・rgengc_allow_full_mark: false への設定・未知キーの無視・:implementation の読み取り専用(ArgumentError)を確認。
• GC.total_time / measure_total_time: 既定 true・計測無効中は増えない・nil で false、を確認。

参考(非ブロッキング): GC.config(hash) の戻り値の版差

本文の「hash を指定すると…変更後の設定を返します」について、GC.config(hash)(setter 呼び出し)の戻り値そのものを見ると版差がありました:

3.4.10: GC.config(rgengc_allow_full_mark: false)  # => {rgengc_allow_full_mark: false}          (指定キーのみ・implementation なし)
4.0.6 : GC.config(rgengc_allow_full_mark: false)  # => {rgengc_allow_full_mark: false, implementation: "default"}  (完全な Hash)

3.4 系では setter の戻り値が「指定したキーだけの部分 Hash」で、「変更後の設定(全体)」という文言とは少しずれます(4.0 で全体を返すよう変わったようです)。掲載されている例はいずれも GC.config(...) の後で改めて p GC.config を呼んでいるので出力は 3.4/4.0 どちらでも正しく、実害はありません。もし正確を期すなら、戻り値についてだけ一言補足する余地があるかも、という程度の参考です。このままでも問題ないと思います。

🤖 Generated with Claude Code

[Watson1978]

参考情報ありがとうございます。ご指摘のとおり実機でも版差を確認しました。

3.4.10: GC.config(rgengc_allow_full_mark: false) # => {rgengc_allow_full_mark: false}
4.0.6 : GC.config(rgengc_allow_full_mark: false) # => {rgengc_allow_full_mark: false, implementation: "default"}

APPROVED いただいた後で恐縮ですが、返り値についてだけ一文補足しました (dd1e926)。

hash を指定したときの返り値は、Ruby 3.4 では指定したキーだけを含む Hash で、
Ruby 4.0 以降では設定全体を含む Hash です。

例そのものは、ご指摘のとおり設定後に改めて p GC.config を呼んでいて出力はどちらの版でも正しいため、変更していません。

🤖 Generated with Claude Code

[znz]

補足対応ありがとうございます。dd1e9269b を確認しました。マージ可と考えます。

追記いただいた一文は実機の版差と一致していますし（3.4＝指定キーのみ / 4.0 以降＝設定全体）、本文の「設定を返します」への言い換えも適切だと思います。[c:Hash] へのリンクも問題なく、ネイティブ MDParser でのレンダリングも 3.4 / 4.0 とも compileerror 0 でした。版差はどちらの版でも成立する記述なので、#@since で囲まずに地の文で説明する形で良いと思います。

🤖 Generated with Claude Code