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

   Perform a collection.  The optional argument *generation* may be an
   integer specifying which generation to collect (from 0 to 2).  A
   "ValueError" is raised if the generation number is invalid. The sum
   of collected objects and uncollectable objects is returned.

   Calling "gc.collect(0)" will perform a GC collection on the young
   generation.

   Calling "gc.collect(1)" will perform a GC collection on the young
   generation and an increment of the old generation.

   Calling "gc.collect(2)" or "gc.collect()" performs a full
   collection

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

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

   버전 3.14에서 변경: "generation=1" performs an increment of
   collection.

gc.set_debug(flags)

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

gc.get_debug()

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

gc.get_objects(generation=None)

   Returns a list of all objects tracked by the collector, excluding
   the list returned. If *generation* is not "None", return only the
   objects as follows:

   * 0: All objects in the young generation

   * 1: No objects, as there is no generation 1 (as of Python 3.14)

   * 2: All objects in the old generation

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

   버전 3.14에서 변경: Generation 1 is removed

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

gc.get_stats()

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

   * "collections"는 이 세대가 수거된 횟수입니다.

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

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

   Added in version 3.4.

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

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

   The GC classifies objects into two generations depending on whether
   they have survived a collection. New objects are placed in the
   young generation. If an object survives a collection it is moved
   into the old generation.

   In order to decide when to run, the collector keeps track of the
   number of object allocations and deallocations since the last
   collection.  When the number of allocations minus the number of
   deallocations exceeds *threshold0*, collection starts. For each
   collection, all the objects in the young generation and some
   fraction of the old generation is collected.

   In the free-threaded build, the increase in process memory usage is
   also checked before running the collector.  If the memory usage has
   not increased by 10% since the last collection and the net number
   of object allocations has not exceeded 40 times *threshold0*, the
   collection is not run.

   The fraction of the old generation that is collected is
   **inversely** proportional to *threshold1*. The larger *threshold1*
   is, the slower objects in the old generation are collected. For the
   default value of 10, 1% of the old generation is scanned during
   each collection.

   *threshold2* is ignored.

   See Garbage collector design for more information.

   버전 3.14에서 변경: *threshold2* is ignored

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})
      True

   Added in version 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

   Added in version 3.9.

gc.freeze()

   가비지 수거기가 추적한 모든 객체를 고정합니다; 그들을 영구 세대
   (permanent generation)로 이동하고 향후 모든 수거에서 그들을 무시합
   니다.

   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.

   Added in version 3.7.

gc.unfreeze()

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

   Added in version 3.7.

gc.get_freeze_count()

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

   Added in version 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"에 나타날 때
      식별하고 지울 수 있도록 합니다.

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