Add a compatibility note about why Clang rejects jumps past __block variables.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@112865 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 50 insertions, 0 deletions

diff --git a/www/compatibility.html b/www/compatibility.html
index 4ad5bc018a..8ac7d7de82 100644
--- a/www/compatibility.html
+++ b/www/compatibility.html
@@ -33,6 +33,7 @@
     <ul>
       <li><a href="#inline">C99 inline functions</a></li>
       <li><a href="#lvalue-cast">Lvalue casts</a></li>
+      <li><a href="#blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</a></li>
     </ul>
   </li>
   <li><a href="#objective-c">Objective-C compatibility</a>
@@ -135,6 +136,55 @@ example, one could use:</p>
 </pre>
 
 <!-- ======================================================================= -->
+<h3 id="blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</h3>
+<!-- ======================================================================= -->
+
+<p>Clang disallows jumps into the scope of a <tt>__block</tt> variable, similar
+to the manner in which both GCC and Clang disallow jumps into the scope of
+variables which have user defined constructors (in C++).</p>
+
+<p>Variables marked with <tt>__block</tt> require special runtime initialization
+before they can be used. A jump into the scope of a <tt>__block</tt> variable
+would bypass this initialization and therefore the variable cannot safely be
+used.</p>
+
+<p>For example, consider the following code fragment:</p>
+
+<pre>
+int f0(int c) {
+  if (c)
+    goto error;
+
+  __block int x;
+  x = 1;
+  return x;
+
+ error:
+  x = 0;
+  return x;
+}
+</pre>
+
+<p>GCC accepts this code, but it will crash at runtime along the error path,
+because the runtime setup for the storage backing the <tt>x</tt> variable will
+not have been initialized. Clang rejects this code with a hard error:</p>
+
+<pre>
+t.c:3:5: error: goto into protected scope
+    goto error;
+    ^
+t.c:5:15: note: jump bypasses setup of __block variable
+  __block int x;
+              ^
+</pre>
+
+<p>Some instances of this construct may be safe if the variable is never used
+after the jump target, however the protected scope checker does not check the
+uses of the varaible, only the scopes in which it is visible. You should rewrite
+your code to put the <tt>__block</tt> variables in a scope which is only visible
+where they are used.</p>
+
+<!-- ======================================================================= -->
 <h2 id="objective-c">Objective-C compatibility</h3>
 <!-- ======================================================================= -->