Skip to content

[BUG]: Data race in class_::init_instance() on free-threaded builds #6214

Open

Description

@YukaSadaoka

Required prerequisites

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

  1. YukaSadaoka commented on Nov 13, 2026

    @YukaSadaoka
    ContributorAuthor

    @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

  2. henryiii commented on Nov 13, 2026

    @henryiii
    Collaborator

    You can work on that if you'd like, I just did the easiest one for now. 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageNew bug, unverified

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions