"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")
   으로 인해, 일부 자유 목록에서 모든 항목이 해제되지는 않을 수 있습니
   다.

   The effect of calling "gc.collect()" while the interpreter is
   already performing a collection is undefined.

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()

   Freeze all the objects tracked by the garbage collector; move them
   to a permanent generation and ignore them in all the future
   collections.

   If a process will "fork()" without "exec()", avoiding unnecessary
   copy-on-write in child processes will maximize memory sharing and
   reduce overall memory usage. This requires both avoiding creation
   of freed "holes" in memory pages in the parent process and ensuring
   that GC collections in child processes won't touch the "gc_refs"
   counter of long-lived objects originating in the parent process. To
   accomplish both, call "gc.disable()" early in the parent process,
   "gc.freeze()" right before "fork()", and "gc.enable()" early in
   child processes.

   버전 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에서 변경: Following **PEP 442**, objects with a
   "__del__()" method don't end up in "gc.garbage" anymore.

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