支持循环垃圾收集 ¶

Python’s support for detecting and collecting garbage which involves circular references requires support from object types which are “containers” for other objects which may also be containers. Types which do not store references to other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection.

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

Objects with a type with this flag set must conform with the rules documented here. For convenience these objects will be referred to as container objects.

Constructors for container types must conform to two rules:

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

2. Once all the fields which may contain references to other containers are initialized, it must call PyObject_GC_Track() .

Similarly, the deallocator for the object must conform to a similar pair of rules:

1. Before fields which refer to other containers are invalidated, PyObject_GC_UnTrack() must be called.

2. The object’s memory must be deallocated using 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 标志。

PyObject_GC_New ( TYPE , typeobj ) ¶

Analogous to PyObject_New but for container objects with the Py_TPFLAGS_HAVE_GC 设置标志。

PyObject_GC_NewVar ( TYPE , typeobj , size ) ¶

Analogous to PyObject_NewVar but for container objects with the Py_TPFLAGS_HAVE_GC 设置标志。

PyObject * PyUnstable_Object_GC_NewWithExtraData ( PyTypeObject * type , size_t extra_size ) ¶

这为 Unstable API . It may change without warning in minor releases.

Analogous to PyObject_GC_New but allocates extra_size bytes at the end of the object (at offset tp_basicsize ). The allocated memory is initialized to zeros, except for the Python object header .

The extra data will be deallocated with the object, but otherwise it is not managed by Python.

警告

The function is marked as unstable because the final mechanism for reserving extra data after an instance is not yet decided. For allocating a variable number of fields, prefer using PyVarObject and tp_itemsize 代替。

3.12 版添加。

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 当故障时。

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

属于 稳定 ABI (应用程序二进制接口) .

Adds the object op to the set of container objects tracked by the collector. The collector can run at unexpected times so objects must be valid while being tracked. This should be called once all the fields followed by the tp_traverse handler become valid, usually near the end of the constructor.

int PyObject_IS_GC ( PyObject * obj ) ¶

Returns non-zero if the object implements the garbage collector protocol, otherwise returns 0.

The object cannot be tracked by the garbage collector if this function returns 0.

int PyObject_GC_IsTracked ( PyObject * op ) ¶

属于 稳定 ABI (应用程序二进制接口) since version 3.9.

Returns 1 if the object type of op implements the GC protocol and op is being currently tracked by the garbage collector and 0 otherwise.

This is analogous to the Python function gc.is_tracked() .

Added in version 3.9.