Extending and Embedding Python, Release 3.9.5 17 2.1. Extending Python with C or C++ to any objects in a reference cycle, or referenced from the objects in the cycle, even though there are no further references to the cycle itself. The cycle detector is able to detect garbage cycles and can reclaim them. The$_{gc}$module exposes a way to run the detector (the collect() function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle detector is considered an optional component; though it is included by default, it can be disabled at build time using the$_{--without-cycle-gc}$ option to the$_{configure}$script on Unix platforms (including Mac OS X). If the cycle detector is disabled in this way, the$_{gc}$module will not be available. There are two macros, Py_INCREF(x) and Py_DECREF(x) , which handle the incrementing and decrementing of the reference count. Py_DECREF() also frees the object when the count reaches zero. For flexibility, it doesn’t call$_{free()}$ directly — rather, it makes a call through a function pointer in the object’s type object . For this purpose (and others), every object also contains a pointer to its type object. The big question now remains: when to use$_{Py_INCREF(x)}$and$_{Py_DECREF(x)}$ ? Let’s first introduce some terms. Nobody “owns” an object; however, you can own a reference to an object. An object’s reference count is now defined as the number of owned references to it. The owner of a reference is responsible for calling Py_DECREF() when the reference is no longer needed. Ownership of a reference can be transferred. There are three ways to dispose of an owned reference: pass it on, store it, or call Py_DECREF() . Forgetting to dispose of an owned reference creates a memory leak. It is also possible to borrow 2 a reference to an object. The borrower of a reference should not call$_{Py_DECREF()}$ . The borrower must not hold on to the object longer than the owner from which it was borrowed. Using a borrowed reference after the owner has disposed of it risks using freed memory and should be avoided completely$^{3}$. The advantage of borrowing over owning a reference is that you don’t need to take care of disposing of the reference on all possible paths through the code — in other words, with a borrowed reference you don’t run the risk of leaking when a premature exit is taken. The disadvantage of borrowing over owning is that there are some subtle situations where in seemingly correct code a borrowed reference can be used after the owner from which it was borrowed has in fact disposed of it. A borrowed reference can be changed into an owned reference by calling$_{Py_INCREF()}$ . This does not affect the status of the owner from which the reference was borrowed — it creates a new owned reference, and gives full owner responsibilities (the new owner must dispose of the reference properly, as well as the previous owner). Whenever an object reference is passed into or out of a function, it is part of the function’s interface specification whether ownership is transferred with the reference or not. Most functions that return a reference to an object pass on ownership with the reference. In particular, all functions whose function it is to create a new object, such as$_{PyLong_FromLong()}$ and$_{Py_BuildValue()}$ , pass own- ership to the receiver. Even if the object is not actually new, you still receive ownership of a new reference to that object. For instance,$_{PyLong_FromLong()}$ maintains a cache of popular values and can return a reference to a cached item. Many functions that extract objects from other objects also transfer ownership with the reference, for in- stance PyObject_GetAttrString() . The picture is less clear, here, however, since a few com- mon routines are exceptions: PyTuple_GetItem() , PyList_GetItem() , PyDict_GetItem() , and PyDict_GetItemString() all return references that you borrow from the tuple, list or dictionary. The function$_{PyImport_AddModule()}$ also returns a borrowed reference, even though it may actually create the object it returns: this is possible because an owned reference to the object is stored in$_{sys.modules}$ . When you pass an object reference into another function, in general, the function borrows the reference from you — if it needs to store it, it will use$_{Py_INCREF()}$to become an independent owner. There are exactly two important Ownership Rules 3 Checking that the reference count is at least 1 does not work — the reference count itself could be in freed memory and may thus be reused for another object! 2 The metaphor of “borrowing” a reference is not completely correct: the owner still has a copy of the reference. Reference Counting in Python