diff options
Diffstat (limited to 'Doc/library/weakref.rst')
| -rw-r--r-- | Doc/library/weakref.rst | 44 |
1 files changed, 26 insertions, 18 deletions
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 83e6000..bffa2ba 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -24,18 +24,20 @@ only remaining references to a referent are weak references, :term:`garbage collection` is free to destroy the referent and reuse its memory for something else. A primary use for weak references is to implement caches or mappings holding large objects, where it's desired that a large object not be -kept alive solely because it appears in a cache or mapping. For example, if you -have a number of large binary image objects, you may wish to associate a name -with each. If you used a Python dictionary to map names to images, or images to -names, the image objects would remain alive just because they appeared as values -or keys in the dictionaries. The :class:`WeakKeyDictionary` and -:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are -an alternative, using weak references to construct mappings that don't keep -objects alive solely because they appear in the mapping objects. If, for -example, an image object is a value in a :class:`WeakValueDictionary`, then when -the last remaining references to that image object are the weak references held -by weak mappings, garbage collection can reclaim the object, and its -corresponding entries in weak mappings are simply deleted. +kept alive solely because it appears in a cache or mapping. + +For example, if you have a number of large binary image objects, you may wish to +associate a name with each. If you used a Python dictionary to map names to +images, or images to names, the image objects would remain alive just because +they appeared as values or keys in the dictionaries. The +:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` classes supplied by +the :mod:`weakref` module are an alternative, using weak references to construct +mappings that don't keep objects alive solely because they appear in the mapping +objects. If, for example, an image object is a value in a +:class:`WeakValueDictionary`, then when the last remaining references to that +image object are the weak references held by weak mappings, garbage collection +can reclaim the object, and its corresponding entries in weak mappings are +simply deleted. :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references in their implementation, setting up callback functions on the weak references @@ -49,6 +51,12 @@ they need -- it's not usually necessary to create your own weak references directly. The low-level machinery used by the weak dictionary implementations is exposed by the :mod:`weakref` module for the benefit of advanced uses. +.. note:: + + Weak references to an object are cleared before the object's :meth:`__del__` + is called, to ensure that the weak reference callback (if any) finds the + object still alive. + Not all objects can be weakly referenced; those objects which can include class instances, functions written in Python (but not in C), instance methods, sets, frozensets, file objects, :term:`generator`\s, type objects, :class:`DBcursor` @@ -130,11 +138,11 @@ Extension types can easily be made to support weak references; see .. note:: - Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python + Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python dictionary, it must not change size when iterating over it. This can be - difficult to ensure for a :class:`WeakKeyDictionary` because actions performed - by the program during iteration may cause items in the dictionary to vanish "by - magic" (as a side effect of garbage collection). + difficult to ensure for a :class:`WeakKeyDictionary` because actions + performed by the program during iteration may cause items in the + dictionary to vanish "by magic" (as a side effect of garbage collection). :class:`WeakKeyDictionary` objects have the following additional methods. These expose the internal references directly. The references are not guaranteed to @@ -229,7 +237,7 @@ Weak Reference Objects ---------------------- Weak reference objects have no attributes or methods, but do allow the referent -to be obtained, if it still exists, by calling it:: +to be obtained, if it still exists, by calling it: >>> import weakref >>> class Object: @@ -242,7 +250,7 @@ to be obtained, if it still exists, by calling it:: True If the referent no longer exists, calling the reference object returns -:const:`None`:: +:const:`None`: >>> del o, o2 >>> print(r()) |