From 71dee18c43a3419fce2be80e39176ae59e01656f Mon Sep 17 00:00:00 2001
From: Howard Hinnant <hhinnant@apple.com>
Date: Fri, 8 Oct 2010 17:36:50 +0000
Subject: [PATCH] Updated atomic design docs

llvm-svn: 116065
---
 libcxx/www/atomic_design.html   | 34 +++++++++++++++++++++++++++++++++
 libcxx/www/atomic_design_a.html |  3 +++
 libcxx/www/atomic_design_b.html | 13 ++++++++-----
 3 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/libcxx/www/atomic_design.html b/libcxx/www/atomic_design.html
index 36e73244d911..87a2f6249141 100644
--- a/libcxx/www/atomic_design.html
+++ b/libcxx/www/atomic_design.html
@@ -53,6 +53,40 @@ should be identical (and conforming) for all three designs.
 </li>
 </ol>
 
+<p>
+With any design, the (back end) compiler writer should note:
+</p>
+
+<blockquote>
+<p>
+The decision to implement lock-free operations on any given type (or not) is an
+ABI-binding decision.  One can not change from treating a type as not lock free,
+to lock free (or vice-versa) without breaking your ABI.
+</p>
+
+<p>
+Example:
+</p>
+
+<blockquote><pre>
+TU1.cc
+-----------
+extern atomic&lt;long long&gt; A;
+int foo() { return A.compare_exchange_strong(w, x); }
+
+TU2.cc
+-----------
+extern atomic&lt;long long&gt; A;
+void bar() { return A.compare_exchange_strong(y, z); }
+</pre></blockquote>
+</blockquote>
+
+<p>
+If only <em>one</em> of these calls to <tt>compare_exchange_strong</tt> is
+implemented with mutex-locked code, then that mutex-locked code will not be
+executed mutually exclusively of the one implemented in a lock-free manner.
+</p>
+
 </div>
 </body>
 </html>
diff --git a/libcxx/www/atomic_design_a.html b/libcxx/www/atomic_design_a.html
index f09d0b36a532..bcb262712792 100644
--- a/libcxx/www/atomic_design_a.html
+++ b/libcxx/www/atomic_design_a.html
@@ -49,6 +49,9 @@ the memory ordering parameter.
 <font color="#C80000">// In every intrinsic signature below, type* atomic_obj may be a pointer to a</font>
 <font color="#C80000">//    volatile-qualifed type.</font>
 
+<font color="#C80000">// type must be trivially copyable</font>
+bool __atomic_is_lock_free(const type* atomic_obj);
+
 <font color="#C80000">// type must be trivially copyable</font>
 <font color="#C80000">// Behavior is defined for mem_ord = 0, 1, 2, 5</font>
 type __atomic_load(const type* atomic_obj, int mem_ord);
diff --git a/libcxx/www/atomic_design_b.html b/libcxx/www/atomic_design_b.html
index 7891050c132d..b738445be363 100644
--- a/libcxx/www/atomic_design_b.html
+++ b/libcxx/www/atomic_design_b.html
@@ -44,18 +44,21 @@ option in the spirit of completeness.
 </p>
 
 <blockquote><pre>
-<font color="#C80000">// type can be any pod</font>
+<font color="#C80000">// type must be trivially copyable</font>
+bool __atomic_is_lock_free(const type* atomic_obj);
+
+<font color="#C80000">// type must be trivially copyable</font>
 type __atomic_load_relaxed(const volatile type* atomic_obj);
 type __atomic_load_consume(const volatile type* atomic_obj);
 type __atomic_load_acquire(const volatile type* atomic_obj);
 type __atomic_load_seq_cst(const volatile type* atomic_obj);
 
-<font color="#C80000">// type can be any pod</font>
+<font color="#C80000">// type must be trivially copyable</font>
 type __atomic_store_relaxed(volatile type* atomic_obj, type desired);
 type __atomic_store_release(volatile type* atomic_obj, type desired);
 type __atomic_store_seq_cst(volatile type* atomic_obj, type desired);
 
-<font color="#C80000">// type can be any pod</font>
+<font color="#C80000">// type must be trivially copyable</font>
 type __atomic_exchange_relaxed(volatile type* atomic_obj, type desired);
 type __atomic_exchange_consume(volatile type* atomic_obj, type desired);
 type __atomic_exchange_acquire(volatile type* atomic_obj, type desired);
@@ -63,7 +66,7 @@ type __atomic_exchange_release(volatile type* atomic_obj, type desired);
 type __atomic_exchange_acq_rel(volatile type* atomic_obj, type desired);
 type __atomic_exchange_seq_cst(volatile type* atomic_obj, type desired);
 
-<font color="#C80000">// type can be any pod</font>
+<font color="#C80000">// type must be trivially copyable</font>
 bool __atomic_compare_exchange_strong_relaxed_relaxed(volatile type* atomic_obj,
                                                       type* expected,
                                                       type desired);
@@ -113,7 +116,7 @@ bool __atomic_compare_exchange_strong_seq_cst_seq_cst(volatile type* atomic_obj,
                                                       type* expected,
                                                       type desired);
 
-<font color="#C80000">// type can be any pod</font>
+<font color="#C80000">// type must be trivially copyable</font>
 bool __atomic_compare_exchange_weak_relaxed_relaxed(volatile type* atomic_obj,
                                                     type* expected,
                                                     type desired);