Beginning Python - From Novice to Professional

366 CHAPTER 17 ■ EXTENDING PYTHON
Reference Counting
If you haven’t worked with it before, reference counting will probably be one of the most foreign
concepts you’ll encounter in this section, although it’s not really all that complicated. In Python,
memory used is dealt with automatically—you just create objects, and they disappear when
you no longer use them. In C, this isn’t the case: you have to explicitly deallocate objects (or,
rather, chunks of memory) that you’re no longer using. If you don’t, your program may start
hogging more and more memory, and you have what’s called a memory leak.
When writing Python extensions, you have access to the same tools Python uses “under
the hood” to manage memory, one of which is reference counting. The idea is that as long as
some parts of your code have references to an object (that is, in C-speak, pointers pointing to
it), it should not be deallocated. However, once the number of references to an object hits zero,
the number can no longer increase—there is no code that can create new references to it, and
it’s just “free floating” in memory.
At this point, it’s safe to deallocate it. Reference counting automates this process: You
follow a set of rules where you increment or decrement the reference count for an object under
various circumstances (through a part of the Python API), and if the count ever goes to zero,
the object is automatically deallocated. This means that no single piece of code has the sole
responsibility for managing an object. You can create an object, return it from a function, and
forget about it, safe in the knowledge that it will disappear when it is no longer needed.
You use two macros called Py_INCREF and Py_DECREF to increment and decrement the
reference count of an object, respectively. You can find detailed information about how to use
these in the Python documentation (http://python.org/doc/ext/refcounts.html); here is the
gist of it:
• You can’t own an object, but you can own a reference to it. The reference count of an
object is the number of owned references to it.
• If you own a reference, you are responsible for calling Py_DECREF when you no longer
need the reference.
• If you borrow a reference temporarily, you should not call Py_DECREF when you’re
finished with the object; that’s the responsibility of the owner. (You should certainly
never use a borrowed reference after the owner has disposed of it. See the “Thin Ice”
sections in the documentation for some more advice on staying safe.)
• You can change a borrowed reference into an owned reference by calling Py_INCREF.
This creates a new owned reference; the original owner still owns the original reference.
• When you receive an object as a parameter, it’s up to you whether you want the ownership
of its reference transferred (for example, if you’re going to store it somewhere) or
whether you simply want to borrow it. This should be documented clearly. If your function
is called from Python, it’s safe to simply borrow—the object will live for the duration
of the function call. If, however, your function is called from C, this cannot be guaranteed,
and you might want to create an owned reference, and release it when you’re finished.