From dc5770b161a5e28eeff73a406cd4eddb0676c5b5 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 19 Dec 2017 11:00:13 -0800 Subject: [PATCH] bpo-32377: improve __del__ docs and fix mention about resurrection (GH-4927) (#4929) * Fix GH-32377: improve __del__ docs and fix mention about resurrection * Mention that CPython only calls __del__ once. (cherry picked from commit 4b965930e8625f77cb0e821daf5cc40e85b45f84) --- Doc/glossary.rst | 3 +- Doc/reference/datamodel.rst | 86 ++++++++++++++++++++----------------- 2 files changed, 49 insertions(+), 40 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index b947520b96b..aa5f47ed99a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -391,7 +391,8 @@ Glossary garbage collection The process of freeing memory when it is not used anymore. Python performs garbage collection via reference counting and a cyclic garbage - collector that is able to detect and break reference cycles. + collector that is able to detect and break reference cycles. The + garbage collector can be controlled using the :mod:`gc` module. .. index:: single: generator diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 230caf843a5..cd11020e0db 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1157,60 +1157,68 @@ Basic customization .. index:: single: destructor + single: finalizer statement: del Called when the instance is about to be destroyed. This is also called a - destructor. If a base class has a :meth:`__del__` method, the derived class's - :meth:`__del__` method, if any, must explicitly call it to ensure proper - deletion of the base class part of the instance. Note that it is possible - (though not recommended!) for the :meth:`__del__` method to postpone destruction - of the instance by creating a new reference to it. It may then be called at a - later time when this new reference is deleted. It is not guaranteed that - :meth:`__del__` methods are called for objects that still exist when the - interpreter exits. + finalizer or (improperly) a destructor. If a base class has a + :meth:`__del__` method, the derived class's :meth:`__del__` method, + if any, must explicitly call it to ensure proper deletion of the base + class part of the instance. + + It is possible (though not recommended!) for the :meth:`__del__` method + to postpone destruction of the instance by creating a new reference to + it. This is called object *resurrection*. It is implementation-dependent + whether :meth:`__del__` is called a second time when a resurrected object + is about to be destroyed; the current :term:`CPython` implementation + only calls it once. + + It is not guaranteed that :meth:`__del__` methods are called for objects + that still exist when the interpreter exits. .. note:: ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the reference count for ``x`` by one, and the latter is only called when - ``x``'s reference count reaches zero. Some common situations that may - prevent the reference count of an object from going to zero include: - circular references between objects (e.g., a doubly-linked list or a tree - data structure with parent and child pointers); a reference to the object - on the stack frame of a function that caught an exception (the traceback - stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a - reference to the object on the stack frame that raised an unhandled - exception in interactive mode (the traceback stored in - ``sys.last_traceback`` keeps the stack frame alive). The first situation - can only be remedied by explicitly breaking the cycles; the second can be - resolved by freeing the reference to the traceback object when it is no - longer useful, and the third can be resolved by storing ``None`` in - ``sys.last_traceback``. - Circular references which are garbage are detected and cleaned up when - the cyclic garbage collector is enabled (it's on by default). Refer to the - documentation for the :mod:`gc` module for more information about this - topic. + ``x``'s reference count reaches zero. + + .. impl-detail:: + It is possible for a reference cycle to prevent the reference count + of an object from going to zero. In this case, the cycle will be + later detected and deleted by the :term:`cyclic garbage collector + `. A common cause of reference cycles is when + an exception has been caught in a local variable. The frame's + locals then reference the exception, which references its own + traceback, which references the locals of all frames caught in the + traceback. + + .. seealso:: + Documentation for the :mod:`gc` module. .. warning:: Due to the precarious circumstances under which :meth:`__del__` methods are invoked, exceptions that occur during their execution are ignored, and a warning - is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in - response to a module being deleted (e.g., when execution of the program is - done), other globals referenced by the :meth:`__del__` method may already have - been deleted or in the process of being torn down (e.g. the import - machinery shutting down). For this reason, :meth:`__del__` methods - should do the absolute - minimum needed to maintain external invariants. Starting with version 1.5, - Python guarantees that globals whose name begins with a single underscore are - deleted from their module before other globals are deleted; if no other - references to such globals exist, this may help in assuring that imported - modules are still available at the time when the :meth:`__del__` method is - called. + is printed to ``sys.stderr`` instead. In particular: - .. index:: - single: repr() (built-in function); __repr__() (object method) + * :meth:`__del__` can be invoked when arbitrary code is being executed, + including from any arbitrary thread. If :meth:`__del__` needs to take + a lock or invoke any other blocking resource, it may deadlock as + the resource may already be taken by the code that gets interrupted + to execute :meth:`__del__`. + * :meth:`__del__` can be executed during interpreter shutdown. As a + consequence, the global variables it needs to access (including other + modules) may already have been deleted or set to ``None``. Python + guarantees that globals whose name begins with a single underscore + are deleted from their module before other globals are deleted; if + no other references to such globals exist, this may help in assuring + that imported modules are still available at the time when the + :meth:`__del__` method is called. + + + .. index:: + single: repr() (built-in function); __repr__() (object method) .. method:: object.__repr__(self)