Skip to content

Commit 09d9880

Browse files
committed
Add a new section and fix links.
1 parent ccf9056 commit 09d9880

File tree

1 file changed

+23
-13
lines changed

1 file changed

+23
-13
lines changed

peps/pep-0797.rst

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,10 @@ other areas of CPython, or in third-party libraries:
105105
(:c:func:`PyUnstable_Object_EnableDeferredRefcount`), but that has the downside
106106
of damaging single-threaded performance.
107107
- Immortality can help memory usage by avoiding copy-on-write operations in
108-
child processes. Instagram has been `doing this in Cinder <pep-797-cinder>`_
109-
for years, and it would be nice to let CPython also take advantage of it.
108+
child processes. Instagram has been `doing this in Cinder`_ for years,
109+
and it would be nice to let CPython also take advantage of it.
110110

111-
.. _pep-797-cinder: https://engineering.fb.com/2023/08/15/developer-tools/immortal-objects-for-python-instagram-meta/
111+
.. _doing this in Cinder: https://engineering.fb.com/2023/08/15/developer-tools/immortal-objects-for-python-instagram-meta/
112112

113113
Motivation
114114
==========
@@ -119,13 +119,12 @@ Immortal Objects Must Remain in CPython
119119
In the past, the main pushback to exposing APIs for immortality is that
120120
it's exposing an implementation detail, and would force CPython to keep
121121
immortality forever. Unfortunately, we've already reached that point: too
122-
many users, and `CPython itself <_pep-797-omitting-immortals>`_, omit
123-
reference counting for known immortal objects, such as :c:data:`Py_None`.
124-
Since there's no good way to deprecate that, CPython will always need some
125-
form of immortality to retain compatibility. That said, this proposal still
126-
keeps all new APIs as unstable.
122+
many users, and `CPython itself`_, omit reference counting for known immortal
123+
objects, such as :c:data:`Py_None`. Since there's no good way to deprecate
124+
that, CPython will always need some form of immortality to retain
125+
compatibility. That said, this proposal still keeps all new APIs unstable.
127126

128-
.. _pep-797-omitting-immortals: https://github.com/python/cpython/issues/103906
127+
.. _CPython itself: https://github.com/python/cpython/issues/103906
129128

130129
Objects Cannot be Directly Shared Between Interpreters
131130
******************************************************
@@ -175,6 +174,17 @@ In doing so, an object will release its memory back to CPython's object allocato
175174
allocator is per-interpreter, so it is unsafe to try to release an object's
176175
memory in an interpreter different from the one that created it.
177176

177+
178+
Immortality is a Powerful Tool to Wield
179+
***************************************
180+
181+
In general, immortal objects seem to have a lot of applications that aren't
182+
immediately clear. For example, `Nanobind used immortal objects`_
183+
in its original :term:`free threading` implementation. It seems like it would
184+
have interesting use-cases for many places outside of CPython.
185+
186+
.. _Nanobind used immortal objects: https://github.com/wjakob/nanobind/pull/695
187+
178188
Specification
179189
=============
180190

@@ -233,7 +243,7 @@ This PEP introduces two new semi-public APIs for making an object immortal:
233243
it's very unlikely that a type doesn't follow it:
234244
235245
* The object must be allocated under either the "object" or "memory" allocator
236-
domains. See :ref:`Allocator Domains <allocator-domains>` for more information.
246+
domains. See :ref:`Allocator Domains <python:allocator-domains>` for more information.
237247
Default values of :c:member:`~PyTypeObject.tp_alloc` always use the object
238248
allocator.
239249
* All :term:`strong references <strong reference>` released in the object's
@@ -289,7 +299,7 @@ or in tests) will now break if they are made immortal, because the reference
289299
count of an object will unexpectedly not change.
290300
291301
In one of the 3.14 alphas, this rule about reference counting was
292-
`brought up <pep-797-limited-refcount>`_ for clarification by a user of the
302+
`brought up`_ for clarification by a user of the
293303
limited C API. From that post, it's clear that reference count numbers are
294304
an implementation detail:
295305

@@ -303,7 +313,7 @@ that reference counts are unstable:
303313
well-defined values; the number of references to an object, and how that
304314
number is affected by Python code, may be different between versions.
305315

306-
.. _pep-797-limited-refcount: https://discuss.python.org/t/72006
316+
.. _brought up: https://discuss.python.org/t/72006
307317

308318
Destructors Must Use ``tp_finalize``
309319
------------------------------------
@@ -528,7 +538,7 @@ Preventing Reference Cycle UAFs
528538
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
529539

530540
Before any destruction of immortal objects starts to happen,
531-
`deferred memory deletion <Deferred Memory Deletion>`_ needs to be enabled.
541+
deferred memory deletion needs to be enabled.
532542
This is because the garbage collector doesn't manually call
533543
:c:member:`~PyTypeObject.tp_dealloc`, but instead it relies on
534544
:c:member:`~PyTypeObject.tp_clear` to get reference counts to zero.

0 commit comments

Comments
 (0)