Further improve the abstract.

Author: ZeroIntensity

peps/pep-0797.rst

@@ -12,23 +12,12 @@ Post-History: `01-Jul-2025 <https://discuss.python.org/t/97306>`__
 Abstract
 ========
 
-:pep:`683` introduced :term:`immortal` objects into CPython, using an "immortal
-reference count" where the reference count field is never modified on the
-object. Currently, all APIs for enabling immortality on a given object are
-private, and even those APIs aren't fully safe for immortalizing *any* object.
-
-In particular, the private API has ``_Py_SetImmortal``, which simply untracks a
-passed object from the garbage collector, and then sets its reference count to
-the magic immortal number. But again, this isn't totally safe; for example, due
-to the current string interning implementation, immortalizing a string can cause
-crashes. To make matters worse, there's no mechanism in place to deallocate an
-object once it has become immortal; objects on the heap are leaked, which is bad
-for per-interpreter state.
-
 This PEP aims to introduce a public way to immortalize arbitrary objects, while
-making sure the object is deallocated later (specifically, during interpreter
+making sure the object is deallocated later (during interpreter
 finalization). This is done by introducing two new APIs: :func:`sys._immortalize`
-on the Python side, and :c:func:`PyUnstable_Immortalize` on the C side.
+on the Python side, and :c:func:`PyUnstable_Immortalize` on the C side. These
+are generally considered to be low-level APIs that won't be needed by users; the
+main beneficiary will be CPython.
 
 Both of these functions make the given object immortal, and then deallocate it when
 the interpreter is shutting down using a simulated garbage collection.
@@ -62,9 +51,33 @@ Or, in Python:
     sys._immortalize(my_singleton)
     assert sys._is_immortal(my_singleton)
 
+Running either of these examples on a Python debug build with :option:`-X showrefcount <-X>`
+show that the (heap-allocated) immortal object is not leaked:
+
+.. code-block:: bash
+
+   $ ./python -Xshowrefcount -c "import sys; sys._immortalize(object())"
+   [0 refs, 0 blocks]
+
 Motivation
 ==========
 
+It's Currently Impossible to Immortalize General Objects
+********************************************************
+
+:pep:`683` introduced :term:`immortal` objects into CPython, using an "immortal
+reference count" where the reference count field is never modified on the
+object. Currently, all APIs for enabling immortality on a given object are
+private, and even those APIs aren't fully safe for immortalizing *any* object.
+
+In particular, the private API has ``_Py_SetImmortal``, which simply untracks a
+passed object from the garbage collector, and then sets its reference count to
+the magic immortal number. But again, this isn't totally safe; for example, due
+to the current string interning implementation, immortalizing a string can cause
+crashes. To make matters worse, there's no mechanism in place to deallocate an
+object once it has become immortal; this is limiting for potential optimizations
+using immortality.
+
 What Problem Does Immortality Solve?
 ************************************