third_party/cython/src/Cython/Includes/cpython/ref.pxd

   1 cdef extern from "Python.h":
   2     ctypedef struct PyTypeObject
   3     ctypedef struct PyObject:
   4         Py_ssize_t ob_refcnt
   5         PyTypeObject *ob_type
   6     cdef PyTypeObject *Py_TYPE(object)
   7
   8
   9     #####################################################################
  10     # 3. Reference Counts
  11     #####################################################################
  12     # The macros in this section are used for managing reference counts of Python objects.
  13     void Py_INCREF(object o)
  14     # Increment the reference count for object o. The object must not
  15     # be NULL; if you aren't sure that it isn't NULL, use
  16     # Py_XINCREF().
  17
  18     void Py_XINCREF(PyObject* o)
  19     # Increment the reference count for object o. The object may be NULL, in which case the macro has no effect.
  20
  21     void Py_DECREF(object o)
  22     # Decrement the reference count for object o. The object must not
  23     # be NULL; if you aren't sure that it isn't NULL, use
  24     # Py_XDECREF(). If the reference count reaches zero, the object's
  25     # type's deallocation function (which must not be NULL) is
  26     # invoked.
  27
  28     # Warning: The deallocation function can cause arbitrary Python
  29     # code to be invoked (e.g. when a class instance with a __del__()
  30     # method is deallocated). While exceptions in such code are not
  31     # propagated, the executed code has free access to all Python
  32     # global variables. This means that any object that is reachable
  33     # from a global variable should be in a consistent state before
  34     # Py_DECREF() is invoked. For example, code to delete an object
  35     # from a list should copy a reference to the deleted object in a
  36     # temporary variable, update the list data structure, and then
  37     # call Py_DECREF() for the temporary variable.
  38
  39     void Py_XDECREF(PyObject* o)
  40     # Decrement the reference count for object o. The object may be
  41     # NULL, in which case the macro has no effect; otherwise the
  42     # effect is the same as for Py_DECREF(), and the same warning
  43     # applies.
  44
  45     void Py_CLEAR(PyObject* o)
  46     # Decrement the reference count for object o. The object may be
  47     # NULL, in which case the macro has no effect; otherwise the
  48     # effect is the same as for Py_DECREF(), except that the argument
  49     # is also set to NULL. The warning for Py_DECREF() does not apply
  50     # with respect to the object passed because the macro carefully
  51     # uses a temporary variable and sets the argument to NULL before
  52     # decrementing its reference count.
  53     # It is a good idea to use this macro whenever decrementing the
  54     # value of a variable that might be traversed during garbage
  55     # collection.
  56