[issue41133] Insufficient description of cyclic garbage collector for C API

[Pablo Galindo Salgado]

Pablo Galindo Salgado <pablogsal at gmail.com> added the comment:

I agree with what Tim said. We also cannot foresee every possible bug of someone misusing the C API, and the garbage collector interacts with many systems of the VM, and having gigantic documentation has shown to be always detrimental. 

> I think it would be helpful to have something as troubleshooting information on the garbage collector. If you've got a bug in your C module,

"A bug in your C module" can be absolutely anything (even more things given that we are talking about C!). Many people also blame the GC immediately just because the crash happens during visitation when the bug already happened much before. I don't think that a "general debugging section" about the GC will be very as helpful as improving the clarity of the contract.

> For that matter, the documentation for tp_traverse doesn't mention that you have to call Py_VISIT on each object exactly as many times as references you hold to it; the phrasing sounds like it's fine so long as you call it at least once on any object you hold a reference to.

A note in the docs about this sounds reasonable as is well-scoped. If you want, you can do a PR and add me there and I will review it. Otherwise, I will try to put something together myself.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue41133>
_______________________________________