GC 모듈

GC 모듈 (GC)

GC 모듈은 Ruby의 mark and sweep 가비지 컬렉션 매커니즘에 대한 인터페이스를 제공해요. 기반 메서드 중 일부는 ObjectSpace 모듈로도 쓸 수 있고, GC 동작 정보는 GC::Profiler로 얻을 수 있어요.

출처: Ruby 3.3 API

본문

상수 (Constants)

  • INTERNAL_CONSTANTS — 가비지 컬렉터의 내부 상수
  • OPTS — GC 빌드 옵션

::add_stress_to_class

add_stress_to_class(class[, ...]) — 주어진 클래스들의 인스턴스를 할당할 때 NoMemoryError를 발생시켜요(디버깅용).

::auto_compact

auto_compact → true 또는 false — 자동 압축(compaction)이 활성화됐는지 돌려줘요.

::auto_compact=

auto_compact = flag — 자동 압축 모드를 갱신해요. 활성화되면 압축기가 매 major 콜렉션마다 실행돼요. 압축을 켜면 major 콜렉션 성능이 떨어져요.

::compact

compact — Ruby 힙의 객체들을 함께 압축해요. 힙의 미사용 공간(파편화)을 제거하려고 객체들을 그 공간으로 옮겨요. 어느 객체가 옮겨졌는지에 관한 통계를 담은 해시를 돌려줘요(압축 통계는 GC.latest_gc_info 참고). 이 메서드는 구현 특이적이라 MRI 외 구현에는 없을 수 있어요. GC 압축이 지원되는지 테스트하려면 이 관용구를 쓰세요.

GC.respond_to?(:compact)

::count

count → Integer — GC가 발생한 횟수를 돌려줘요. 프로세스 시작 이후 GC가 발생한 횟수예요.

::disable

disable → true 또는 false — 가비지 컬렉션을 비활성화하고, 이미 비활성화돼 있었으면 true를 돌려줘요.

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

::enable

enable → true 또는 false — 가비지 컬렉션을 활성화하고, 이전에 비활성화돼 있었으면 true를 돌려줘요.

GC.disable   #=> false
GC.enable    #=> true
GC.enable    #=> false

::latest_compact_info

latest_compact_info → hash — 가장 최근 GC 압축에서 옮겨진 객체에 관한 정보를 돌려줘요. 반환 해시는 :considered와 :moved 두 키를 가져요. :considered는 압축기가 이동을 고려한 객체 수, :moved는 실제로 옮겨진 객체 수를 담아요. 일부 객체는 옮길 수 없으므로(고정됐을 수 있음) 이 숫자로 압축 효율을 계산할 수 있어요.

::latest_gc_info

latest_gc_info → hash, latest_gc_info(hash) → hash, latest_gc_info(:major_by) → :malloc — 가장 최근 가비지 컬렉션에 관한 정보를 돌려줘요. 선택 인자 hash를 주면 그 해시를 덮어쓰고 돌려줘요(프로브 효과 방지용).

::malloc_allocated_size

malloc_allocated_size → Integer — malloc()이 할당한 메모리 크기를 돌려줘요. CALC_EXACT_MALLOC_SIZE로 빌드된 경우에만 사용 가능해요.

::malloc_allocations

malloc_allocations → Integer — malloc() 할당 횟수를 돌려줘요. CALC_EXACT_MALLOC_SIZE 빌드에서만 사용 가능해요.

::measure_total_time

measure_total_time → true/false — measure_total_time 플래그(기본: true)를 돌려줘요. 측정이 애플리케이션 성능에 영향을 줄 수 있다는 점을 유의하세요.

::measure_total_time=

measure_total_time = true/false — GC 시간 측정을 활성화해요. 결과는 GC.stat(:time)으로 얻을 수 있어요. 시간 측정은 약간의 성능 오버헤드가 있을 수 있어요.

::remove_stress_to_class

remove_stress_to_class(class[, ...]) — 주어진 클래스들의 인스턴스 할당 시 NoMemoryError를 더 이상 발생시키지 않아요.

::start

start(full_mark: true, immediate_mark: true, immediate_sweep: true) — 수동으로 비활성화돼 있어도 가비지 컬렉션을 시작해요.

  • full_mark — true면 major GC 사이클(모든 객체를 마킹), false면 minor GC 사이클(young 객체만 마킹)을 실행해요.
  • immediate_mark — true면 이 호출 동안 마킹을 완료하고, false면 이후 Ruby 코드 실행과 섞여 단계적으로 수행돼요. full_mark이 false면 immediate_mark 값과 무관하게 마킹은 항상 즉시 수행돼요.
  • immediate_sweep — true면 lazy sweep으로 이후 코드 실행과 섞여 수행될 수 있고, false면 이 호출 동안 완료돼요.

주의: 이 키워드 인자들은 구현·버전 의존적이라 미래 호환성이 보장되지 않고, 기반 구현이 지원하지 않으면 무시될 수 있어요.

::stat

stat → Hash, stat(hash) → Hash, stat(:key) → Numeric — GC에 관한 정보를 담은 해시를 돌려줘요. 해시 내용은 구현 특이적이고 예고 없이 바뀔 수 있어요. 주요 키:

  • count — 애플리케이션 시작 이후 실행된 GC 총 횟수(minor+major)
  • time — GC에 쓴 총 시간(밀리초)
  • heap_allocated_pages — :heap_eden_pages + :heap_tomb_pages
  • heap_sorted_length — 모든 페이지에 대한 참조를 담는 버퍼에 들어갈 수 있는 페이지 수
  • heap_allocatable_pages — 추가 GC 없이 할당할 수 있는 총 페이지 수
  • heap_available_slots — 모든 :heap_allocated_pages의 슬롯 총수
  • heap_live_slots — 살아 있는 객체를 담고 있는 슬롯 총수
  • heap_free_slots — 살아 있는 객체가 없는 슬롯 총수
  • heap_final_slots — 실행할 finalizer가 대기 중인 슬롯 총수
  • heap_marked_slots — 마지막 GC에서 마킹된 객체 총수
  • heap_eden_pages — 살아 있는 슬롯이 하나 이상 있는 페이지 수
  • heap_tomb_pages — 살아 있는 슬롯이 없는 페이지 수
  • total_allocated_pages — 시작 이후 할당된 누적 페이지 수
  • total_freed_pages — 시작 이후 해제된 누적 페이지 수
  • total_allocated_objects — 시작 이후 할당된 누적 객체 수
  • total_freed_objects — 시작 이후 해제된 누적 객체 수
  • malloc_increase_bytes — 객체용 힙에 할당된 메모리 양(GC마다 감소)
  • malloc_increase_bytes_limit — :malloc_increase_bytes가 이 한계를 넘으면 GC 트리거
  • minor_gc_count, major_gc_count — 시작 이후 minor/major GC 실행 횟수
  • compact_count — 시작 이후 실행된 압축 횟수
  • read_barrier_faults — 압축 중 읽기 배리어가 트리거된 횟수
  • total_moved_objects — 압축이 옮긴 객체 총수
  • remembered_wb_unprotected_objects — 쓰기 배리어가 없는 객체 수
  • old_objects — 적어도 3번의 GC에서 살아남은 살아 있는 old 객체 수
  • oldmalloc_increase_bytes, oldmalloc_increase_bytes_limit — old 객체용 힙 메모리 양과 그 한계

선택 인자 hash를 주면 덮어쓰고 돌려줘요(프로브 효과 방지). CRuby에서만 동작이 기대돼요.

::stat_heap

stat_heap → Hash, stat_heap(nil, hash) → Hash, stat_heap(heap_name) → Hash, stat_heap(heap_name, hash) → Hash, stat_heap(heap_name, :key) → Numeric — GC의 힙에 관한 정보를 돌려줘요. 첫 선택 인자 heap_name을 주고 nil이 아니면 특정 힙 정보를 담은 해시를, 아니면 힙 이름을 키로 하는 해시를 돌려줘요. 두 번째 인자가 해시면 덮어쓰고 반환하고, 심볼이면 그 힙의 값을 Numeric으로 돌려줘요. CRuby에서 heap_name은 Integer 타입이지만 다른 구현에서는 String일 수 있어요. 주요 키:

  • slot_size — 힙 슬롯 크기(바이트)
  • heap_allocatable_pages — 새 GC 사이클 없이 할당할 수 있는 페이지 수
  • heap_eden_pages, heap_eden_slots — eden 힙의 페이지 수와 슬롯 총수
  • heap_tomb_pages, heap_tomb_slots — tomb 힙의 페이지 수와 슬롯 총수(live 객체가 없는 페이지만 포함)
  • total_allocated_pages, total_freed_pages — 힙에서 할당/해제된 페이지 총수
  • force_major_gc_count — free 슬롯 부족으로 이 힙이 major GC를 강제 시작한 횟수
  • force_incremental_marking_finish_count — pooled 슬롯 부족으로 증분 마킹 완료를 강제한 횟수

::stress

stress → integer, true 또는 false — GC 스트레스 모드의 현재 상태를 돌려줘요.

::stress=

stress = flag → flag — GC 스트레스 모드를 갱신해요. 활성화되면 모든 메모리·객체 할당의 모든 GC 기회마다 GC가 호출돼요. 스트레스 모드를 켜면 성능이 떨어지므로 디버깅용이에요. flag는 true, false, 또는 다음 플래그를 비트-OR한 정수일 수 있어요.

0x01:: no major GC
0x02:: no immediate sweep
0x04:: full mark after malloc/calloc/realloc

::total_time

total_time → int — 측정된 GC 총 시간을 나노초 단위로 돌려줘요.

::verify_compaction_references

verify_compaction_references(toward: nil, double_heap: false) → hash — 압축 참조 일관성을 검증해요. 구현 특이적이에요. 이 함수는 모든 객체를 옮길 공간을 확보하도록 힙을 늘리고, 모든 것이 움직이도록 힙을 압축한 뒤 모든 참조를 갱신하고 full GC를 수행해요. 어떤 객체가 T_MOVED 객체에 대한 참조를 담고 있으면 그 객체가 마크 스택으로 밀려나 SEGV가 날 수 있어요.

::verify_internal_consistency

verify_internal_consistency → nil — 내부 일관성을 검증해요. 구현 특이적이에요. RGenGC가 지원되면 세대(generational) 일관성을 검사해요.

#garbage_collect (Public Instance Method)

garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true) — GC.start의 별칭이에요.