Remove cached_method locking logic

Although this logic tried to avoid lock contention, there were still
scenarios under which it was possible and could negatively impact users.
Removal and adjustment of the documentation puts responsibility for
locking/safety onto users, similar to other parts of the stdlib.

Author: sirosen

Doc/library/functools.rst

@@ -152,8 +152,9 @@ The :mod:`!functools` module defines the following functions:
    The *cached_method* does not prevent all possible race conditions in
    multi-threaded usage. The function could run more than once on the
    same instance, with the same inputs, with the latest run setting the cached
-   value. However, initialization of the cached method, which happens lazily on
-   first access, is itself threadsafe.
+   value. The per-instance cache is lazily initialized on first access (via the
+   descriptor protocol), so parallel access on a single instance can race to
+   initialize.
 
    This decorator requires that the each instance supports weak references.
    Some immutable types and slotted classes without ``__weakref__`` as one of

Lib/functools.py

@@ -1242,27 +1242,19 @@ def _get_or_create_cached_func(self, instance):
 
         instance_id = id(instance)
 
-        # first try to retrieve the cached func without locking (thus avoiding any
-        # unnecessary contention when there is a value), but then retry
-        # under a lock to actually provide safety such that two parallel threads won't
-        # construct distinct caches simultaneously
         try:
             ref, cached_func = self._function_table[instance_id]
         except KeyError:
-            with self._cache_init_lock:
-                try:
-                    ref, cached_func = self._function_table[instance_id]
-                except KeyError:
-                    ref = weakref.ref(
-                        instance,
-                        _cached_method_weakref_callback(
-                            self._function_table, instance_id
-                        ),
-                    )
-                    cached_func = _wrap_unbound_cached_method(
-                        ref, self.func, self._maxsize, self._typed
-                    )
-                    self._function_table[instance_id] = ref, cached_func
+            ref = weakref.ref(
+                instance,
+                _cached_method_weakref_callback(
+                    self._function_table, instance_id
+                ),
+            )
+            cached_func = _wrap_unbound_cached_method(
+                ref, self.func, self._maxsize, self._typed
+            )
+            self._function_table[instance_id] = ref, cached_func
 
         return cached_func