Ruby 4.1 リファレンスマニュアル

module GC

[edit]

要約

GC は Ruby インタプリタの「ゴミ集め(Garbage Collection)」を制御するモジュールです。

GCのチューニングについて

Ruby 2.1ではRGenGCと呼ばれる新たなGCメカニズムが導入されました。それにともない、以下の環境変数が導入され、これらを設定することでGCの動作をチューニングできます。これらの環境変数の効果はRubyの起動時のみ有効です(つまりrubyを動かしている途中で変更することはできません)。

チューニングのための環境変数

以下の2つの環境変数はobsoleteであり、新しいものを使うことが望ましい

RUBY_GC_HEAP_GROWTH_FACTOR と RUBY_GC_HEAP_FREE_SLOTS_GOAL_RATIO に関する補足説明

RUBY_GC_HEAP_GROWTH_FACTOR と RUBY_GC_HEAP_FREE_SLOTS_GOAL_RATIO はともに GC後に空きスロットが少ないときにどれだけの量のメモリを新たに確保するかを決めるパラメータである。この2つのパラメータの優先順位は以下の通りである。

当然、RUBY_GC_HEAP_GROWTH_MAX_SLOTS はこれらより優先度が高いことに注意。

malloc閾値についての説明

Rubyが利用するメモリはスロット以外にもある。例えば長い文字列は malloc によってCのヒープ上に確保される。GCはこのようなヒープ上のメモリを解放するためにも実行される。そこで、rubyでは malloc によるメモリ消費量を保持し、この消費量がある閾値を越えるとGCが起動される。また、GCが起動されるごとにこの消費量カウンタが0にリセットされる。

このカウンタは2種類あり、一方は malloc_increase_bytes、もう一方は oldmalloc_increase_bytes と呼ばれる。この2つの性質は以下のようになっている。

実行中のパラメータ

プログラム実行中には、GCに関する統計情報/閾値情報を GC.stat で見ることができるが、この文章で説明した以下の情報はこれで調べることができる。

チューニングについて

この設定を理解するための用語集

参考資料

[SEE_ALSO] ObjectSpace

目次

特異メソッド
インスタンスメソッド
定数

特異メソッド

auto_compact -> boolRuby 3.0 から[permalink][rdoc][edit]

auto compaction が有効化どうかを返します。

[RETURN]
auto compaction が有効な場合 true を返します。そうでなければ false を返します。

[SEE_ALSO] GC.auto_compact=

auto_compact=(bool)Ruby 3.0 から[permalink][rdoc][edit]

GC.compact をフルGCで行うかどうかを制御します。

true を設定するとフルGCのタイミングででヒープをコンパクションします。

この機能を有効にするとフルGCのパフォーマンスが低下します。

デフォルトは false です。

詳細は[feature#17176]を参照してください。

[PARAM] bool:
フルGCでコンパクションするかどうかを true か false で設定します。

[SEE_ALSO] GC.compact GC.auto_compact

compact -> HashRuby 2.7.0 から[permalink][rdoc][edit]

ヒープをコンパクションします。

詳細は[feature#15626]を参照してください。

[SEE_ALSO] GC.verify_compaction_references

config -> {Symbol => object}Ruby 3.4 から[permalink][rdoc][edit]
config(hash) -> {Symbol => object}

GC の設定を取得、変更します。

引数を省略すると現在の設定を返します。 hash を指定すると、その内容を現在の設定にマージしてから設定を返します。設定に無いキーは無視されます。

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

このメソッドは処理系依存 (CRuby 特有) です。設定できる項目は GC の実装ごとに異なり、予告なく変更される可能性があります。

すべての実装に共通する項目は :implementation だけです。これは実装の名前を表す読み取り専用の項目で、Ruby の既定の実装では "default" です。

既定の実装では :rgengc_allow_full_mark を設定できます。 false を指定すると、フルマークを行う GC (major GC) が実行されなくなります。

[PARAM] hash:
変更する設定を Hash で指定します。キーは Symbol で指定します。
[RETURN]
設定を Hash で返します。
[EXCEPTION] ArgumentError:
hash が Hash でない場合に発生します。 
p GC.config # => {rgengc_allow_full_mark: true, implementation: "default"}

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

# 設定に無いキーは無視される
GC.config(unknown_key: 1)
p GC.config # => {rgengc_allow_full_mark: false, implementation: "default"}
count -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]

プロセス開始からガーベージコレクトを実行した回数を Integer で返します。

例 
p GC.count # => 3
disable -> bool[permalink][rdoc][edit]

ガーベージコレクトを禁止します。

前回の禁止状態を返します(禁止されていたなら true, GC が有効であったなら、 false)。

例 
p GC.disable # => false
p GC.disable # => true

[SEE_ALSO] GC.enable

enable -> bool[permalink][rdoc][edit]

ガーベージコレクトを許可します。

前回の禁止状態を返します(禁止されていたなら true, GC が有効であったなら、 false)。

[SEE_ALSO] GC.disable

例 
p GC.disable # => false
p GC.enable  # => true
p GC.enable  # => false
latest_gc_info(result_hash = {}) -> HashRuby 2.1.0 から[permalink][rdoc][edit]
latest_gc_info(key) -> object

最新のGCの情報を返します。

[PARAM] result_hash:
戻り値のためのハッシュを指定します。省略した場合は新しくハッシュを作成します。result_hash の内容は上書きされます。
[PARAM] key:
得られる情報から特定の情報を取得したい場合にキーを Symbol で指定します。
例 
latest = GC.latest_gc_info
p latest # => {:major_by=>nil, :gc_by=>:newobj, :have_finalizer=>false, :immediate_sweep=>false, :state=>:sweeping}

stat = GC.stat
merged = GC.latest_gc_info(stat)
p merged == latest.merge(stat) # => true

p GC.latest_gc_info(:gc_by)  # => :newobj
measure_total_time -> boolRuby 3.1 から[permalink][rdoc][edit]
measure_total_time=(flag)

GC にかかった時間を計測するかどうかを取得、設定します。既定では計測が有効です。

計測を有効にすると GC のたびに時間を測るため、わずかに実行速度が落ちます。

[PARAM] flag:
nil または false を指定すると計測を無効にします。それ以外の値を指定すると有効にします。
[RETURN]
measure_total_time は計測が有効なら true を、無効なら false を返します。 
p GC.measure_total_time # => true

GC.measure_total_time = false
p GC.measure_total_time # => false

GC.measure_total_time = nil
p GC.measure_total_time # => false

[SEE_ALSO] GC.total_time

start(full_mark: true, immediate_mark: true, immediate_sweep: true) -> nil[permalink][rdoc][edit]

ガーベージコレクトを開始します。

GC#garbage_collect や ObjectSpace?.garbage_collect と同じ働きをします。 GC.disable により GC が禁止されている場合でもガベージコレクトを開始します。

nil を返します。

[PARAM] full_mark:
マイナー GC を動作させる場合は false を、そうでない場合は true を指定します。
[PARAM] immediate_mark:
mark を遅らせる(Lazy Mark を行う)場合は false を、そうでない場合は true を指定します。
[PARAM] immediate_sweep:
sweep を遅らせる(Lazy Sweep を行う)場合は false を、そうでない場合は true を指定します。

注意: これらのキーワード引数は Ruby の実装やバージョンによって異なります。将来のバージョンとの互換性も保証されません。また、Ruby の実装がサポートしていない場合はキーワード引数を指定しても無視される可能性があります。

例 
p GC.count  # => 3
p GC.start  # => nil
p GC.count  # => 4
stat(result_hash = {}) -> {Symbol => Integer}Ruby 1.9.3 から[permalink][rdoc][edit]
stat(key) -> Numeric

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

[PARAM] result_hash:
戻り値のためのハッシュを指定します。省略した場合は新しくハッシュを作成します。result_hash の内容は上書きされます。
[PARAM] key:
得られる統計情報から特定の情報を取得したい場合にキーを Symbol で指定します。
[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
# }

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

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

stat_heap -> {Integer => Hash}Ruby 3.2 から[permalink][rdoc][edit]
stat_heap(heap_id) -> {Symbol => Integer}
stat_heap(heap_id, key) -> Integer
stat_heap(heap_id, result_hash) -> {Symbol => Integer}
stat_heap(nil, result_hash) -> {Integer => Hash}

サイズプールごとの GC の統計情報を Hash で返します。

引数を省略すると、すべてのサイズプールの統計情報を、サイズプールの番号をキーとしたハッシュで返します。 heap_id を指定すると、そのサイズプールの統計情報だけを返します。

[PARAM] heap_id:
サイズプールの番号を Integer で指定します。 nil を指定すると、すべてのサイズプールが対象になります。
[PARAM] key:
特定の情報だけを取得したい場合にキーを Symbol で指定します。
[PARAM] result_hash:
戻り値のためのハッシュを指定します。省略した場合は新しくハッシュを作成します。result_hash の内容は上書きされます。
[EXCEPTION] ArgumentError:
存在しないサイズプールの番号を指定した場合に発生します。 
# サイズプールごとの統計情報を返す
p GC.stat_heap.keys # => [0, 1, 2, 3, 4]

# サイズプール 0 が扱うオブジェクトの大きさ (バイト)
p GC.stat_heap(0, :slot_size) # => 40

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

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

[SEE_ALSO] GC.stat

stress -> bool[permalink][rdoc][edit]

GCがストレスモードかどうかを返します。

真が設定されている場合は GC を行えるすべての機会に GC を行います。

[SEE_ALSO] GC.stress=

stress=(value)[permalink][rdoc][edit]

GCのストレスモードを引数 value に設定します。引数 value が真に設定されている間は、GC を行えるすべての機会に GC を行います。

この機能はデバッグ用途に提供されています。ストレスモードを有効にするとプログラムのパフォーマンスが低下します。

[PARAM] value:
任意のオブジェクト。整数以外の値を指定した場合は真偽値として解釈されます。整数を指定する場合は以下のフラグをOR演算した値を指定します。
0x01

マイナー GC を動作させる場合に指定します。

0x02

sweep を遅らせる(Lazy Sweep を行う)に指定します。

0x04

malloc/calloc/realloc の後でメジャーGCを動作させる場合に指定します。

例 
p GC.stress # => false
GC.stress = true
p GC.stress # => true

[SEE_ALSO] GC.stress

total_time -> IntegerRuby 3.1 から[permalink][rdoc][edit]

プロセス開始から GC にかかった時間の合計をナノ秒で返します。

時間が積算されるのは GC.measure_total_time が true の間だけです。計測を無効にしている間に GC が実行されても、返り値は変化しません。 

p GC.measure_total_time # => true
p GC.total_time         # => 625000

GC.start
p GC.total_time         # => 937500

GC.measure_total_time = false
GC.start
p GC.total_time         # => 937500  計測が無効なので増えない

返り値は実行環境や実行状況によって異なります。

[SEE_ALSO] GC.measure_total_time

verify_compaction_references(toward: nil, double_heap: nil) -> HashRuby 2.7.0 から[permalink][rdoc][edit]

コンパクションの参照の一貫性を検証します。

このメソッドは処理系依存 (CRuby 特有) です。コンパクション中に移動されたオブジェクトは T_MOVED オブジェクトに置き換えられます。コンパクション後には T_MOVED を参照するオブジェクトは存在するべきではありません。

この関数は全てのオブジェクトが移動する余地を確保するためにヒープを2倍にして、全ての移動を確実にするためにヒープをコンパクションして、全ての参照を更新して、それからフルGCを実行します。もし T_MOVED への参照をもつオブジェクトがあれば、マークスタックにプッシュされて、 SEGV が起きるでしょう。

[PARAM] toward:
nil か :empty を指定します。
[PARAM] double_heap:
ヒープサイズを2倍にするかどうかを真偽値で指定します。
[RETURN]
GC.compact の返り値と同じです。

[SEE_ALSO] GC.compact

インスタンスメソッド

garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true) -> nil[permalink][rdoc][edit]

ガーベージコレクトを開始します。

GC.start や ObjectSpace?.garbage_collect と同じ働きをします。 GC.disable により GC が禁止されている場合でもガベージコレクトを開始します。

nil を返します。

[PARAM] full_mark:
マイナー GC を動作させる場合は false を、そうでない場合は true を指定します。
[PARAM] immediate_mark:
mark を遅らせる(Lazy Mark を行う)場合は false を、そうでない場合は true を指定します。
[PARAM] immediate_sweep:
sweep を遅らせる(Lazy Sweep を行う)場合は false を、そうでない場合は true を指定します。

注意: これらのキーワード引数は Ruby の実装やバージョンによって異なります。将来のバージョンとの互換性も保証されません。また、Ruby の実装がサポートしていない場合はキーワード引数を指定しても無視される可能性があります。

例 
include GC
p GC.count  # => 3
garbage_collect
p GC.count  # => 4

定数

INTERNAL_CONSTANTS -> {Symbol => Integer}Ruby 2.1.0 から[permalink][rdoc][edit]

GC用内部定数の値を保持するハッシュテーブルです。 

p GC::INTERNAL_CONSTANTS
# => {:RVALUE_SIZE=>40, :HEAP_PAGE_OBJ_LIMIT=>408, :HEAP_PAGE_BITMAP_SIZE=>56, :HEAP_PAGE_BITMAP_PLANES=>4}
OPTS -> [String]Ruby 2.1.0 から[permalink][rdoc][edit]

コンパイル時に指定したGCのオプションです。

可能性があるオプション文字列は以下の通りです。

  • "GC_DEBUG"
  • "USE_RGENGC"
  • "RGENGC_DEBUG"
  • "RGENGC_CHECK_MODE"
  • "RGENGC_PROFILE"
  • "RGENGC_ESTIMATE_OLDMALLOC"
  • "GC_PROFILE_MORE_DETAIL"
  • "GC_ENABLE_LAZY_SWEEP"
  • "CALC_EXACT_MALLOC_SIZE"
  • "MALLOC_ALLOCATED_SIZE"
  • "MALLOC_ALLOCATED_SIZE_CHECK"
  • "GC_PROFILE_DETAIL_MEMORY"
例 
p GC::OPTS # => ["USE_RGENGC", "RGENGC_ESTIMATE_OLDMALLOC", "GC_ENABLE_LAZY_SWEEP"]
# この場合、GCデバッグ機能やプロファイル機能は無効化されている