순환 가비지 수집 지원

순환 참조를 포함하는 가비지를 탐지하고 수집하는 파이썬의 지원은 역시 컨테이너일 수 있는 다른 객체의 “컨테이너” 인 객체 형의 지원이 필요합니다. 다른 객체에 대한 참조를 저장하지 않거나, 원자 형(가령 숫자나 문자열)에 대한 참조만 저장하는 형은 가비지 수집에 대한 어떤 명시적인 지원을 제공할 필요가 없습니다.

To create a container type, the tp_flags field of the type object must include the Py_TPFLAGS_HAVE_GC and provide an implementation of the tp_traverse handler. If instances of the type are mutable, a tp_clear implementation must also be provided.

Py_TPFLAGS_HAVE_GC

이 플래그가 설정된 형의 객체는 여기에 설명된 규칙을 준수해야 합니다. 편의를 위해 이러한 객체를 컨테이너 객체라고 하겠습니다.

컨테이너형의 생성자는 두 가지 규칙을 준수해야 합니다:

1. The memory for the object must be allocated using PyObject_GC_New or PyObject_GC_NewVar.

2. 다른 컨테이너에 대한 참조를 포함할 수 있는 모든 필드가 초기화되면, PyObject_GC_Track()를 호출해야 합니다.

마찬가지로, 객체의 할당해제자(deallocator)는 비슷한 규칙 쌍을 준수해야 합니다:

1. 다른 컨테이너를 참조하는 필드가 무효화 되기 전에, PyObject_GC_UnTrack()를 호출해야 합니다.

2. 객체의 메모리는 PyObject_GC_Del()를 사용하여 할당 해제되어야 합니다.

   경고

   If a type adds the Py_TPFLAGS_HAVE_GC, then it must implement at least a tp_traverse handler or explicitly use one from its subclass or subclasses.

   When calling PyType_Ready() or some of the APIs that indirectly call it like PyType_FromSpecWithBases() or PyType_FromSpec() the interpreter will automatically populate the tp_flags, tp_traverse and tp_clear fields if the type inherits from a class that implements the garbage collector protocol and the child class does not include the Py_TPFLAGS_HAVE_GC flag.

PyObject_GC_New(TYPE, typeobj)

Analogous to PyObject_New but for container objects with the Py_TPFLAGS_HAVE_GC flag set.

PyObject_GC_NewVar(TYPE, typeobj, size)

Analogous to PyObject_NewVar but for container objects with the Py_TPFLAGS_HAVE_GC flag set.

PyObject_GC_Resize(TYPE, op, newsize)

Resize an object allocated by PyObject_NewVar. Returns the resized object of type TYPE* (refers to any C type) or NULL on failure.

op must be of type PyVarObject* and must not be tracked by the collector yet. newsize must be of type Py_ssize_t.

void PyObject_GC_Track(PyObject *op)

Part of the Stable ABI.

수집기가 추적하는 컨테이너 객체 집합에 객체 op를 추가합니다. 수집기는 예기치 않은 시간에 실행될 수 있으므로 추적되는 동안 객체가 유효해야 합니다. tp_traverse 처리기가 탐색하는 모든 필드가 유효해지면 호출해야 합니다, 보통 생성자의 끝부분 근처입니다.

int PyObject_IS_GC(PyObject *obj)

객체가 가비지 수거기 프로토콜을 구현하면 0이 아닌 값을 반환하고, 그렇지 않으면 0을 반환합니다.

이 함수가 0을 반환하면 가비지 수거기가 객체를 추적할 수 없습니다.

int PyObject_GC_IsTracked(PyObject *op)

Part of the Stable ABI since version 3.9.

op의 객체 형이 GC 프로토콜을 구현하고 op가 현재 가비지 수거기가 추적 중이면 1을 반환하고 그렇지 않으면 0을 반환합니다.

이것은 파이썬 함수 gc.is_tracked()에 해당합니다.

버전 3.9에 추가.

int PyObject_GC_IsFinalized(PyObject *op)

Part of the Stable ABI since version 3.9.

op의 객체 형이 GC 프로토콜을 구현하고 가비지 수거기가 op를 이미 파이널라이즈 했으면 1을 반환하고 그렇지 않으면 0을 반환합니다.

이것은 파이썬 함수 gc.is_finalized()에 해당합니다.

버전 3.9에 추가.

void PyObject_GC_Del(void *op)

Part of the Stable ABI.

Releases memory allocated to an object using PyObject_GC_New or PyObject_GC_NewVar.

void PyObject_GC_UnTrack(void *op)

Part of the Stable ABI.

수집기가 추적하는 컨테이너 객체 집합에서 op 객체를 제거합니다. PyObject_GC_Track()를 이 객체에 대해 다시 호출하여 추적 객체 집합에 다시 추가할 수 있음에 유의하십시오. 할당해제자(tp_dealloc 처리기)는 tp_traverse 처리기에서 사용하는 필드가 무효화 되기 전에 객체에 대해 이 함수를 호출해야 합니다.

버전 3.8에서 변경: The _PyObject_GC_TRACK() and _PyObject_GC_UNTRACK() macros have been removed from the public C API.

tp_traverse 처리기는 다음과 같은 형의 함수 매개 변수를 받아들입니다:

typedef int (*visitproc)(PyObject *object, void *arg)

Part of the Stable ABI.

tp_traverse 처리기에 전달되는 방문자 함수의 형. 이 함수는 탐색하는 객체를 object로, tp_traverse 처리기의 세 번째 매개 변수를 arg로 호출되어야 합니다. 파이썬 코어는 순환 가비지 탐지를 구현하기 위해 여러 방문자 함수를 사용합니다; 사용자가 자신의 방문자 함수를 작성해야 할 필요는 없습니다.

tp_traverse 처리기는 다음 형이어야 합니다:

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

Part of the Stable ABI.

컨테이너 객체의 탐색 함수입니다. 구현은 self에 직접 포함된 각 객체에 대해 visit 함수를 호출해야 하며, visit에 대한 매개 변수는 포함된 객체와 처리기로 전달된 arg 값입니다. visit 함수는 NULL object 인자로 호출하면 안 됩니다. visit가 0이 아닌 값을 반환하면 그 값이 즉시 반환되어야 합니다.

tp_traverse 처리기 작성을 단순화하기 위해, Py_VISIT() 매크로가 제공됩니다. 이 매크로를 사용하려면, tp_traverse 구현은 인자의 이름을 정확히 visit 와 arg로 지정해야 합니다:

void Py_VISIT(PyObject *o)

o가 NULL이 아니면, o 와 arg 인자로 visit 콜백을 호출합니다. visit가 0이 아닌 값을 반환하면, 그것을 반환합니다. 이 매크로를 사용하면, tp_traverse 처리기가 다음과 같아집니다:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

tp_clear 처리기는 inquiry 형이거나 객체가 불변이면 NULL이어야 합니다.

typedef int (*inquiry)(PyObject *self)

Part of the Stable ABI.

참조 순환을 생성했을 수 있는 참조를 삭제합니다. 불변 객체는 참조 순환을 직접 생성할 수 없으므로, 이 메서드를 정의 할 필요가 없습니다. 이 메서드를 호출한 후에도 객체가 유효해야 합니다 (단지 참조에 대해 Py_DECREF()를 호출하지 마십시오). 이 객체가 참조 순환에 참여하고 있음을 수집기가 감지하면 이 메서드를 호출합니다.

Controlling the Garbage Collector State

The C-API provides the following functions for controlling garbage collection runs.

Py_ssize_t PyGC_Collect(void)

Part of the Stable ABI.

Perform a full garbage collection, if the garbage collector is enabled. (Note that gc.collect() runs it unconditionally.)

Returns the number of collected + unreachable objects which cannot be collected. If the garbage collector is disabled or already collecting, returns 0 immediately. Errors during garbage collection are passed to sys.unraisablehook. This function does not raise exceptions.

int PyGC_Enable(void)

Part of the Stable ABI since version 3.10.

Enable the garbage collector: similar to gc.enable(). Returns the previous state, 0 for disabled and 1 for enabled.

버전 3.10에 추가.

int PyGC_Disable(void)

Part of the Stable ABI since version 3.10.

Disable the garbage collector: similar to gc.disable(). Returns the previous state, 0 for disabled and 1 for enabled.

버전 3.10에 추가.

int PyGC_IsEnabled(void)

Part of the Stable ABI since version 3.10.

Query the state of the garbage collector: similar to gc.isenabled(). Returns the current state, 0 for disabled and 1 for enabled.

버전 3.10에 추가.