Just for the sheer heck of it, I’ve decided to create a Scheme binding to libpython so you can embed Python in Scheme programs. I’m already able to call into Python’s C API, but I haven’t really thought about memory management.
The way mzscheme’s FFI works is that I can call a function, and if that function returns a pointer to a PyObject, then I can have it automatically increment the reference count. Then, I can register a finalizer that will decrement the reference count when the Scheme object gets garbage collected. I’ve looked at the documentation for reference counting, and don’t see any problems with this at first glance (although it may be sub-optimal in some cases). Are there any gotchas I’m missing?
Also, I’m having trouble making heads or tails of the cyclic garbage collector documentation. What things will I need to bear in mind here? In particular, how do I make Python aware that I have a reference to something so it doesn’t collect it while I’m still using it?
Your link to http://docs.python.org/extending/extending.html#reference-counts is the right place. The Extending and Embedding and Python/C API sections of the documentation are the ones that will explain how to use the C API.
Reference counting is one of the annoying parts of using the C API. The main gotcha is keeping everything straight: Depending on the API function you call, you may or may not own the reference to the object you get. Be careful to understand whether you own it (and thus cannot forget to DECREF it or give it to something that will steal it) or are borrowing it (and must INCREF it to keep it and possibly to use it during your function). The most common bugs involving this are 1) remembering incorrectly whether you own a reference returned by a particular function and 2) believing you’re safe to borrow a reference for a longer time than you are.
You do not have to do anything special for the cyclic garbage collector. It’s just there to patch up a flaw in reference counting and doesn’t require direct access.