순환 가비지 수집 지원
*********************

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

컨테이너형을 만들려면, 형 객체의 "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)

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

int PyObject_IS_GC(PyObject *obj)

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

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

int PyObject_GC_IsTracked(PyObject *op)

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

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

   버전 3.9에 추가.

int PyObject_GC_IsFinalized(PyObject *op)

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

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

   버전 3.9에 추가.

void PyObject_GC_Del(void *op)

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

void PyObject_GC_UnTrack(void *op)

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

버전 3.8에서 변경: "_PyObject_GC_TRACK()"과 "_PyObject_GC_UNTRACK()"
매크로는 공용 C API에서 제거되었습니다.

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

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

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

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

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

   컨테이너 객체의 탐색 함수입니다. 구현은 *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"이어야 합
니다.

int (*inquiry)(PyObject *self)

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