cython

1
from .object cimport PyObject, PyTypeObject, Py_TYPE  # legacy imports for re-export
2

3
cdef extern from "Python.h":
4
    #####################################################################
5
    # 3. Reference Counts
6
    #####################################################################
7
    # The macros in this section are used for managing reference counts of Python objects.
8
    void Py_INCREF(object o)
9
    # Increment the reference count for object o. The object must not
10
    # be NULL; if you aren't sure that it isn't NULL, use
11
    # Py_XINCREF().
12

13
    void Py_XINCREF(PyObject* o)
14
    # Increment the reference count for object o. The object may be NULL, in which case the macro has no effect.
15

16
    void Py_DECREF(object o)
17
    # Decrement the reference count for object o. The object must not
18
    # be NULL; if you aren't sure that it isn't NULL, use
19
    # Py_XDECREF(). If the reference count reaches zero, the object's
20
    # type's deallocation function (which must not be NULL) is
21
    # invoked.
22

23
    # Warning: The deallocation function can cause arbitrary Python
24
    # code to be invoked (e.g. when a class instance with a __del__()
25
    # method is deallocated). While exceptions in such code are not
26
    # propagated, the executed code has free access to all Python
27
    # global variables. This means that any object that is reachable
28
    # from a global variable should be in a consistent state before
29
    # Py_DECREF() is invoked. For example, code to delete an object
30
    # from a list should copy a reference to the deleted object in a
31
    # temporary variable, update the list data structure, and then
32
    # call Py_DECREF() for the temporary variable.
33

34
    void Py_XDECREF(PyObject* o)
35
    # Decrement the reference count for object o. The object may be
36
    # NULL, in which case the macro has no effect; otherwise the
37
    # effect is the same as for Py_DECREF(), and the same warning
38
    # applies.
39

40
    void Py_CLEAR(PyObject* o)
41
    # Decrement the reference count for object o. The object may be
42
    # NULL, in which case the macro has no effect; otherwise the
43
    # effect is the same as for Py_DECREF(), except that the argument
44
    # is also set to NULL. The warning for Py_DECREF() does not apply
45
    # with respect to the object passed because the macro carefully
46
    # uses a temporary variable and sets the argument to NULL before
47
    # decrementing its reference count.
48
    # It is a good idea to use this macro whenever decrementing the
49
    # value of a variable that might be traversed during garbage
50
    # collection.
51

52
    Py_ssize_t Py_REFCNT(object o)
53
    # Get the reference count of the Python object o.
54

55
    # Note that the returned value may not actually reflect how many
56
    # references to the object are actually held. For example, some
57
    # objects are “immortal” and have a very high refcount that does not
58
    # reflect the actual number of references. Consequently, do not rely
59
    # on the returned value to be accurate, other than a value of 0 or
60
    # 1.
61

62
    Py_ssize_t _Py_REFCNT "Py_REFCNT" (PyObject *ptr)
63
    # Get the reference count for the PyObject pointer ptr.
64

65
    # This is useful when it would be awkward to create an owned reference just
66
    # to get the reference count. See the note for Py_REFCNT above about the
67
    # accuracy of reference counts.
68