Repository navigation
Description
Required prerequisites
- Make sure you've read the documentation. Your issue may be addressed there.
- Search the issue tracker and Discussions to verify that this hasn't already been reported. +1 or comment there if it has.
- Consider asking first in the Gitter chat room or in a Discussion.
What version (or hash if on master) of pybind11 are you using?
master (bf6e3af)
Problem description
On free-threaded Python, ThreadSanitizer reports a data race when several threads get Python wrappers for the same C++ object at the same time. For example, a C++ function exposed with m.def() that returns a cached std::shared_ptr or a singleton.
class_::init_instance() adds the new instance to registered_instances first and only then sets its status flags (set_instance_registered()) and constructs the holder. The smart_holder overload also sets is_alias after registering. As soon as the instance is in the map, another thread can get it from find_registered_python_instance() and call a method on it. Loading self then reads the instance's packed bitfields (simple_layout in the value_and_holder constructor) while the first thread is still writing them.
The instance map lock doesn't help here because those writes happen after the lock is released. With the GIL this can't happen.
TSan report (Python 3.14 free-threaded built with clang 19, libc++):
WARNING: ThreadSanitizer: data race
Write of size 1 by thread T2:
#0 value_and_holder::set_instance_registered(bool) include/pybind11/detail/value_and_holder.h:69
#1 class_<SharedObject<0>, std::shared_ptr<SharedObject<0>>>::init_instance(...)
#2 type_caster_generic::cast(...)
#3 type_caster_base<SharedObject<0>>::cast_holder(...)
Previous read of size 1 by thread T4:
#0 value_and_holder::value_and_holder(instance*, type_info const*, size_t, size_t) include/pybind11/detail/value_and_holder.h:25
#1 instance::get_value_and_holder(type_info const*, bool)
#2 type_caster_generic::load_impl<type_caster_generic>(handle, bool)
#3 type_caster_generic::load(handle, bool)
I'm working on enabling free threading in Python servers and I hit this in one of unit tests under TSan and free-threaded Python. I double checked existing issues but I couldn't find this issue already reported. If I'm missing anything please let me know!
Reproducible example code
// C++
struct SharedObject {
int value() const { return 42; }
};
std::shared_ptr<SharedObject> get_shared() {
static const auto instance = std::make_shared<SharedObject>();
return instance;
}
PYBIND11_MODULE(example, m) {
py::class_<SharedObject, std::shared_ptr<SharedObject>>(m, "SharedObject")
.def("value", &SharedObject::value);
m.def("get_shared", &get_shared);
}
# Python (run with PYTHON_GIL=0 on a TSan build of 3.14 with Free Threading)
import threading
import example
b = threading.Barrier(4)
def worker():
b.wait()
for _ in range(1000):
example.get_shared().value()
threads = [threading.Thread(target=worker) for _ in range(4)]
for t in threads:
t.start()
for t in threads:
t.join()
Is this a regression? Put the last known working version here if it is.
Not a regression
Activity
YukaSadaoka commentedon Nov 13, 2026
@henryiii thanks for sending the PR #6264. My apologies for not posting updates here for a while, I got distracted by other higher priority issues. I'm still interested in fixing the remaining issue (i.e., "Custom holders still register the instance before the holder is constructed.") but please let me know if you prefer sending a PR for that instead. Also FYI @rwgk
henryiii commentedon Nov 13, 2026
You can work on that if you'd like, I just did the easiest one for now. 👍