gc — Garbage Collector interface

---

이 모듈은 선택적인 가비지 수거기에 대한 인터페이스를 제공합니다. 수거기를 비활성화하고, 수거 빈도를 조정하며, 디버깅 옵션을 설정하는 기능을 제공합니다. 또한 수거기가 발견했지만 해제할 수 없는 도달 불가능한 객체에 대한 액세스를 제공합니다. 수거기는 파이썬에서 이미 사용된 참조 횟수 추적을 보충하므로, 프로그램이 참조 순환을 만들지 않는다고 확신한다면 수거기를 비활성화 할 수 있습니다. 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.13에서 변경: 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.13)

• 2: All objects in the old generation

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

버전 3.13에서 변경: 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.

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.13에서 변경: 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()

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.

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에서 변경: 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에 나타날 때 식별하고 지울 수 있도록 합니다.

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