mirror of
https://github.com/micropython/micropython.git
synced 2026-05-01 13:20:14 +02:00
Damien George
79 lines
3.0 KiB
ReStructuredText
79 lines
3.0 KiB
ReStructuredText
:mod:`weakref` -- Python object lifetime management
|
|
===================================================
|
|
|
|
.. module:: weakref
|
|
:synopsis: Create weak references to Python objects
|
|
|
|
|see_cpython_module| :mod:`python:weakref`.
|
|
|
|
This module allows creation of weak references to Python objects. A weak reference
|
|
is a non-traceable reference to a heap-allocated Python object, so the garbage
|
|
collector can still reclaim the object even though the weak reference refers to it.
|
|
|
|
Python callbacks can be registered to be called when an object is reclaimed by the
|
|
garbage collector. This provides a safe way to clean up when objects are no longer
|
|
needed.
|
|
|
|
**Availability:** the weakref module requires ``MICROPY_PY_WEAKREF`` to be enabled
|
|
at compile time. It is enabled on the unix coverage variant and the webassembly
|
|
pyscript variant.
|
|
|
|
ref objects
|
|
-----------
|
|
|
|
A ref object is the simplest way to make a weak reference.
|
|
|
|
.. class:: ref(object [, callback], /)
|
|
|
|
Return a weak reference to the given *object*.
|
|
|
|
If *callback* is given and is not ``None`` then, when *object* is reclaimed
|
|
by the garbage collector and if the weak reference object is still alive, the
|
|
*callback* will be called. The *callback* will be passed the weak reference
|
|
object as its single argument.
|
|
|
|
.. method:: ref.__call__()
|
|
|
|
Calling the weak reference object will return its referenced object if that
|
|
object is still alive. Otherwise ``None`` will be returned.
|
|
|
|
finalize objects
|
|
----------------
|
|
|
|
A finalize object is an extended version of a ref object that is more convenient to
|
|
use, and allows more control over the callback.
|
|
|
|
.. class:: finalize(object, callback, /, *args, **kwargs)
|
|
|
|
Return a weak reference to the given *object*. In contrast to *weakref.ref*
|
|
objects, finalize objects are held onto internally and will not be collected until
|
|
*object* is collected.
|
|
|
|
A finalize object starts off alive. It transitions to the dead state when the
|
|
finalize object is called, either explicitly or when *object* is collected. It also
|
|
transitions to dead if the `finalize.detach()` method is called.
|
|
|
|
When *object* is reclaimed by the garbage collector (or the finalize object is
|
|
explicitly called by user code) and the finalize object is still in the alive state,
|
|
the *callback* will be called. The *callback* will be passed arguments as:
|
|
``callback(*args, **kwargs)``.
|
|
|
|
.. method:: finalize.__call__()
|
|
|
|
If the finalize object is alive then it transitions to the dead state and returns
|
|
the value of ``callback(*args, **kwargs)``. Otherwise ``None`` will be returned.
|
|
|
|
.. method:: finalize.alive
|
|
|
|
Read-only boolean attribute that indicates if the finalizer is in the alive state.
|
|
|
|
.. method:: finalize.peek()
|
|
|
|
If the finalize object is alive then return ``(object, callback, args, kwargs)``.
|
|
Otherwise return ``None``.
|
|
|
|
.. method:: finalize.detach()
|
|
|
|
If the finalize object is alive then it transitions to the dead state and returns
|
|
``(object, callback, args, kwargs)``. Otherwise ``None`` will be returned.
|