[Docs] Possibly Add More Information About Immortal Objects about cpython

[ericsnowcurrently]

FWIW, I'm hesitant to make immortal objects more prominent in the docs. Presently they are an internal implementation detail (which daring users may use at their own risk). If anything, I'd rather they were less prominent in the docs. The only reason to mention them in the docs at all is for the benefit of people that notice objects with a really big refcount (which always stays the same).

All that would change, of course, if we were to expose immortal objects via public API--which PEP 683 purposefully did not do (other than the slight change in semantics for a few refcount operations). However, I'm not sure the existing internal API should ever be made public. It would be a genuine foot gun in its current unconstrained and unmanaged form, inviting substantial memory leaks. At best we might eventually choose to expose some more-carefully-crafted variant that's either better constrained in scope, less generic, or better managed by the runtime (or all of those). Until then, I think we should avoid drawing people's attention to the concept/term.

CC @eduardo-elizondo

[ncoghlan]

It's mainly conceptual documentation that I was suggesting would be helpful, rather than getting into the exact mechanics.

At the very least, a glossary entry for other documentation like https://docs.python.org/3/library/sys.html#sys.getrefcount and https://docs.python.org/3/glossary.html#term-reference-count to point to rather than each mention having to provide its own short definition.

I don't think the actual definition needs to be particularly in depth, just give a bit more info about why immortal objects are a thing:

immortal object
  To reduce runtime overhead (especially in free-threaded builds and when sharing objects between
  subinterpreters), the CPython interpreter internally marks some objects (such as :const:`None`,
  :const:`True`, and :const:`False`) as "immortal", and excludes them from the interpreter's normal
  reference count tracking. This provides several practical benefits (as described in :pep:`683`) but
  also means the immortal objects do not report accurate reference count information at runtime.

  .. impl-detail::
     Interpreters other than CPython may not need or define immortal objects.

And then tweak the "historical document" notice on the PEP to make it clear that while it may no longer be an accurate description of the technical implementation details, it will indefinitely provide an accurate description of the benefits of including immortal objects in the CPython implementation.

[picnixz]

I'm in favor of this definition, but would say "may not report" instead of "does not report".

[eduardo-elizondo]

I agree with @ericsnowcurrently's proposal of keeping this mostly as an implementation detail since that was the original intent of the PEP. At the same time, @ncoghlan is very explicitly stating that it's an implementation detail so I wouldn't be opposed to that. I'll leave it to Eric to ultimately decide