May 13, 2025 · May 9, 2025
diff --git a/Include/internal/pycore_dict.h b/Include/internal/pycore_dict.h
    Py_hash_t hash,
    PyObject **result);

 extern void _PyDict_Clear_LockHeld(PyObject *op);

 #ifdef Py_GIL_DISABLED
 PyAPI_FUNC(void) _PyDict_EnsureSharedOnRead(PyDictObject *mp);
 #endif
diff --git a/Lib/test/test_free_threading/test_functools.py b/Lib/test/test_free_threading/test_functools.py
 importrandom
 importunittest

 fromfunctoolsimportlru_cache
 fromthreadingimportBarrier,Thread

 fromtest.supportimportthreading_helper

 @threading_helper.requires_working_threading()
 classTestLRUCache(unittest.TestCase):

 def_test_concurrent_operations(self,maxsize):
 num_threads=10
 b=Barrier(num_threads)
 @lru_cache(maxsize=maxsize)
 deffunc(arg=0):
 returnobject()


 defthread_func():
 b.wait()
 foriinrange(1000):
 r=random.randint(0,1000)
 ifi<800:
 func(i)
 elifi<900:
 func.cache_info()
 else:
 func.cache_clear()

 threads= []
 foriinrange(num_threads):
 t=Thread(target=thread_func)
 threads.append(t)

 withthreading_helper.start_threads(threads):
 pass

 deftest_concurrent_operations_unbounded(self):
 self._test_concurrent_operations(maxsize=None)

 deftest_concurrent_operations_bounded(self):
 self._test_concurrent_operations(maxsize=128)

 def_test_reentrant_cache_clear(self,maxsize):
 num_threads=10
 b=Barrier(num_threads)
 @lru_cache(maxsize=maxsize)
 deffunc(arg=0):
 func.cache_clear()
 returnobject()


 defthread_func():
 b.wait()
 foriinrange(1000):
 func(random.randint(0,10000))

 threads= []
 foriinrange(num_threads):
 t=Thread(target=thread_func)
 threads.append(t)

 withthreading_helper.start_threads(threads):
 pass

 deftest_reentrant_cache_clear_unbounded(self):
 self._test_reentrant_cache_clear(maxsize=None)

 deftest_reentrant_cache_clear_bounded(self):
 self._test_reentrant_cache_clear(maxsize=128)


 if__name__=="__main__":
 unittest.main()
diff --git a/Misc/NEWS.d/next/Library/2025-05-09-20-59-24.gh-issue-132641.3qTw44.rst b/Misc/NEWS.d/next/Library/2025-05-09-20-59-24.gh-issue-132641.3qTw44.rst
 Fixed a race in:func:`functools.lru_cache` under free-threading.
diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c
           this same key, then this setitem call will update the cache dict
           with this new link, leaving the old link as an orphan (i.e. not
           having a cache dict entry that refers to it). */
        if (_PyDict_SetItem_KnownHash(self->cache, key, (PyObject *)link,
                                      hash) < 0) {
        if (_PyDict_SetItem_KnownHash_LockHeld((PyDictObject *)self->cache, key,
         (PyObject *)link,hash) < 0) {
            Py_DECREF(link);
            return NULL;
        }
       for successful insertion in the cache dict before adding the
       link to the linked list.  Otherwise, the potentially reentrant
       __eq__ call could cause the then orphan link to be visited. */
    if (_PyDict_SetItem_KnownHash(self->cache, key, (PyObject *)link,
                                  hash) < 0) {
    if (_PyDict_SetItem_KnownHash_LockHeld((PyDictObject *)self->cache, key,
         (PyObject *)link,hash) < 0) {
        /* Somehow the cache dict update failed.  We no longer can
           restore the old link.  Let the error propagate upward and
           leave the cache short one link. */
    lru_list_elem *list = lru_cache_unlink_list(_self);
    FT_ATOMIC_STORE_SSIZE_RELAXED(_self->hits, 0);
    FT_ATOMIC_STORE_SSIZE_RELAXED(_self->misses, 0);
    PyDict_Clear(_self->cache);
    if (_self->wrapper == bounded_lru_cache_wrapper) {
        /* The critical section on the lru cache itself protects the dictionary
           for bounded_lru_cache instances. */
        _PyDict_Clear_LockHeld(_self->cache);
    } else {
        PyDict_Clear(_self->cache);
    }
    lru_cache_clear_list(list);
    Py_RETURN_NONE;
 }
diff --git a/Objects/dictobject.c b/Objects/dictobject.c
    ASSERT_CONSISTENT(mp);
 }

 void
 _PyDict_Clear_LockHeld(PyObject *op) {
    clear_lock_held(op);
 }

 void
 PyDict_Clear(PyObject *op)
 {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -150,6 +150,8 @@ extern int _PyDict_Pop_KnownHash(
		Py_hash_t hash,
		PyObject **result);

		extern void _PyDict_Clear_LockHeld(PyObject *op);

		#ifdef Py_GIL_DISABLED
		PyAPI_FUNC(void) _PyDict_EnsureSharedOnRead(PyDictObject *mp);
		#endif
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,75 @@
		importrandom
		importunittest

		fromfunctoolsimportlru_cache
		fromthreadingimportBarrier,Thread

		fromtest.supportimportthreading_helper

		@threading_helper.requires_working_threading()
		classTestLRUCache(unittest.TestCase):

		def_test_concurrent_operations(self,maxsize):
		num_threads=10
		b=Barrier(num_threads)
		@lru_cache(maxsize=maxsize)
		deffunc(arg=0):
		returnobject()


		defthread_func():
		b.wait()
		foriinrange(1000):
		r=random.randint(0,1000)
		ifi<800:
		func(i)
		elifi<900:
		func.cache_info()
		else:
		func.cache_clear()

		threads= []
		foriinrange(num_threads):
		t=Thread(target=thread_func)
		threads.append(t)

		withthreading_helper.start_threads(threads):
		pass

		deftest_concurrent_operations_unbounded(self):
		self._test_concurrent_operations(maxsize=None)

		deftest_concurrent_operations_bounded(self):
		self._test_concurrent_operations(maxsize=128)

		def_test_reentrant_cache_clear(self,maxsize):
		num_threads=10
		b=Barrier(num_threads)
		@lru_cache(maxsize=maxsize)
		deffunc(arg=0):
		func.cache_clear()
		returnobject()


		defthread_func():
		b.wait()
		foriinrange(1000):
		func(random.randint(0,10000))

		threads= []
		foriinrange(num_threads):
		t=Thread(target=thread_func)
		threads.append(t)

		withthreading_helper.start_threads(threads):
		pass

		deftest_reentrant_cache_clear_unbounded(self):
		self._test_reentrant_cache_clear(maxsize=None)

		deftest_reentrant_cache_clear_bounded(self):
		self._test_reentrant_cache_clear(maxsize=128)


		if__name__=="__main__":
		unittest.main()
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Fixed a race in:func:`functools.lru_cache` under free-threading.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1383,8 +1383,8 @@ bounded_lru_cache_update_lock_held(lru_cache_object *self,
		this same key, then this setitem call will update the cache dict
		with this new link, leaving the old link as an orphan (i.e. not
		having a cache dict entry that refers to it). */
		if (_PyDict_SetItem_KnownHash(self->cache, key, (PyObject *)link,
		hash) < 0) {
		if (_PyDict_SetItem_KnownHash_LockHeld((PyDictObject *)self->cache, key,
		(PyObject *)link,hash) < 0) {
		Py_DECREF(link);
		return NULL;
		}
Expand DownExpand Up		@@ -1453,8 +1453,8 @@ bounded_lru_cache_update_lock_held(lru_cache_object *self,
		for successful insertion in the cache dict before adding the
		link to the linked list. Otherwise, the potentially reentrant
		__eq__ call could cause the then orphan link to be visited. */
		if (_PyDict_SetItem_KnownHash(self->cache, key, (PyObject *)link,
		hash) < 0) {
		if (_PyDict_SetItem_KnownHash_LockHeld((PyDictObject *)self->cache, key,
		(PyObject *)link,hash) < 0) {
		/* Somehow the cache dict update failed. We no longer can
		restore the old link. Let the error propagate upward and
		leave the cache short one link. */
Expand DownExpand Up		@@ -1689,7 +1689,13 @@ _functools__lru_cache_wrapper_cache_clear_impl(PyObject *self)
		lru_list_elem *list = lru_cache_unlink_list(_self);
		FT_ATOMIC_STORE_SSIZE_RELAXED(_self->hits, 0);
		FT_ATOMIC_STORE_SSIZE_RELAXED(_self->misses, 0);
		PyDict_Clear(_self->cache);
		if (_self->wrapper == bounded_lru_cache_wrapper) {
		/* The critical section on the lru cache itself protects the dictionary
		for bounded_lru_cache instances. */
		_PyDict_Clear_LockHeld(_self->cache);
		} else {
		PyDict_Clear(_self->cache);
		}
		lru_cache_clear_list(list);
		Py_RETURN_NONE;
		}
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2915,6 +2915,11 @@ clear_lock_held(PyObject *op)
		ASSERT_CONSISTENT(mp);
		}

		void
		_PyDict_Clear_LockHeld(PyObject *op) {
		clear_lock_held(op);
		}

		void
		PyDict_Clear(PyObject *op)
		{
Expand Down