Reference Counting Documentation (longish)

[Tom Culliton]

Earlier today somebody came to me for help with a simple application
which embeds python and which was leaking memory.  The application
gets a message using an API, converts the list of key/value pairs into
a python dictionary and runs a python function with the dictionary as
it's argument.  

It was immediately obvious that the problem was going to be botched
reference counts and it was just a matter of looking up the behaviour
of each Python API function in the lovely new C API Reference Manual
and and doing a little trivial mental math.  After all, I've done this
before, extended python, embedded it, avoided leaking memory, and
several times to boot.  It ought to be easy ...  Right?

Wrong.

I dug into the "Python/C API Reference Manual", and found no mention
of the ref-counting behaviour of the functions in the Abstract and
Concrete Object Layer sections (6 and 7).  Checked the Refrence
Counting section (3) with the same results.  Checked the Objects,
Types and Reference Counts section (1.2), again no dice.

So I scratched my head some and checked the "Extending and Embedding"
tutorial.  The section on Reference Counts (1.10) actually managed to
confused me, despite the fact that I understood the topic and got it
right on the first try back around version 1.2 or so.  (BTW - It even
seemed to contradict the code when I fell back on that.)

Thank heavens that the code is so darned readable.  When I finally
gave up on the documentation and just remembered to "use the source"
it was all figured out and fixed in about 10 minutes.

And now for the point of this whole story: I think we need a reference
counting cheat sheet in the C API Reference Manual rather badly.  I'm
not talking about anything elaborate, just a simple table showing each
function in the API, and what it does to the reference counts of its
arguments and return value.  (It could even be part of the current
entries for each function.)  This would be an absolutely priceless
resource for anyone doing embedding and extending.


PyList_New
	return value - refcount set to one	

Py_BuildValue
	return value - refcount set to one
	parameters - unchanged (?)

PyList_Append
	first parameter unchanged
	second parameter INCREFed

PyString_FromString
	return value - refcount set to one
	parameters - unchanged (?)

PyDict_SetItem
	first parameter unchanged
	second parameter INCREFed
	third parameter INCREFed

.
.
.

Does something like this exist?  I sure couldn't find it, despite long
familiarity with the docs and the web sites.  It would certainly be an
easy enough project for anyone with some spare time on their hands.  If
nobody else can step up, I'll even volunteer to provide the content if
someone else can incorporate it ...

Thanks for your patience.