Updating new comments to reflect new information.

Author: rwgk

docs/advanced/pycpp/utilities.rst

@@ -51,13 +51,12 @@ redirects output to the corresponding Python streams:
 
     The implementation in ``pybind11/iostream.h`` is NOT thread safe. Multiple
     threads writing to a redirected ostream concurrently cause data races
-    and potentially buffer overflows. Therefore it is a requirement that
-    all (possibly) concurrent redirected ostream writes are locked. Note
-    that this is not expected to be an actual limitation, because without
-    synchronization output will be randomly interleaved and most likely
-    unreadable. Well-written C++ code is likely to use locking regardless of
-    this pybind11 requirement. — For more background see the discussion under
-    `PR #2982 <https://github.com/pybind/pybind11/pull/2982>`_.
+    and potentially buffer overflows. Therefore it is currrently a requirement
+    that all (possibly) concurrent redirected ostream writes are protected by
+    a mutex. #HelpAppreciated: Work on iostream.h thread safety. For more
+    background see the discussions under
+    `PR #2982 <https://github.com/pybind/pybind11/pull/2982>`_ and
+    `PR #2995 <https://github.com/pybind/pybind11/pull/2995>`_.
 
 This method respects flushes on the output streams and will flush if needed
 when the scoped guard is destroyed. This allows the output to be redirected in

include/pybind11/iostream.h

@@ -7,11 +7,14 @@
     BSD-style license that can be found in the LICENSE file.
 
     WARNING: The implementation in this file is NOT thread safe. Multiple
-    threads writing to a redirected ostream concurrently cause data races and
-    potentially buffer overflows. Therefore it is a REQUIREMENT that all
-    (possibly) concurrent redirected ostream writes are locked. For more
-    background see the discussion under
-    https://github.com/pybind/pybind11/pull/2982.
+    threads writing to a redirected ostream concurrently cause data races
+    and potentially buffer overflows. Therefore it is currrently a requirement
+    that all (possibly) concurrent redirected ostream writes are protected by
+    a mutex.
+    #HelpAppreciated: Work on iostream.h thread safety.
+    For more background see the discussions under
+    https://github.com/pybind/pybind11/pull/2982 and
+    https://github.com/pybind/pybind11/pull/2995.
 */
 
 #pragma once

tests/test_iostream.cpp

@@ -41,6 +41,12 @@ struct TestThread {
             static std::mutex cout_mutex;
             while (!stop_) {
                 {
+                    // #HelpAppreciated: Work on iostream.h thread safety.
+                    // Without this lock, the clang ThreadSanitizer (tsan) reliably reports a
+                    // data race, and this test is predictably flakey on Windows.
+                    // For more background see the discussion under
+                    // https://github.com/pybind/pybind11/pull/2982 and
+                    // https://github.com/pybind/pybind11/pull/2995.
                     const std::lock_guard<std::mutex> lock(cout_mutex);
                     std::cout << "x" << std::flush;
                 }