From: Raymond Hettinger Date: Sat, 22 Apr 2023 14:18:25 +0000 (-0500) Subject: GH-103475: cache() and lru_cache() do not have a "call once" guarantee (GH-103669) X-Git-Tag: v3.12.0b1~488 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e5eaac6064561c8f7643011a31fa506e78330798;p=thirdparty%2FPython%2Fcpython.git GH-103475: cache() and lru_cache() do not have a "call once" guarantee (GH-103669) --- diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index d1289ce83621..29cbc87bf66d 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -49,8 +49,13 @@ The :mod:`functools` module defines the following functions: >>> factorial(12) # makes two new recursive calls, the other 10 are cached 479001600 - The cache is threadsafe so the wrapped function can be used in multiple - threads. + The cache is threadsafe so that the wrapped function can be used in + multiple threads. This means that the underlying data structure will + remain coherent during concurrent updates. + + It is possible for the wrapped function to be called more than once if + another thread makes an additional call before the initial call has been + completed and cached. .. versionadded:: 3.9 @@ -158,8 +163,13 @@ The :mod:`functools` module defines the following functions: *maxsize* most recent calls. It can save time when an expensive or I/O bound function is periodically called with the same arguments. - The cache is threadsafe so the wrapped function can be used in multiple - threads. + The cache is threadsafe so that the wrapped function can be used in + multiple threads. This means that the underlying data structure will + remain coherent during concurrent updates. + + It is possible for the wrapped function to be called more than once if + another thread makes an additional call before the initial call has been + completed and cached. Since a dictionary is used to cache results, the positional and keyword arguments to the function must be :term:`hashable`.