# `gc` — 가비지 수거기 인터페이스

이 모듈은 선택적인 가비지 수거기에 대한 인터페이스를 제공합니다. 수거기를 비활성화하고, 수거 빈도를 조정하며, 디버깅 옵션을 설정하는 기능을 제공합니다. 또한 수거기가 발견했지만 해제할 수 없는 도달 불가능한 객체에 대한 액세스를 제공합니다. 수거기는 파이썬에서 이미 사용된 참조 횟수 추적을 보충하므로, 프로그램이 참조 순환을 만들지 않는다고 확신한다면 수거기를 비활성화 할 수 있습니다. `gc.disable()`을 호출하여 자동 수거를 비활성화 할 수 있습니다. 누수가 발생하는 프로그램을 디버그하려면, `gc.set_debug(gc.DEBUG_LEAK)`을 호출하십시오. 이것은 `gc.DEBUG_SAVEALL`을 포함하므로, 가비지 수거된 객체가 검사를 위해 gc.garbage에 저장되도록 함에 유의하십시오.

`gc` 모듈은 다음 함수를 제공합니다:

`gc.``enable`()

  자동 가비지 수거를 활성화합니다.

`gc.``disable`()

  자동 가비지 수거를 비활성화합니다.

`gc.``isenabled`()

  자동 수거가 활성화되었으면 `True`를 반환합니다.

`gc.``collect`(generation=2)

  인자가 없으면, 전체 수거를 실행합니다. 선택적 인자 generation은 어떤 세대를 수거할지 지정하는 정수(0에서 2)일 수 있습니다. 세대 번호가 유효하지 않으면 `ValueError`가 발생합니다. 발견된 도달할 수 없는(unreachable) 객체의 수가 반환됩니다.

  여러 내장형을 위해 유지되는 자유 목록(free list)은 전체 수거나 최고 세대(2)의 수거가 실행될 때마다 지워집니다. 특정 구현(특히 `float`)으로 인해, 일부 자유 목록에서 모든 항목이 해제되지는 않을 수 있습니다.

`gc.``set_debug`(flags)

  가비지 수거 디버깅 플래그를 설정합니다. 디버깅 정보가 `sys.stderr`에 기록됩니다. 디버깅을 제어하기 위해 비트 연산을 사용하여 결합할 수 있는 디버깅 플래그 목록은 아래를 참조하십시오.

`gc.``get_debug`()

  현재 설정된 디버깅 플래그를 반환합니다.

`gc.``get_objects`(generation=None)

  반환된 리스트를 제외하고, 수거기에서 추적한 모든 객체의 리스트를 반환합니다. generation이 None이 아니면, 수거기가 추적한 해당 세대에 있는 객체만 반환합니다.

  버전 3.8에서 변경: 새로운 generation 매개 변수.

  Raises an auditing event `gc.get_objects` with argument `generation`.

`gc.``get_stats`()

  인터프리터가 시작된 이후의 수거 통계를 포함하는 세 개의 세대별 딕셔너리의 리스트를 반환합니다. 향후 키 수는 변경될 수 있지만, 현재 각 딕셔너리에는 다음과 같은 항목이 포함됩니다:

  - `collections`는 이 세대가 수거된 횟수입니다.

  - `collected`는 이 세대 내에서 수거된 총 객체 수입니다.

  - `uncollectable`은 이 세대 내에서 수거할 수 없는 (따라서 `garbage` 리스트로 이동된) 것으로 확인된 총 객체 수입니다.

  버전 3.4에 추가.

`gc.``set_threshold`(threshold0[, threshold1[, threshold2]])

  가비지 수거 임곗값(수거 빈도)을 설정합니다. threshold0을 0으로 설정하면 수거가 비활성화됩니다.

  GC는 얼마나 많은 수거 스위프(sweep)에서 살아남았는지에 따라 객체를 세 가지 세대로 분류합니다. 새로운 객체는 가장 어린 세대(`0`세대)에 배치됩니다. 객체가 수거에서 살아남으면 다음 세대로 이동합니다. `2` 가 가장 나이 든 세대이므로, 이 세대의 객체는 수거 후에도 여기에 남아 있습니다. 언제 실행할지를 결정하기 위해, 수거기는 마지막 수거 이후의 객체 할당과 할당 해제 수를 추적합니다. 할당 횟수에서 할당 해제 횟수를 뺀 값이 threshold0를 초과하면 수거가 시작됩니다. 처음에는 `0`세대만 검사합니다. `1` 세대를 검사한 후로, `0`세대를 threshold1 회를 초과하여 검사했으면, `1` 세대도 검사됩니다. 3세대에서는 상황이 좀 더 복잡해졌습니다. 자세한 내용은 Collecting the oldest generation을 참조하세요.

`gc.``get_count`()

  현재 수거 횟수를 `(count0, count1, count2)`의 튜플로 반환합니다.

`gc.``get_threshold`()

  현재 수거 임곗값을 `(threshold0, threshold1, threshold2)`의 튜플로 반환합니다.

`gc.``get_referrers`(*objs)

  objs에 있는 것을 직접 참조하는 객체의 리스트를 반환합니다. 이 함수는 가비지 수거를 지원하는 컨테이너만 찾습니다; 다른 객체를 참조하지만, 가비지 수거를 지원하지 않는 확장형은 찾을 수 없습니다.

  이미 참조 해제되었지만, 순환에 참여해서 가비지 수거기에 의해 아직 수거되지 않은 객체는 결과 참조자(referrer)에 나열될 수 있음에 유의하십시오. 현재 살아있는 객체만 가져오려면, `get_referrers()`를 호출하기 전에 `collect()`를 호출하십시오.

  경고

  `get_referrers()`에서 반환된 객체를 사용할 때는, 그중 일부는 아직 생성 중이라서 일시적으로 유효하지 않은 상태일 수 있기 때문에 주의해야 합니다. 디버깅 이외의 목적으로 `get_referrers()`를 사용하지 마십시오.

  Raises an auditing event `gc.get_referrers` with argument `objs`.

`gc.``get_referents`(*objs)

  인자로 제공된 객체가 직접 참조하는 객체의 리스트를 반환합니다. 반환된 피 참조자(referent)는 인자의 C 수준 `tp_traverse` 메서드(있다면)가 방문한 객체이며, 실제로 직접 도달할 수 있는 모든 객체는 아닐 수 있습니다. `tp_traverse` 메서드는 가비지 수거를 지원하는 객체에서만 지원되며, 순환에 참여하는 객체만 방문하면 됩니다. 그래서, 예를 들어, 인자에서 정수에 직접 도달 할 수 있으면, 해당 정수 객체가 결과 목록에 나타날 수도 그렇지 않을 수도 있습니다.

  Raises an auditing event `gc.get_referents` with argument `objs`.

`gc.``is_tracked`(obj)

  가비지 수거기가 객체를 현재 추적하고 있으면 `True`를, 그렇지 않으면 `False`를 반환합니다. 일반적인 규칙으로, 원자 형(atomic type)의 인스턴스는 추적하지 않고, 원자 형이 아닌 인스턴스(컨테이너, 사용자 정의 객체…)는 추적합니다. 그러나 간단한 인스턴스의 가비지 수거기 크기를 줄이기 위해 일부 형별 최적화가 존재할 수 있습니다 (예를 들어, 원자적 키와 값만 포함하는 딕셔너리):

      >>> gc.is_tracked(0)
      False
      >>> gc.is_tracked("a")
      False
      >>> gc.is_tracked([])
      True
      >>> gc.is_tracked({})
      False
      >>> gc.is_tracked({"a": 1})
      False
      >>> gc.is_tracked({"a": []})
      True

  버전 3.1에 추가.

`gc.``freeze`()

  gc가 추적한 모든 객체를 고정합니다 - 그들을 영구 세대(permanent generation)로 이동하고 향후 모든 수거를 무시합니다. gc를 쓸 때 복사(copy-on-write) 친화적으로 만들거나 수거 속도를 높이기 위해 POSIX fork() 호출 전에 사용할 수 있습니다. 또한 POSIX fork() 호출 이전의 수거는 미래의 할당을 위해 쓸 때 복사(copy-on-write)를 일으킬 수 있는 페이지를 해제할 수 있기 때문에, 부모 프로세스에서 gc를 비활성화하고 포크 전에 고정(freeze)한 후 자식 프로세스에서 gc를 활성화하는 것이 좋습니다.

  버전 3.7에 추가.

`gc.``unfreeze`()

  영구 세대(permanent generation)의 객체를 고정 해제하고, 가장 나이 든 세대로 되돌립니다.

  버전 3.7에 추가.

`gc.``get_freeze_count`()

  영구 세대(permanent generation)에 있는 객체 수를 반환합니다.

  버전 3.7에 추가.

다음 변수가 전용 액세스로 제공됩니다 (값을 변경할 수는 있지만, 다시 연결해서는 안 됩니다):

`gc.``garbage`

  수거기가 발견했지만 해제할 수 없는 도달 불가능한 객체의 리스트 (수거할 수 없는 객체). 파이썬 3.4부터, `NULL`이 아닌 `tp_del` 슬롯이 있는 C 확장형의 인스턴스를 사용할 때를 제외하고, 이 리스트는 대체로 비어 있어야 합니다.

  `DEBUG_SAVEALL`이 설정되면, 도달할 수 없는 모든 객체가 해제되지 않고 이 목록에 추가됩니다.

  버전 3.2에서 변경: 인터프리터 종료 시 이 목록이 비어 있지 않으면, `ResourceWarning`이 발생하는데, 기본적으로 조용(silent)합니다. `DEBUG_UNCOLLECTABLE`이 설정되면, 추가로 모든 수거 할 수 없는 객체가 인쇄됩니다.

  버전 3.4에서 변경: PEP 442에 따라, `__del__()` 메서드를 가진 객체는 더는 `gc.garbage`에 들어가지 않습니다.

`gc.``callbacks`

  수거 전후에 가비지 수거기가 호출할 콜백의 리스트입니다. 콜백은 두 인자로 호출됩니다, phase와 info.

  phase는 다음 두 값 중 하나일 수 있습니다:

  > 《start》: 가비지 수거를 시작하려고 합니다.

  > 《stop》: 가비지 수거가 완료되었습니다.

  info는 콜백에 추가 정보를 제공하는 딕셔너리입니다. 현재 다음 키가 정의되어 있습니다:

  > 《generation》: 수거되는 가장 나이 든 세대.

  > 《collected》: phase가 《stop》일 때, 성공적으로 수거된 객체 수.

  > 《uncollectable》: phase가 《stop》일 때, 수거할 수 없어서 `garbage`에 들어간 객체 수.

  응용 프로그램은 이 리스트에 자체 콜백을 추가 할 수 있습니다. 주요 사용 사례는 다음과 같습니다:

  > 다양한 세대가 수거되는 빈도와 수거에 걸린 시간과 같은 가비지 수거에 대한 통계 수집.

  > 응용 프로그램이 자신의 수거할 수 없는 형이 `garbage`에 나타날 때 식별하고 지울 수 있도록 합니다.

  버전 3.3에 추가.

`set_debug()`와 함께 사용하기 위해 다음 상수가 제공됩니다:

`gc.``DEBUG_STATS`

  수거 중 통계를 인쇄합니다. 이 정보는 수거 빈도를 조정할 때 유용 할 수 있습니다.

`gc.``DEBUG_COLLECTABLE`

  발견된 수거 가능한 객체에 대한 정보를 인쇄합니다.

`gc.``DEBUG_UNCOLLECTABLE`

  발견된 수거 할 수 없는 객체에 대한 정보를 인쇄합니다 (도달 할 수 있지만, 수거기가 해제할 수 없는 객체). 이 객체는 `garbage` 리스트에 추가됩니다.

  버전 3.2에서 변경: 인터프리터 종료 시에 `garbage` 리스트가 비어있지 않으면 내용을 인쇄하기도 합니다.

`gc.``DEBUG_SAVEALL`

  설정하면, 발견된 모든 도달할 수 없는 객체를 해제하는 대신 garbage에 추가합니다. 누수가 있는 프로그램을 디버깅하는 데 유용 할 수 있습니다.

`gc.``DEBUG_LEAK`

  수거기가 누수가 있는 프로그램에 대한 정보를 인쇄하도록 하는 데 필요한 디버깅 플래그 (`DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL`과 같습니다).