https://gcc.gnu.org/g:4ec931c5e514ce0731cc72085af817ce0c6f3887
commit r14-11615-g4ec931c5e514ce0731cc72085af817ce0c6f3887
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Fri Apr 11 11:08:34 2025 +0100
libstdc++: Document thread-safety for COW std::string [PR21334]
The gcc4-compatible copy-on-write std::string does not conform to the
C++11 requirements on data race avoidance in standard containers.
Specifically, calling non-const member functions such as begin() and
data() needs to do the "copy on write" operation and so is most
definitely a modification of the object. As such, those non-const
members must not be called concurrently with any other uses of the
string object.
libstdc++-v3/ChangeLog:
PR libstdc++/21334
* doc/xml/manual/using.xml: Document that container data race
avoidance rules do not apply to COW std::string.
* doc/html/*: Regenerate.
(cherry picked from commit dd35f66287b7cca196a720c9641e463255dceb1c)
Diff:
---
libstdc++-v3/doc/html/manual/using_concurrency.html | 10 ++++++++++
libstdc++-v3/doc/xml/manual/using.xml | 12 ++++++++++++
2 files changed, 22 insertions(+)
diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html
b/libstdc++-v3/doc/html/manual/using_concurrency.html
index e09fc5e15bcb..f99cca414ec8 100644
--- a/libstdc++-v3/doc/html/manual/using_concurrency.html
+++ b/libstdc++-v3/doc/html/manual/using_concurrency.html
@@ -126,6 +126,16 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
the container the iterator refers to (for example incrementing a
list iterator must access the pointers between nodes, which are part
of the container and so conflict with other accesses to the
container).
+ </p><p>
+ The Copy-On-Write <code class="classname">std::string</code>
implementation
+ used before GCC 5 (and with
+ <a class="link" href="using_dual_abi.html" title="Dual
ABI">_GLIBCXX_USE_CXX11_ABI=0</a>)
+ is not a standard container and does not conform to the data race
+ avoidance rules described above. For the Copy-On-Write
+ <code class="classname">std::string</code>, non-const member functions
such as
+ <code class="function">begin()</code> are considered to be modifying
accesses
+ and so must not be used concurrently with any other accesses to the
+ same object.
</p><p>Programs which follow the rules above will not encounter data
races in library code, even when using library types which share
state between distinct objects. In the example below the
diff --git a/libstdc++-v3/doc/xml/manual/using.xml
b/libstdc++-v3/doc/xml/manual/using.xml
index 92d3c0ed6b86..46b36ba7a7c7 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -2047,6 +2047,18 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
of the container and so conflict with other accesses to the
container).
</para>
+ <para>
+ The Copy-On-Write <classname>std::string</classname> implementation
+ used before GCC 5 (and with
+ <link linkend="manual.intro.using.abi">_GLIBCXX_USE_CXX11_ABI=0</link>)
+ is not a standard container and does not conform to the data race
+ avoidance rules described above. For the Copy-On-Write
+ <classname>std::string</classname>, non-const member functions such as
+ <function>begin()</function> are considered to be modifying accesses
+ and so must not be used concurrently with any other accesses to the
+ same object.
+ </para>
+
<para>Programs which follow the rules above will not encounter data
races in library code, even when using library types which share
state between distinct objects. In the example below the
