"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* 매개 변수.

   인자 "generation"으로 감사 이벤트 "gc.get_objects"를 발생시킵니다.

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()"를 사용하지
     마십시오.

   인자 "objs"로 감사 이벤트 "gc.get_referrers"를 발생시킵니다.

gc.get_referents(*objs)

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

   인자 "objs"로 감사 이벤트 "gc.get_referents"를 발생시킵니다.

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.is_finalized(obj)

   주어진 객체가 가비지 수거기에 의해 파이널라이즈 되었으면 "True"를,
   그렇지 않으면 "False"를 반환합니다.

      >>> x = None
      >>> class Lazarus:
      ...     def __del__(self):
      ...         global x
      ...         x = self
      ...
      >>> lazarus = Lazarus()
      >>> gc.is_finalized(lazarus)
      False
      >>> del lazarus
      >>> gc.is_finalized(x)
      True

   버전 3.9에 추가.

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"과 같습니다).
