diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/bool.rst | 12 | ||||
| -rw-r--r-- | Doc/c-api/init.rst | 2 | ||||
| -rw-r--r-- | Doc/c-api/init_config.rst | 2 | ||||
| -rw-r--r-- | Doc/c-api/none.rst | 6 | ||||
| -rw-r--r-- | Doc/c-api/refcounting.rst | 10 | ||||
| -rw-r--r-- | Doc/c-api/slice.rst | 3 | ||||
| -rw-r--r-- | Doc/glossary.rst | 12 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 6 |
8 files changed, 32 insertions, 21 deletions
diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index b14fa6a..b4dc484 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -26,19 +26,19 @@ are available, however. .. c:var:: PyObject* Py_False The Python ``False`` object. This object has no methods and is - `immortal <https://peps.python.org/pep-0683/>`_. + :term:`immortal`. -.. versionchanged:: 3.12 - :c:data:`Py_False` is immortal. + .. versionchanged:: 3.12 + :c:data:`Py_False` is :term:`immortal`. .. c:var:: PyObject* Py_True The Python ``True`` object. This object has no methods and is - `immortal <https://peps.python.org/pep-0683/>`_. + :term:`immortal`. -.. versionchanged:: 3.12 - :c:data:`Py_True` is immortal. + .. versionchanged:: 3.12 + :c:data:`Py_True` is :term:`immortal`. .. c:macro:: Py_RETURN_FALSE diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index d164d1a..e89641f 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1485,7 +1485,7 @@ otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared because of the refcount. One simple but less-efficient approach around this is to use a global lock around all use of some state (or object). Alternately, effectively immutable objects (like integers or strings) -can be made safe in spite of their refcounts by making them "immortal". +can be made safe in spite of their refcounts by making them :term:`immortal`. In fact, this has been done for the builtin singletons, small integers, and a number of other builtin objects. diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 0c2ed8a..47a8fbb 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -1170,7 +1170,7 @@ PyConfig .. c:member:: int show_ref_count - Show total reference count at exit (excluding immortal objects)? + Show total reference count at exit (excluding :term:`immortal` objects)? Set to ``1`` by :option:`-X showrefcount <-X>` command line option. diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index dd8bfb5..f1941fc 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -16,10 +16,10 @@ same reason. .. c:var:: PyObject* Py_None The Python ``None`` object, denoting lack of value. This object has no methods - and is `immortal <https://peps.python.org/pep-0683/>`_. + and is :term:`immortal`. -.. versionchanged:: 3.12 - :c:data:`Py_None` is immortal. + .. versionchanged:: 3.12 + :c:data:`Py_None` is :term:`immortal`. .. c:macro:: Py_RETURN_NONE diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 118af7a..68119a2 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -17,7 +17,7 @@ of Python objects. Note that the returned value may not actually reflect how many references to the object are actually held. For example, some - objects are "immortal" and have a very high refcount that does not + objects are :term:`immortal` and have a very high refcount that does not reflect the actual number of references. Consequently, do not rely on the returned value to be accurate, other than a value of 0 or 1. @@ -34,9 +34,7 @@ of Python objects. Set the object *o* reference counter to *refcnt*. - Note that this function has no effect on - `immortal <https://peps.python.org/pep-0683/>`_ - objects. + This function has no effect on :term:`immortal` objects. .. versionadded:: 3.9 @@ -49,6 +47,8 @@ of Python objects. Indicate taking a new :term:`strong reference` to object *o*, indicating it is in use and should not be destroyed. + This function has no effect on :term:`immortal` objects. + This function is usually used to convert a :term:`borrowed reference` to a :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be used to create a new :term:`strong reference`. @@ -113,6 +113,8 @@ of Python objects. Release a :term:`strong reference` to object *o*, indicating the reference is no longer used. + This function has no effect on :term:`immortal` objects. + Once the last :term:`strong reference` is released (i.e. the object's reference count reaches 0), the object's type's deallocation diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 9e880c6..27a1757c 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -119,8 +119,7 @@ Ellipsis Object .. c:var:: PyObject *Py_Ellipsis The Python ``Ellipsis`` object. This object has no methods. Like - :c:data:`Py_None`, it is an `immortal <https://peps.python.org/pep-0683/>`_. - singleton object. + :c:data:`Py_None`, it is an :term:`immortal` singleton object. .. versionchanged:: 3.12 :c:data:`Py_Ellipsis` is immortal. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index dad7453..6b517b9 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -579,6 +579,16 @@ Glossary :ref:`idle` is a basic editor and interpreter environment which ships with the standard distribution of Python. + immortal + If an object is immortal, its reference count is never modified, and + therefore it is never deallocated. + + Built-in strings and singletons are immortal objects. For example, + :const:`True` and :const:`None` singletons are immmortal. + + See `PEP 683 – Immortal Objects, Using a Fixed Refcount + <https://peps.python.org/pep-0683/>`_ for more information. + immutable An object with a fixed value. Immutable objects include numbers, strings and tuples. Such an object cannot be altered. A new object has to @@ -1056,7 +1066,7 @@ Glossary reference count The number of references to an object. When the reference count of an object drops to zero, it is deallocated. Some objects are - "immortal" and have reference counts that are never modified, and + :term:`immortal` and have reference counts that are never modified, and therefore the objects are never deallocated. Reference counting is generally not visible to Python code, but it is a key element of the :term:`CPython` implementation. Programmers can call the diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 4d24606..bf9aaca 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -831,7 +831,7 @@ always available. Note that the returned value may not actually reflect how many references to the object are actually held. For example, some - objects are "immortal" and have a very high refcount that does not + objects are :term:`immortal` and have a very high refcount that does not reflect the actual number of references. Consequently, do not rely on the returned value to be accurate, other than a value of 0 or 1. @@ -1182,8 +1182,8 @@ always available. names used in Python programs are automatically interned, and the dictionaries used to hold module, class or instance attributes have interned keys. - Interned strings are not immortal; you must keep a reference to the return - value of :func:`intern` around to benefit from it. + Interned strings are not :term:`immortal`; you must keep a reference to the + return value of :func:`intern` around to benefit from it. .. function:: is_finalizing() |