# 순환 가비지 수집 지원

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

컨테이너형을 만들려면, 형 객체의 `tp_flags` 필드가 `Py_TPFLAGS_HAVE_GC`를 포함해야 하고 `tp_traverse` 처리기 구현을 제공해야 합니다. 형의 인스턴스가 가변이면, `tp_clear` 구현도 제공해야 합니다.

`Py_TPFLAGS_HAVE_GC`

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

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

1. 객체의 메모리는 `PyObject_GC_New()` 나 `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.

TYPE *`PyObject_GC_New`(TYPE, PyTypeObject *type)

  `PyObject_New()`와 유사하지만, `Py_TPFLAGS_HAVE_GC` 플래그가 설정된 컨테이너 객체를 위한 것.

TYPE *`PyObject_GC_NewVar`(TYPE, PyTypeObject *type, Py_ssize_t size)

  `PyObject_NewVar()`와 유사하지만, `Py_TPFLAGS_HAVE_GC` 플래그가 설정된 컨테이너 객체를 위한 것.

TYPE *`PyObject_GC_Resize`(TYPE, PyVarObject *op, Py_ssize_t newsize)

  `PyObject_NewVar()`에 의해 할당된 객체의 크기를 변경합니다. 크기가 조정된 객체나 실패하면 `NULL`을 반환합니다. op는 아직 수집기가 추적하지 않아야 합니다.

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.

  `PyObject_GC_New()` 나 `PyObject_GC_NewVar()`를 사용하여 객체에 할당된 메모리를 해제합니다.

void `PyObject_GC_UnTrack`(void *op)
  Part of the Stable ABI.

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

버전 3.8에서 변경: `_PyObject_GC_TRACK()`과 `_PyObject_GC_UNTRACK()` 매크로는 공용 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에 추가.