gh-123241: Document restrictions for tp_traverse implementations

[colesbury]

---

📚 Documentation preview 📚: https://cpython-previews--142272.org.readthedocs.build/

• https://cpython-previews--142272.org.readthedocs.build/en/142272/c-api/typeobj.html#c.PyTypeObject.tp_traverse
• https://cpython-previews--142272.org.readthedocs.build/en/142272/c-api/gcsupport.html#c.traverseproc

• Issue: GC in free-threaded build has problems with Py_INCREF()/Py_DECREF() in tp_traverse handlers #123241

[mpage]

LGTM

[encukou]

If we just add it to the docs like this, how are maintainers of old code expected to find out about it?

AFAICS, this is a new requirement, and making CPython rely on it will be a breaking change.
I assume there can't be a period of deprecation warnings. Does this need a PEP 387 exception?

[pablogsal]

If we just add it to the docs like this, how are maintainers of old code expected to find out about it?

AFAICS, this is a new requirement, and making CPython rely on it will be a breaking change.

I assume there can't be a period of deprecation warnings. Does this need a PEP 387 exception?

This was unfortunately always a requirement for correctness but we never documented it. Calling it a "new requirement" is probably not very productive because if you were doing this before you have a bug and you can affect the correctness of the algorithm or crash depending on the version and the situation.

We could perhaps raise some warnings with time time cost in debug build by checking the total ref count.

[DinoV]

Arguably the "create or destroy" objects is redundant given that involves modifying a reference count but LGTM.