[www-releases] r225843 - Add documentation for 3.5.1
Tom Stellard
thomas.stellard at amd.com
Tue Jan 13 14:55:45 PST 2015
Added: www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersReference.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersReference.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersReference.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersReference.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,3863 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>AST Matcher Reference</title>
+<link type="text/css" rel="stylesheet" href="../menu.css" />
+<link type="text/css" rel="stylesheet" href="../content.css" />
+<style type="text/css">
+td {
+ padding: .33em;
+}
+td.doc {
+ display: none;
+ border-bottom: 1px solid black;
+}
+td.name:hover {
+ color: blue;
+ cursor: pointer;
+}
+</style>
+<script type="text/javascript">
+function toggle(id) {
+ if (!id) return;
+ row = document.getElementById(id);
+ if (row.style.display != 'table-cell')
+ row.style.display = 'table-cell';
+ else
+ row.style.display = 'none';
+}
+</script>
+</head>
+<body onLoad="toggle(location.hash.substring(1, location.hash.length - 6))">
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<h1>AST Matcher Reference</h1>
+
+<p>This document shows all currently implemented matchers. The matchers are grouped
+by category and node type they match. You can click on matcher names to show the
+matcher's source documentation.</p>
+
+<p>There are three different basic categories of matchers:
+<ul>
+<li><a href="#decl-matchers">Node Matchers:</a> Matchers that match a specific type of AST node.</li>
+<li><a href="#narrowing-matchers">Narrowing Matchers:</a> Matchers that match attributes on AST nodes.</li>
+<li><a href="#traversal-matchers">Traversal Matchers:</a> Matchers that allow traversal between AST nodes.</li>
+</ul>
+</p>
+
+<p>Within each category the matchers are ordered by node type they match on.
+Note that if a matcher can match multiple node types, it will it will appear
+multiple times. This means that by searching for Matcher<Stmt> you can
+find all matchers that can be used to match on Stmt nodes.</p>
+
+<p>The exception to that rule are matchers that can match on any node. Those
+are marked with a * and are listed in the beginning of each category.</p>
+
+<p>Note that the categorization of matchers is a great help when you combine
+them into matcher expressions. You will usually want to form matcher expressions
+that read like english sentences by alternating between node matchers and
+narrowing or traversal matchers, like this:
+<pre>
+recordDecl(hasDescendant(
+ ifStmt(hasTrueExpression(
+ expr(hasDescendant(
+ ifStmt()))))))
+</pre>
+</p>
+
+<!-- ======================================================================= -->
+<h2 id="decl-matchers">Node Matchers</h2>
+<!-- ======================================================================= -->
+
+<p>Node matchers are at the core of matcher expressions - they specify the type
+of node that is expected. Every match expression starts with a node matcher,
+which can then be further refined with a narrowing or traversal matcher. All
+traversal matchers take node matchers as their arguments.</p>
+
+<p>For convenience, all node matchers take an arbitrary number of arguments
+and implicitly act as allOf matchers.</p>
+
+<p>Node matchers are the only matchers that support the bind("id") call to
+bind the matched node to the given string, to be later retrieved from the
+match callback.</p>
+
+<p>It is important to remember that the arguments to node matchers are
+predicates on the same node, just with additional information about the type.
+This is often useful to make matcher expression more readable by inlining bind
+calls into redundant node matchers inside another node matcher:
+<pre>
+// This binds the CXXRecordDecl to "id", as the decl() matcher will stay on
+// the same node.
+recordDecl(decl().bind("id"), hasName("::MyClass"))
+</pre>
+</p>
+
+<table>
+<tr style="text-align:left"><th>Return type</th><th>Name</th><th>Parameters</th></tr>
+<!-- START_DECL_MATCHERS -->
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('ctorInitializer0')"><a name="ctorInitializer0Anchor">ctorInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="ctorInitializer0"><pre>Matches constructor initializers.
+
+Examples matches i(42).
+ class C {
+ C() : i(42) {}
+ int i;
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('accessSpecDecl0')"><a name="accessSpecDecl0Anchor">accessSpecDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AccessSpecDecl.html">AccessSpecDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="accessSpecDecl0"><pre>Matches C++ access specifier declarations.
+
+Given
+ class C {
+ public:
+ int a;
+ };
+accessSpecDecl()
+ matches 'public:'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('classTemplateDecl0')"><a name="classTemplateDecl0Anchor">classTemplateDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateDecl.html">ClassTemplateDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="classTemplateDecl0"><pre>Matches C++ class template declarations.
+
+Example matches Z
+ template<class T> class Z {};
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('classTemplateSpecializationDecl0')"><a name="classTemplateSpecializationDecl0Anchor">classTemplateSpecializationDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateSpecializationDecl.html">ClassTemplateSpecializationDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="classTemplateSpecializationDecl0"><pre>Matches C++ class template specializations.
+
+Given
+ template<typename T> class A {};
+ template<> class A<double> {};
+ A<int> a;
+classTemplateSpecializationDecl()
+ matches the specializations A<int> and A<double>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('constructorDecl0')"><a name="constructorDecl0Anchor">constructorDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="constructorDecl0"><pre>Matches C++ constructor declarations.
+
+Example matches Foo::Foo() and Foo::Foo(int)
+ class Foo {
+ public:
+ Foo();
+ Foo(int);
+ int DoSomething();
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('decl0')"><a name="decl0Anchor">decl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="decl0"><pre>Matches declarations.
+
+Examples matches X, C, and the friend declaration inside C;
+ void X();
+ class C {
+ friend X;
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('declaratorDecl0')"><a name="declaratorDecl0Anchor">declaratorDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclaratorDecl.html">DeclaratorDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="declaratorDecl0"><pre>Matches declarator declarations (field, variable, function
+and non-type template parameter declarations).
+
+Given
+ class X { int y; };
+declaratorDecl()
+ matches int y.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('destructorDecl0')"><a name="destructorDecl0Anchor">destructorDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXDestructorDecl.html">CXXDestructorDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="destructorDecl0"><pre>Matches explicit C++ destructor declarations.
+
+Example matches Foo::~Foo()
+ class Foo {
+ public:
+ virtual ~Foo();
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('enumConstantDecl0')"><a name="enumConstantDecl0Anchor">enumConstantDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumConstantDecl.html">EnumConstantDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="enumConstantDecl0"><pre>Matches enum constants.
+
+Example matches A, B, C
+ enum X {
+ A, B, C
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('enumDecl0')"><a name="enumDecl0Anchor">enumDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumDecl.html">EnumDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="enumDecl0"><pre>Matches enum declarations.
+
+Example matches X
+ enum X {
+ A, B, C
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('fieldDecl0')"><a name="fieldDecl0Anchor">fieldDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FieldDecl.html">FieldDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="fieldDecl0"><pre>Matches field declarations.
+
+Given
+ class X { int m; };
+fieldDecl()
+ matches 'm'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('friendDecl0')"><a name="friendDecl0Anchor">friendDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="friendDecl0"><pre>Matches friend declarations.
+
+Given
+ class X { friend void foo(); };
+friendDecl()
+ matches 'friend void foo()'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('functionDecl0')"><a name="functionDecl0Anchor">functionDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="functionDecl0"><pre>Matches function declarations.
+
+Example matches f
+ void f();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('functionTemplateDecl0')"><a name="functionTemplateDecl0Anchor">functionTemplateDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionTemplateDecl.html">FunctionTemplateDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="functionTemplateDecl0"><pre>Matches C++ function template declarations.
+
+Example matches f
+ template<class T> void f(T t) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('methodDecl0')"><a name="methodDecl0Anchor">methodDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="methodDecl0"><pre>Matches method declarations.
+
+Example matches y
+ class X { void y(); };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('namedDecl0')"><a name="namedDecl0Anchor">namedDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="namedDecl0"><pre>Matches a declaration of anything that could have a name.
+
+Example matches X, S, the anonymous union type, i, and U;
+ typedef int X;
+ struct S {
+ union {
+ int i;
+ } U;
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('namespaceDecl0')"><a name="namespaceDecl0Anchor">namespaceDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamespaceDecl.html">NamespaceDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="namespaceDecl0"><pre>Matches a declaration of a namespace.
+
+Given
+ namespace {}
+ namespace test {}
+namespaceDecl()
+ matches "namespace {}" and "namespace test {}"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('parmVarDecl0')"><a name="parmVarDecl0Anchor">parmVarDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="parmVarDecl0"><pre>Matches parameter variable declarations.
+
+Given
+ void f(int x);
+parmVarDecl()
+ matches int x.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('recordDecl0')"><a name="recordDecl0Anchor">recordDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="recordDecl0"><pre>Matches C++ class declarations.
+
+Example matches X, Z
+ class X;
+ template<class T> class Z {};
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('unresolvedUsingValueDecl0')"><a name="unresolvedUsingValueDecl0Anchor">unresolvedUsingValueDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingValueDecl.html">UnresolvedUsingValueDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="unresolvedUsingValueDecl0"><pre>Matches unresolved using value declarations.
+
+Given
+ template<typename X>
+ class C : private X {
+ using X::x;
+ };
+unresolvedUsingValueDecl()
+ matches using X::x </pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('usingDecl0')"><a name="usingDecl0Anchor">usingDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingDecl.html">UsingDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="usingDecl0"><pre>Matches using declarations.
+
+Given
+ namespace X { int x; }
+ using X::x;
+usingDecl()
+ matches using X::x </pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('varDecl0')"><a name="varDecl0Anchor">varDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="varDecl0"><pre>Matches variable declarations.
+
+Note: this does not match declarations of member variables, which are
+"field" declarations in Clang parlance.
+
+Example matches a
+ int a;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('nestedNameSpecifierLoc0')"><a name="nestedNameSpecifierLoc0Anchor">nestedNameSpecifierLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="nestedNameSpecifierLoc0"><pre>Same as nestedNameSpecifier but matches NestedNameSpecifierLoc.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>></td><td class="name" onclick="toggle('nestedNameSpecifier0')"><a name="nestedNameSpecifier0Anchor">nestedNameSpecifier</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="nestedNameSpecifier0"><pre>Matches nested name specifiers.
+
+Given
+ namespace ns {
+ struct A { static void f(); };
+ void A::f() {}
+ void g() { A::f(); }
+ }
+ ns::A a;
+nestedNameSpecifier()
+ matches "ns::" and both "A::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('qualType0')"><a name="qualType0Anchor">qualType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="qualType0"><pre>Matches QualTypes in the clang AST.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('arraySubscriptExpr0')"><a name="arraySubscriptExpr0Anchor">arraySubscriptExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="arraySubscriptExpr0"><pre>Matches array subscript expressions.
+
+Given
+ int i = a[1];
+arraySubscriptExpr()
+ matches "a[1]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('asmStmt0')"><a name="asmStmt0Anchor">asmStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AsmStmt.html">AsmStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="asmStmt0"><pre>Matches asm statements.
+
+ int i = 100;
+ __asm("mov al, 2");
+asmStmt()
+ matches '__asm("mov al, 2")'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('binaryOperator0')"><a name="binaryOperator0Anchor">binaryOperator</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="binaryOperator0"><pre>Matches binary operator expressions.
+
+Example matches a || b
+ !(a || b)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('bindTemporaryExpr0')"><a name="bindTemporaryExpr0Anchor">bindTemporaryExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBindTemporaryExpr.html">CXXBindTemporaryExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="bindTemporaryExpr0"><pre>Matches nodes where temporaries are created.
+
+Example matches FunctionTakesString(GetStringByValue())
+ (matcher = bindTemporaryExpr())
+ FunctionTakesString(GetStringByValue());
+ FunctionTakesStringByPointer(GetStringPointer());
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('boolLiteral0')"><a name="boolLiteral0Anchor">boolLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="boolLiteral0"><pre>Matches bool literals.
+
+Example matches true
+ true
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('breakStmt0')"><a name="breakStmt0Anchor">breakStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BreakStmt.html">BreakStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="breakStmt0"><pre>Matches break statements.
+
+Given
+ while (true) { break; }
+breakStmt()
+ matches 'break'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cStyleCastExpr0')"><a name="cStyleCastExpr0Anchor">cStyleCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CStyleCastExpr.html">CStyleCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="cStyleCastExpr0"><pre>Matches a C-style cast expression.
+
+Example: Matches (int*) 2.2f in
+ int i = (int) 2.2f;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('callExpr0')"><a name="callExpr0Anchor">callExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="callExpr0"><pre>Matches call expressions.
+
+Example matches x.y() and y()
+ X x;
+ x.y();
+ y();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('caseStmt0')"><a name="caseStmt0Anchor">caseStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CaseStmt.html">CaseStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="caseStmt0"><pre>Matches case statements inside switch statements.
+
+Given
+ switch(a) { case 42: break; default: break; }
+caseStmt()
+ matches 'case 42: break;'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('castExpr0')"><a name="castExpr0Anchor">castExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="castExpr0"><pre>Matches any cast nodes of Clang's AST.
+
+Example: castExpr() matches each of the following:
+ (int) 3;
+ const_cast<Expr *>(SubExpr);
+ char c = 0;
+but does not match
+ int i = (0);
+ int k = 0;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('catchStmt0')"><a name="catchStmt0Anchor">catchStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCatchStmt.html">CXXCatchStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="catchStmt0"><pre>Matches catch statements.
+
+ try {} catch(int i) {}
+catchStmt()
+ matches 'catch(int i)'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('characterLiteral0')"><a name="characterLiteral0Anchor">characterLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="characterLiteral0"><pre>Matches character literals (also matches wchar_t).
+
+Not matching Hex-encoded chars (e.g. 0x1234, which is a IntegerLiteral),
+though.
+
+Example matches 'a', L'a'
+ char ch = 'a'; wchar_t chw = L'a';
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('compoundLiteralExpr0')"><a name="compoundLiteralExpr0Anchor">compoundLiteralExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundLiteralExpr.html">CompoundLiteralExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="compoundLiteralExpr0"><pre>Matches compound (i.e. non-scalar) literals
+
+Example match: {1}, (1, 2)
+ int array[4] = {1}; vector int myvec = (vector int)(1, 2);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('compoundStmt0')"><a name="compoundStmt0Anchor">compoundStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="compoundStmt0"><pre>Matches compound statements.
+
+Example matches '{}' and '{{}}'in 'for (;;) {{}}'
+ for (;;) {{}}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('conditionalOperator0')"><a name="conditionalOperator0Anchor">conditionalOperator</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="conditionalOperator0"><pre>Matches conditional operator expressions.
+
+Example matches a ? b : c
+ (a ? b : c) + 42
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('constCastExpr0')"><a name="constCastExpr0Anchor">constCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstCastExpr.html">CXXConstCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="constCastExpr0"><pre>Matches a const_cast expression.
+
+Example: Matches const_cast<int*>(&r) in
+ int n = 42;
+ const int &r(n);
+ int* p = const_cast<int*>(&r);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('constructExpr0')"><a name="constructExpr0Anchor">constructExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="constructExpr0"><pre>Matches constructor call expressions (including implicit ones).
+
+Example matches string(ptr, n) and ptr within arguments of f
+ (matcher = constructExpr())
+ void f(const string &a, const string &b);
+ char *ptr;
+ int n;
+ f(string(ptr, n), ptr);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('continueStmt0')"><a name="continueStmt0Anchor">continueStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ContinueStmt.html">ContinueStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="continueStmt0"><pre>Matches continue statements.
+
+Given
+ while (true) { continue; }
+continueStmt()
+ matches 'continue'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('declRefExpr0')"><a name="declRefExpr0Anchor">declRefExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="declRefExpr0"><pre>Matches expressions that refer to declarations.
+
+Example matches x in if (x)
+ bool x;
+ if (x) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('declStmt0')"><a name="declStmt0Anchor">declStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">DeclStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="declStmt0"><pre>Matches declaration statements.
+
+Given
+ int a;
+declStmt()
+ matches 'int a'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('defaultArgExpr0')"><a name="defaultArgExpr0Anchor">defaultArgExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXDefaultArgExpr.html">CXXDefaultArgExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="defaultArgExpr0"><pre>Matches the value of a default argument at the call site.
+
+Example matches the CXXDefaultArgExpr placeholder inserted for the
+ default value of the second parameter in the call expression f(42)
+ (matcher = defaultArgExpr())
+ void f(int x, int y = 0);
+ f(42);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('defaultStmt0')"><a name="defaultStmt0Anchor">defaultStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DefaultStmt.html">DefaultStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="defaultStmt0"><pre>Matches default statements inside switch statements.
+
+Given
+ switch(a) { case 42: break; default: break; }
+defaultStmt()
+ matches 'default: break;'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('deleteExpr0')"><a name="deleteExpr0Anchor">deleteExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXDeleteExpr.html">CXXDeleteExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="deleteExpr0"><pre>Matches delete expressions.
+
+Given
+ delete X;
+deleteExpr()
+ matches 'delete X'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('doStmt0')"><a name="doStmt0Anchor">doStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="doStmt0"><pre>Matches do statements.
+
+Given
+ do {} while (true);
+doStmt()
+ matches 'do {} while(true)'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('dynamicCastExpr0')"><a name="dynamicCastExpr0Anchor">dynamicCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXDynamicCastExpr.html">CXXDynamicCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="dynamicCastExpr0"><pre>Matches a dynamic_cast expression.
+
+Example:
+ dynamicCastExpr()
+matches
+ dynamic_cast<D*>(&b);
+in
+ struct B { virtual ~B() {} }; struct D : B {};
+ B b;
+ D* p = dynamic_cast<D*>(&b);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('explicitCastExpr0')"><a name="explicitCastExpr0Anchor">explicitCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ExplicitCastExpr.html">ExplicitCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="explicitCastExpr0"><pre>Matches explicit cast expressions.
+
+Matches any cast expression written in user code, whether it be a
+C-style cast, a functional-style cast, or a keyword cast.
+
+Does not match implicit conversions.
+
+Note: the name "explicitCast" is chosen to match Clang's terminology, as
+Clang uses the term "cast" to apply to implicit conversions as well as to
+actual cast expressions.
+
+hasDestinationType.
+
+Example: matches all five of the casts in
+ int((int)(reinterpret_cast<int>(static_cast<int>(const_cast<int>(42)))))
+but does not match the implicit conversion in
+ long ell = 42;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('expr0')"><a name="expr0Anchor">expr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="expr0"><pre>Matches expressions.
+
+Example matches x()
+ void f() { x(); }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('exprWithCleanups0')"><a name="exprWithCleanups0Anchor">exprWithCleanups</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ExprWithCleanups.html">ExprWithCleanups</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="exprWithCleanups0"><pre>Matches expressions that introduce cleanups to be run at the end
+of the sub-expression's evaluation.
+
+Example matches std::string()
+ const std::string str = std::string();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('floatLiteral0')"><a name="floatLiteral0Anchor">floatLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="floatLiteral0"><pre>Matches float literals of all sizes encodings, e.g.
+1.0, 1.0f, 1.0L and 1e10.
+
+Does not match implicit conversions such as
+ float a = 10;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('forRangeStmt0')"><a name="forRangeStmt0Anchor">forRangeStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="forRangeStmt0"><pre>Matches range-based for statements.
+
+forRangeStmt() matches 'for (auto a : i)'
+ int i[] = {1, 2, 3}; for (auto a : i);
+ for(int j = 0; j < 5; ++j);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('forStmt0')"><a name="forStmt0Anchor">forStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="forStmt0"><pre>Matches for statements.
+
+Example matches 'for (;;) {}'
+ for (;;) {}
+ int i[] = {1, 2, 3}; for (auto a : i);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('functionalCastExpr0')"><a name="functionalCastExpr0Anchor">functionalCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="functionalCastExpr0"><pre>Matches functional cast expressions
+
+Example: Matches Foo(bar);
+ Foo f = bar;
+ Foo g = (Foo) bar;
+ Foo h = Foo(bar);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('gotoStmt0')"><a name="gotoStmt0Anchor">gotoStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1GotoStmt.html">GotoStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="gotoStmt0"><pre>Matches goto statements.
+
+Given
+ goto FOO;
+ FOO: bar();
+gotoStmt()
+ matches 'goto FOO'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('ifStmt0')"><a name="ifStmt0Anchor">ifStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="ifStmt0"><pre>Matches if statements.
+
+Example matches 'if (x) {}'
+ if (x) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('implicitCastExpr0')"><a name="implicitCastExpr0Anchor">implicitCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ImplicitCastExpr.html">ImplicitCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="implicitCastExpr0"><pre>Matches the implicit cast nodes of Clang's AST.
+
+This matches many different places, including function call return value
+eliding, as well as any type conversions.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('initListExpr0')"><a name="initListExpr0Anchor">initListExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InitListExpr.html">InitListExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="initListExpr0"><pre>Matches init list expressions.
+
+Given
+ int a[] = { 1, 2 };
+ struct B { int x, y; };
+ B b = { 5, 6 };
+initList()
+ matches "{ 1, 2 }" and "{ 5, 6 }"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('integerLiteral0')"><a name="integerLiteral0Anchor">integerLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="integerLiteral0"><pre>Matches integer literals of all sizes encodings, e.g.
+1, 1L, 0x1 and 1U.
+
+Does not match character-encoded integers such as L'a'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('labelStmt0')"><a name="labelStmt0Anchor">labelStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="labelStmt0"><pre>Matches label statements.
+
+Given
+ goto FOO;
+ FOO: bar();
+labelStmt()
+ matches 'FOO:'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('lambdaExpr0')"><a name="lambdaExpr0Anchor">lambdaExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="lambdaExpr0"><pre>Matches lambda expressions.
+
+Example matches [&](){return 5;}
+ [&](){return 5;}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('materializeTemporaryExpr0')"><a name="materializeTemporaryExpr0Anchor">materializeTemporaryExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MaterializeTemporaryExpr.html">MaterializeTemporaryExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="materializeTemporaryExpr0"><pre>Matches nodes where temporaries are materialized.
+
+Example: Given
+ struct T {void func()};
+ T f();
+ void g(T);
+materializeTemporaryExpr() matches 'f()' in these statements
+ T u(f());
+ g(f());
+but does not match
+ f();
+ f().func();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('memberCallExpr0')"><a name="memberCallExpr0Anchor">memberCallExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="memberCallExpr0"><pre>Matches member call expressions.
+
+Example matches x.y()
+ X x;
+ x.y();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('memberExpr0')"><a name="memberExpr0Anchor">memberExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="memberExpr0"><pre>Matches member expressions.
+
+Given
+ class Y {
+ void x() { this->x(); x(); Y y; y.x(); a; this->b; Y::b; }
+ int a; static int b;
+ };
+memberExpr()
+ matches this->x, x, y.x, a, this->b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('newExpr0')"><a name="newExpr0Anchor">newExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="newExpr0"><pre>Matches new expressions.
+
+Given
+ new X;
+newExpr()
+ matches 'new X'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('nullPtrLiteralExpr0')"><a name="nullPtrLiteralExpr0Anchor">nullPtrLiteralExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXNullPtrLiteralExpr.html">CXXNullPtrLiteralExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="nullPtrLiteralExpr0"><pre>Matches nullptr literal.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('nullStmt0')"><a name="nullStmt0Anchor">nullStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NullStmt.html">NullStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="nullStmt0"><pre>Matches null statements.
+
+ foo();;
+nullStmt()
+ matches the second ';'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('operatorCallExpr0')"><a name="operatorCallExpr0Anchor">operatorCallExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="operatorCallExpr0"><pre>Matches overloaded operator calls.
+
+Note that if an operator isn't overloaded, it won't match. Instead, use
+binaryOperator matcher.
+Currently it does not match operators such as new delete.
+FIXME: figure out why these do not match?
+
+Example matches both operator<<((o << b), c) and operator<<(o, b)
+ (matcher = operatorCallExpr())
+ ostream &operator<< (ostream &out, int i) { };
+ ostream &o; int b = 1, c = 1;
+ o << b << c;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('reinterpretCastExpr0')"><a name="reinterpretCastExpr0Anchor">reinterpretCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXReinterpretCastExpr.html">CXXReinterpretCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="reinterpretCastExpr0"><pre>Matches a reinterpret_cast expression.
+
+Either the source expression or the destination type can be matched
+using has(), but hasDestinationType() is more specific and can be
+more readable.
+
+Example matches reinterpret_cast<char*>(&p) in
+ void* p = reinterpret_cast<char*>(&p);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('returnStmt0')"><a name="returnStmt0Anchor">returnStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html">ReturnStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="returnStmt0"><pre>Matches return statements.
+
+Given
+ return 1;
+returnStmt()
+ matches 'return 1'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('staticCastExpr0')"><a name="staticCastExpr0Anchor">staticCastExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXStaticCastExpr.html">CXXStaticCastExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="staticCastExpr0"><pre>Matches a C++ static_cast expression.
+
+hasDestinationType
+reinterpretCast
+
+Example:
+ staticCastExpr()
+matches
+ static_cast<long>(8)
+in
+ long eight(static_cast<long>(8));
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('stmt0')"><a name="stmt0Anchor">stmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="stmt0"><pre>Matches statements.
+
+Given
+ { ++a; }
+stmt()
+ matches both the compound statement '{ ++a; }' and '++a'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('stringLiteral0')"><a name="stringLiteral0Anchor">stringLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1StringLiteral.html">StringLiteral</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="stringLiteral0"><pre>Matches string literals (also matches wide string literals).
+
+Example matches "abcd", L"abcd"
+ char *s = "abcd"; wchar_t *ws = L"abcd"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('switchCase0')"><a name="switchCase0Anchor">switchCase</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchCase.html">SwitchCase</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="switchCase0"><pre>Matches case and default statements inside switch statements.
+
+Given
+ switch(a) { case 42: break; default: break; }
+switchCase()
+ matches 'case 42: break;' and 'default: break;'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('switchStmt0')"><a name="switchStmt0Anchor">switchStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchStmt.html">SwitchStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="switchStmt0"><pre>Matches switch statements.
+
+Given
+ switch(a) { case 42: break; default: break; }
+switchStmt()
+ matches 'switch(a)'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('temporaryObjectExpr0')"><a name="temporaryObjectExpr0Anchor">temporaryObjectExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXTemporaryObjectExpr.html">CXXTemporaryObjectExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="temporaryObjectExpr0"><pre>Matches functional cast expressions having N != 1 arguments
+
+Example: Matches Foo(bar, bar)
+ Foo h = Foo(bar, bar);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('thisExpr0')"><a name="thisExpr0Anchor">thisExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXThisExpr.html">CXXThisExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="thisExpr0"><pre>Matches implicit and explicit this expressions.
+
+Example matches the implicit this expression in "return i".
+ (matcher = thisExpr())
+struct foo {
+ int i;
+ int f() { return i; }
+};
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('throwExpr0')"><a name="throwExpr0Anchor">throwExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXThrowExpr.html">CXXThrowExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="throwExpr0"><pre>Matches throw expressions.
+
+ try { throw 5; } catch(int i) {}
+throwExpr()
+ matches 'throw 5'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('tryStmt0')"><a name="tryStmt0Anchor">tryStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXTryStmt.html">CXXTryStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="tryStmt0"><pre>Matches try statements.
+
+ try {} catch(int i) {}
+tryStmt()
+ matches 'try {}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('unaryExprOrTypeTraitExpr0')"><a name="unaryExprOrTypeTraitExpr0Anchor">unaryExprOrTypeTraitExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="unaryExprOrTypeTraitExpr0"><pre>Matches sizeof (C99), alignof (C++11) and vec_step (OpenCL)
+
+Given
+ Foo x = bar;
+ int y = sizeof(x) + alignof(x);
+unaryExprOrTypeTraitExpr()
+ matches sizeof(x) and alignof(x)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('unaryOperator0')"><a name="unaryOperator0Anchor">unaryOperator</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryOperator.html">UnaryOperator</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="unaryOperator0"><pre>Matches unary operator expressions.
+
+Example matches !a
+ !a || b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('unresolvedConstructExpr0')"><a name="unresolvedConstructExpr0Anchor">unresolvedConstructExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXUnresolvedConstructExpr.html">CXXUnresolvedConstructExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="unresolvedConstructExpr0"><pre>Matches unresolved constructor call expressions.
+
+Example matches T(t) in return statement of f
+ (matcher = unresolvedConstructExpr())
+ template <typename T>
+ void f(const T& t) { return T(t); }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('userDefinedLiteral0')"><a name="userDefinedLiteral0Anchor">userDefinedLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UserDefinedLiteral.html">UserDefinedLiteral</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="userDefinedLiteral0"><pre>Matches user defined literal operator call.
+
+Example match: "foo"_suffix
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('whileStmt0')"><a name="whileStmt0Anchor">whileStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1WhileStmt.html">WhileStmt</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="whileStmt0"><pre>Matches while statements.
+
+Given
+ while (true) {}
+whileStmt()
+ matches 'while (true) {}'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('typeLoc0')"><a name="typeLoc0Anchor">typeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="typeLoc0"><pre>Matches TypeLocs in the clang AST.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('arrayType0')"><a name="arrayType0Anchor">arrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="arrayType0"><pre>Matches all kinds of arrays.
+
+Given
+ int a[] = { 2, 3 };
+ int b[4];
+ void f() { int c[a[0]]; }
+arrayType()
+ matches "int a[]", "int b[4]" and "int c[a[0]]";
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('atomicType0')"><a name="atomicType0Anchor">atomicType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AtomicType.html">AtomicType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="atomicType0"><pre>Matches atomic types.
+
+Given
+ _Atomic(int) i;
+atomicType()
+ matches "_Atomic(int) i"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('autoType0')"><a name="autoType0Anchor">autoType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AutoType.html">AutoType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="autoType0"><pre>Matches types nodes representing C++11 auto types.
+
+Given:
+ auto n = 4;
+ int v[] = { 2, 3 }
+ for (auto i : v) { }
+autoType()
+ matches "auto n" and "auto i"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('blockPointerType0')"><a name="blockPointerType0Anchor">blockPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="blockPointerType0"><pre>Matches block pointer types, i.e. types syntactically represented as
+"void (^)(int)".
+
+The pointee is always required to be a FunctionType.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('builtinType0')"><a name="builtinType0Anchor">builtinType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BuiltinType.html">BuiltinType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="builtinType0"><pre>Matches builtin Types.
+
+Given
+ struct A {};
+ A a;
+ int b;
+ float c;
+ bool d;
+builtinType()
+ matches "int b", "float c" and "bool d"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('complexType0')"><a name="complexType0Anchor">complexType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="complexType0"><pre>Matches C99 complex types.
+
+Given
+ _Complex float f;
+complexType()
+ matches "_Complex float f"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('constantArrayType0')"><a name="constantArrayType0Anchor">constantArrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConstantArrayType.html">ConstantArrayType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="constantArrayType0"><pre>Matches C arrays with a specified constant size.
+
+Given
+ void() {
+ int a[2];
+ int b[] = { 2, 3 };
+ int c[b[0]];
+ }
+constantArrayType()
+ matches "int a[2]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('dependentSizedArrayType0')"><a name="dependentSizedArrayType0Anchor">dependentSizedArrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DependentSizedArrayType.html">DependentSizedArrayType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="dependentSizedArrayType0"><pre>Matches C++ arrays whose size is a value-dependent expression.
+
+Given
+ template<typename T, int Size>
+ class array {
+ T data[Size];
+ };
+dependentSizedArrayType
+ matches "T data[Size]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('elaboratedType0')"><a name="elaboratedType0Anchor">elaboratedType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ElaboratedType.html">ElaboratedType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="elaboratedType0"><pre>Matches types specified with an elaborated type keyword or with a
+qualified name.
+
+Given
+ namespace N {
+ namespace M {
+ class D {};
+ }
+ }
+ class C {};
+
+ class C c;
+ N::M::D d;
+
+elaboratedType() matches the type of the variable declarations of both
+c and d.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('functionType0')"><a name="functionType0Anchor">functionType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionType.html">FunctionType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="functionType0"><pre>Matches FunctionType nodes.
+
+Given
+ int (*f)(int);
+ void g();
+functionType()
+ matches "int (*f)(int)" and the type of "g".
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('incompleteArrayType0')"><a name="incompleteArrayType0Anchor">incompleteArrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IncompleteArrayType.html">IncompleteArrayType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="incompleteArrayType0"><pre>Matches C arrays with unspecified size.
+
+Given
+ int a[] = { 2, 3 };
+ int b[42];
+ void f(int c[]) { int d[a[0]]; };
+incompleteArrayType()
+ matches "int a[]" and "int c[]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('lValueReferenceType0')"><a name="lValueReferenceType0Anchor">lValueReferenceType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LValueReferenceType.html">LValueReferenceType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="lValueReferenceType0"><pre>Matches lvalue reference types.
+
+Given:
+ int *a;
+ int &b = *a;
+ int &&c = 1;
+ auto &d = b;
+ auto &&e = c;
+ auto &&f = 2;
+ int g = 5;
+
+lValueReferenceType() matches the types of b, d, and e. e is
+matched since the type is deduced as int& by reference collapsing rules.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('memberPointerType0')"><a name="memberPointerType0Anchor">memberPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="memberPointerType0"><pre>Matches member pointer types.
+Given
+ struct A { int i; }
+ A::* ptr = A::i;
+memberPointerType()
+ matches "A::* ptr"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('parenType0')"><a name="parenType0Anchor">parenType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParenType.html">ParenType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="parenType0"><pre>Matches ParenType nodes.
+
+Given
+ int (*ptr_to_array)[4];
+ int *array_of_ptrs[4];
+
+varDecl(hasType(pointsTo(parenType()))) matches ptr_to_array but not
+array_of_ptrs.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('pointerType0')"><a name="pointerType0Anchor">pointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="pointerType0"><pre>Matches pointer types.
+
+Given
+ int *a;
+ int &b = *a;
+ int c = 5;
+pointerType()
+ matches "int *a"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('rValueReferenceType0')"><a name="rValueReferenceType0Anchor">rValueReferenceType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RValueReferenceType.html">RValueReferenceType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="rValueReferenceType0"><pre>Matches rvalue reference types.
+
+Given:
+ int *a;
+ int &b = *a;
+ int &&c = 1;
+ auto &d = b;
+ auto &&e = c;
+ auto &&f = 2;
+ int g = 5;
+
+rValueReferenceType() matches the types of c and f. e is not
+matched as it is deduced to int& by reference collapsing rules.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('recordType0')"><a name="recordType0Anchor">recordType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="recordType0"><pre>Matches record types (e.g. structs, classes).
+
+Given
+ class C {};
+ struct S {};
+
+ C c;
+ S s;
+
+recordType() matches the type of the variable declarations of both c
+and s.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('referenceType0')"><a name="referenceType0Anchor">referenceType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="referenceType0"><pre>Matches both lvalue and rvalue reference types.
+
+Given
+ int *a;
+ int &b = *a;
+ int &&c = 1;
+ auto &d = b;
+ auto &&e = c;
+ auto &&f = 2;
+ int g = 5;
+
+referenceType() matches the types of b, c, d, e, and f.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('templateSpecializationType0')"><a name="templateSpecializationType0Anchor">templateSpecializationType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="templateSpecializationType0"><pre>Matches template specialization types.
+
+Given
+ template <typename T>
+ class C { };
+
+ template class C<int>; A
+ C<char> var; B
+
+templateSpecializationType() matches the type of the explicit
+instantiation in A and the type of the variable declaration in B.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('type0')"><a name="type0Anchor">type</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="type0"><pre>Matches Types in the clang AST.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('typedefType0')"><a name="typedefType0Anchor">typedefType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="typedefType0"><pre>Matches typedef types.
+
+Given
+ typedef int X;
+typedefType()
+ matches "typedef int X"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('unaryTransformType0')"><a name="unaryTransformType0Anchor">unaryTransformType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryTransformType.html">UnaryTransformType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="unaryTransformType0"><pre>Matches types nodes representing unary type transformations.
+
+Given:
+ typedef __underlying_type(T) type;
+unaryTransformType()
+ matches "__underlying_type(T)"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('variableArrayType0')"><a name="variableArrayType0Anchor">variableArrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VariableArrayType.html">VariableArrayType</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="variableArrayType0"><pre>Matches C arrays with a specified size that is not an
+integer-constant-expression.
+
+Given
+ void f() {
+ int a[] = { 2, 3 }
+ int b[42];
+ int c[a[0]];
+variableArrayType()
+ matches "int c[a[0]]"
+</pre></td></tr>
+
+<!--END_DECL_MATCHERS -->
+</table>
+
+<!-- ======================================================================= -->
+<h2 id="narrowing-matchers">Narrowing Matchers</h2>
+<!-- ======================================================================= -->
+
+<p>Narrowing matchers match certain attributes on the current node, thus
+narrowing down the set of nodes of the current type to match on.</p>
+
+<p>There are special logical narrowing matchers (allOf, anyOf, anything and unless)
+which allow users to create more powerful match expressions.</p>
+
+<table>
+<tr style="text-align:left"><th>Return type</th><th>Name</th><th>Parameters</th></tr>
+<!-- START_NARROWING_MATCHERS -->
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('allOf0')"><a name="allOf0Anchor">allOf</a></td><td>Matcher<*>, ..., Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="allOf0"><pre>Matches if all given matchers match.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('anyOf0')"><a name="anyOf0Anchor">anyOf</a></td><td>Matcher<*>, ..., Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="anyOf0"><pre>Matches if any of the given matchers matches.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('anything0')"><a name="anything0Anchor">anything</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="anything0"><pre>Matches any node.
+
+Useful when another matcher requires a child matcher, but there's no
+additional constraint. This will often be used with an explicit conversion
+to an internal::Matcher<> type such as TypeMatcher.
+
+Example: DeclarationMatcher(anything()) matches all declarations, e.g.,
+"int* p" and "void f()" in
+ int* p;
+ void f();
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('unless0')"><a name="unless0Anchor">unless</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="unless0"><pre>Matches if the provided matcher does not match.
+
+Example matches Y (matcher = recordDecl(unless(hasName("X"))))
+ class X {};
+ class Y {};
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasOperatorName0')"><a name="hasOperatorName0Anchor">hasOperatorName</a></td><td>std::string Name</td></tr>
+<tr><td colspan="4" class="doc" id="hasOperatorName0"><pre>Matches the operator Name of operator expressions (binary or
+unary).
+
+Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
+ !(a || b)
+</pre></td></tr>
+
+
+<tr><td>Matcher<CXXBoolLiteral></td><td class="name" onclick="toggle('equals2')"><a name="equals2Anchor">equals</a></td><td>ValueT Value</td></tr>
+<tr><td colspan="4" class="doc" id="equals2"><pre>Matches literals that are equal to the given value.
+
+Example matches true (matcher = boolLiteral(equals(true)))
+ true
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<CXXBoolLiteral>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('argumentCountIs1')"><a name="argumentCountIs1Anchor">argumentCountIs</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="argumentCountIs1"><pre>Checks that a call expression or a constructor call expression has
+a specific number of arguments (including absent default arguments).
+
+Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+ void f(int x, int y);
+ f(0, 0);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('isListInitialization0')"><a name="isListInitialization0Anchor">isListInitialization</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isListInitialization0"><pre>Matches a constructor call expression which uses list initialization.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('isWritten0')"><a name="isWritten0Anchor">isWritten</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isWritten0"><pre>Matches a constructor initializer if it is explicitly written in
+code (as opposed to implicitly added by the compiler).
+
+Given
+ struct Foo {
+ Foo() { }
+ Foo(int) : foo_("A") { }
+ string foo_;
+ };
+constructorDecl(hasAnyConstructorInitializer(isWritten()))
+ will match Foo(int), but not Foo()
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('hasOverloadedOperatorName0')"><a name="hasOverloadedOperatorName0Anchor">hasOverloadedOperatorName</a></td><td>StringRef Name</td></tr>
+<tr><td colspan="4" class="doc" id="hasOverloadedOperatorName0"><pre>Matches overloaded operator names.
+
+Matches overloaded operator names specified in strings without the
+"operator" prefix: e.g. "<<".
+
+Given:
+ class A { int operator*(); };
+ const A &operator<<(const A &a, const A &b);
+ A a;
+ a << a; <-- This matches
+
+operatorCallExpr(hasOverloadedOperatorName("<<"))) matches the specified
+line and recordDecl(hasMethod(hasOverloadedOperatorName("*"))) matches
+the declaration of A.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isConst0')"><a name="isConst0Anchor">isConst</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isConst0"><pre>Matches if the given method declaration is const.
+
+Given
+struct A {
+ void foo() const;
+ void bar();
+};
+
+methodDecl(isConst()) matches A::foo() but not A::bar()
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isOverride0')"><a name="isOverride0Anchor">isOverride</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isOverride0"><pre>Matches if the given method declaration overrides another method.
+
+Given
+ class A {
+ public:
+ virtual void x();
+ };
+ class B : public A {
+ public:
+ virtual void x();
+ };
+ matches B::x
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isPure0')"><a name="isPure0Anchor">isPure</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isPure0"><pre>Matches if the given method declaration is pure.
+
+Given
+ class A {
+ public:
+ virtual void x() = 0;
+ };
+ matches A::x
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isVirtual0')"><a name="isVirtual0Anchor">isVirtual</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isVirtual0"><pre>Matches if the given method declaration is virtual.
+
+Given
+ class A {
+ public:
+ virtual void x();
+ };
+ matches A::x
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('hasOverloadedOperatorName1')"><a name="hasOverloadedOperatorName1Anchor">hasOverloadedOperatorName</a></td><td>StringRef Name</td></tr>
+<tr><td colspan="4" class="doc" id="hasOverloadedOperatorName1"><pre>Matches overloaded operator names.
+
+Matches overloaded operator names specified in strings without the
+"operator" prefix: e.g. "<<".
+
+Given:
+ class A { int operator*(); };
+ const A &operator<<(const A &a, const A &b);
+ A a;
+ a << a; <-- This matches
+
+operatorCallExpr(hasOverloadedOperatorName("<<"))) matches the specified
+line and recordDecl(hasMethod(hasOverloadedOperatorName("*"))) matches
+the declaration of A.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isDerivedFrom1')"><a name="isDerivedFrom1Anchor">isDerivedFrom</a></td><td>StringRef BaseName</td></tr>
+<tr><td colspan="4" class="doc" id="isDerivedFrom1"><pre>Overloaded method as shortcut for isDerivedFrom(hasName(...)).
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isExplicitTemplateSpecialization2')"><a name="isExplicitTemplateSpecialization2Anchor">isExplicitTemplateSpecialization</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isExplicitTemplateSpecialization2"><pre>Matches explicit template specializations of function, class, or
+static member variable template instantiations.
+
+Given
+ template<typename T> void A(T t) { }
+ template<> void A(int N) { }
+functionDecl(isExplicitTemplateSpecialization())
+ matches the specialization A<int>().
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom1')"><a name="isSameOrDerivedFrom1Anchor">isSameOrDerivedFrom</a></td><td>StringRef BaseName</td></tr>
+<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom1"><pre>Overloaded method as shortcut for
+isSameOrDerivedFrom(hasName(...)).
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isTemplateInstantiation2')"><a name="isTemplateInstantiation2Anchor">isTemplateInstantiation</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isTemplateInstantiation2"><pre>Matches template instantiations of function, class, or static
+member variable template instantiations.
+
+Given
+ template <typename T> class X {}; class A {}; X<A> x;
+or
+ template <typename T> class X {}; class A {}; template class X<A>;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ matches the template instantiation of X<A>.
+
+But given
+ template <typename T> class X {}; class A {};
+ template <> class X<A> {}; X<A> x;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ does not match, as X<A> is an explicit template specialization.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('argumentCountIs0')"><a name="argumentCountIs0Anchor">argumentCountIs</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="argumentCountIs0"><pre>Checks that a call expression or a constructor call expression has
+a specific number of arguments (including absent default arguments).
+
+Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+ void f(int x, int y);
+ f(0, 0);
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals3')"><a name="equals3Anchor">equals</a></td><td>ValueT Value</td></tr>
+<tr><td colspan="4" class="doc" id="equals3"><pre>Matches literals that are equal to the given value.
+
+Example matches true (matcher = boolLiteral(equals(true)))
+ true
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<CXXBoolLiteral>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>></td><td class="name" onclick="toggle('statementCountIs0')"><a name="statementCountIs0Anchor">statementCountIs</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="statementCountIs0"><pre>Checks that a compound statement contains a specific number of
+child statements.
+
+Example: Given
+ { for (;;) {} }
+compoundStmt(statementCountIs(0)))
+ matches '{}'
+ but does not match the outer compound statement.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConstantArrayType.html">ConstantArrayType</a>></td><td class="name" onclick="toggle('hasSize0')"><a name="hasSize0Anchor">hasSize</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="hasSize0"><pre>Matches ConstantArrayType nodes that have the specified size.
+
+Given
+ int a[42];
+ int b[2 * 21];
+ int c[41], d[43];
+constantArrayType(hasSize(42))
+ matches "int a[42]" and "int b[2 * 21]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">DeclStmt</a>></td><td class="name" onclick="toggle('declCountIs0')"><a name="declCountIs0Anchor">declCountIs</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="declCountIs0"><pre>Matches declaration statements that contain a specific number of
+declarations.
+
+Example: Given
+ int a, b;
+ int c;
+ int d = 2, e;
+declCountIs(2)
+ matches 'int a, b;' and 'int d = 2, e;', but not 'int c;'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsBoundNode1')"><a name="equalsBoundNode1Anchor">equalsBoundNode</a></td><td>std::string ID</td></tr>
+<tr><td colspan="4" class="doc" id="equalsBoundNode1"><pre>Matches if a node equals a previously bound node.
+
+Matches a node if it equals the node previously bound to ID.
+
+Given
+ class X { int a; int b; };
+recordDecl(
+ has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
+ has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
+ matches the class X, as a and b have the same type.
+
+Note that when multiple matches are involved via forEach* matchers,
+equalsBoundNodes acts as a filter.
+For example:
+compoundStmt(
+ forEachDescendant(varDecl().bind("d")),
+ forEachDescendant(declRefExpr(to(decl(equalsBoundNode("d"))))))
+will trigger a match for each combination of variable declaration
+and reference to that variable declaration within a compound statement.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl *Node</td></tr>
+<tr><td colspan="4" class="doc" id="equalsNode0"><pre>Matches if a node equals another node.
+
+Decl has pointer identity in the AST.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isImplicit0')"><a name="isImplicit0Anchor">isImplicit</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isImplicit0"><pre>Matches a declaration that has been implicitly added
+by the compiler (eg. implicit defaultcopy constructors).
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isPrivate0')"><a name="isPrivate0Anchor">isPrivate</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isPrivate0"><pre>Matches private C++ declarations.
+
+Given
+ class C {
+ public: int a;
+ protected: int b;
+ private: int c;
+ };
+fieldDecl(isPrivate())
+ matches 'int c;'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isProtected0')"><a name="isProtected0Anchor">isProtected</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isProtected0"><pre>Matches protected C++ declarations.
+
+Given
+ class C {
+ public: int a;
+ protected: int b;
+ private: int c;
+ };
+fieldDecl(isProtected())
+ matches 'int b;'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isPublic0')"><a name="isPublic0Anchor">isPublic</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isPublic0"><pre>Matches public C++ declarations.
+
+Given
+ class C {
+ public: int a;
+ protected: int b;
+ private: int c;
+ };
+fieldDecl(isPublic())
+ matches 'int a;'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>></td><td class="name" onclick="toggle('equals1')"><a name="equals1Anchor">equals</a></td><td>ValueT Value</td></tr>
+<tr><td colspan="4" class="doc" id="equals1"><pre>Matches literals that are equal to the given value.
+
+Example matches true (matcher = boolLiteral(equals(true)))
+ true
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<CXXBoolLiteral>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isDefinition2')"><a name="isDefinition2Anchor">isDefinition</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isDefinition2"><pre>Matches if a declaration has a body attached.
+
+Example matches A, va, fa
+ class A {};
+ class B; Doesn't match, as it has no body.
+ int va;
+ extern int vb; Doesn't match, as it doesn't define the variable.
+ void fa() {}
+ void fb(); Doesn't match, as it has no body.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isExplicitTemplateSpecialization0')"><a name="isExplicitTemplateSpecialization0Anchor">isExplicitTemplateSpecialization</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isExplicitTemplateSpecialization0"><pre>Matches explicit template specializations of function, class, or
+static member variable template instantiations.
+
+Given
+ template<typename T> void A(T t) { }
+ template<> void A(int N) { }
+functionDecl(isExplicitTemplateSpecialization())
+ matches the specialization A<int>().
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isExternC0')"><a name="isExternC0Anchor">isExternC</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isExternC0"><pre>Matches extern "C" function declarations.
+
+Given:
+ extern "C" void f() {}
+ extern "C" { void g() {} }
+ void h() {}
+functionDecl(isExternC())
+ matches the declaration of f and g, but not the declaration h
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isTemplateInstantiation0')"><a name="isTemplateInstantiation0Anchor">isTemplateInstantiation</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isTemplateInstantiation0"><pre>Matches template instantiations of function, class, or static
+member variable template instantiations.
+
+Given
+ template <typename T> class X {}; class A {}; X<A> x;
+or
+ template <typename T> class X {}; class A {}; template class X<A>;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ matches the template instantiation of X<A>.
+
+But given
+ template <typename T> class X {}; class A {};
+ template <> class X<A> {}; X<A> x;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ does not match, as X<A> is an explicit template specialization.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('parameterCountIs0')"><a name="parameterCountIs0Anchor">parameterCountIs</a></td><td>unsigned N</td></tr>
+<tr><td colspan="4" class="doc" id="parameterCountIs0"><pre>Matches FunctionDecls that have a specific parameter count.
+
+Given
+ void f(int i) {}
+ void g(int i, int j) {}
+functionDecl(parameterCountIs(2))
+ matches g(int i, int j) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals0')"><a name="equals0Anchor">equals</a></td><td>ValueT Value</td></tr>
+<tr><td colspan="4" class="doc" id="equals0"><pre>Matches literals that are equal to the given value.
+
+Example matches true (matcher = boolLiteral(equals(true)))
+ true
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<CXXBoolLiteral>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('isArrow0')"><a name="isArrow0Anchor">isArrow</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isArrow0"><pre>Matches member expressions that are called with '->' as opposed
+to '.'.
+
+Member calls on the implicit this pointer match as called with '->'.
+
+Given
+ class Y {
+ void x() { this->x(); x(); Y y; y.x(); a; this->b; Y::b; }
+ int a;
+ static int b;
+ };
+memberExpr(isArrow())
+ matches this->x, x, y.x, a, this->b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>></td><td class="name" onclick="toggle('hasName0')"><a name="hasName0Anchor">hasName</a></td><td>std::string Name</td></tr>
+<tr><td colspan="4" class="doc" id="hasName0"><pre>Matches NamedDecl nodes that have the specified name.
+
+Supports specifying enclosing namespaces or classes by prefixing the name
+with '<enclosing>::'.
+Does not match typedefs of an underlying type with the given name.
+
+Example matches X (Name == "X")
+ class X;
+
+Example matches X (Name is one of "::a::b::X", "a::b::X", "b::X", "X")
+ namespace a { namespace b { class X; } }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>></td><td class="name" onclick="toggle('matchesName0')"><a name="matchesName0Anchor">matchesName</a></td><td>std::string RegExp</td></tr>
+<tr><td colspan="4" class="doc" id="matchesName0"><pre>Matches NamedDecl nodes whose fully qualified names contain
+a substring matched by the given RegExp.
+
+Supports specifying enclosing namespaces or classes by
+prefixing the name with '<enclosing>::'. Does not match typedefs
+of an underlying type with the given name.
+
+Example matches X (regexp == "::X")
+ class X;
+
+Example matches X (regexp is one of "::X", "^foo::.*X", among others)
+ namespace foo { namespace bar { class X; } }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('asString0')"><a name="asString0Anchor">asString</a></td><td>std::string Name</td></tr>
+<tr><td colspan="4" class="doc" id="asString0"><pre>Matches if the matched type is represented by the given string.
+
+Given
+ class Y { public: void x(); };
+ void z() { Y* y; y->x(); }
+callExpr(on(hasType(asString("class Y *"))))
+ matches y->x()
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('equalsBoundNode3')"><a name="equalsBoundNode3Anchor">equalsBoundNode</a></td><td>std::string ID</td></tr>
+<tr><td colspan="4" class="doc" id="equalsBoundNode3"><pre>Matches if a node equals a previously bound node.
+
+Matches a node if it equals the node previously bound to ID.
+
+Given
+ class X { int a; int b; };
+recordDecl(
+ has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
+ has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
+ matches the class X, as a and b have the same type.
+
+Note that when multiple matches are involved via forEach* matchers,
+equalsBoundNodes acts as a filter.
+For example:
+compoundStmt(
+ forEachDescendant(varDecl().bind("d")),
+ forEachDescendant(declRefExpr(to(decl(equalsBoundNode("d"))))))
+will trigger a match for each combination of variable declaration
+and reference to that variable declaration within a compound statement.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasLocalQualifiers0')"><a name="hasLocalQualifiers0Anchor">hasLocalQualifiers</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="hasLocalQualifiers0"><pre>Matches QualType nodes that have local CV-qualifiers attached to
+the node, not hidden within a typedef.
+
+Given
+ typedef const int const_int;
+ const_int i;
+ int *const j;
+ int *volatile k;
+ int m;
+varDecl(hasType(hasLocalQualifiers())) matches only j and k.
+i is const-qualified but the qualifier is not local.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('isConstQualified0')"><a name="isConstQualified0Anchor">isConstQualified</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isConstQualified0"><pre>Matches QualType nodes that are const-qualified, i.e., that
+include "top-level" const.
+
+Given
+ void a(int);
+ void b(int const);
+ void c(const int);
+ void d(const int*);
+ void e(int const) {};
+functionDecl(hasAnyParameter(hasType(isConstQualified())))
+ matches "void b(int const)", "void c(const int)" and
+ "void e(int const) {}". It does not match d as there
+ is no top-level const on the parameter type "const int *".
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('isInteger0')"><a name="isInteger0Anchor">isInteger</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isInteger0"><pre>Matches QualType nodes that are of integer type.
+
+Given
+ void a(int);
+ void b(long);
+ void c(double);
+functionDecl(hasAnyParameter(hasType(isInteger())))
+matches "a(int)", "b(long)", but not "c(double)".
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsBoundNode0')"><a name="equalsBoundNode0Anchor">equalsBoundNode</a></td><td>std::string ID</td></tr>
+<tr><td colspan="4" class="doc" id="equalsBoundNode0"><pre>Matches if a node equals a previously bound node.
+
+Matches a node if it equals the node previously bound to ID.
+
+Given
+ class X { int a; int b; };
+recordDecl(
+ has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
+ has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
+ matches the class X, as a and b have the same type.
+
+Note that when multiple matches are involved via forEach* matchers,
+equalsBoundNodes acts as a filter.
+For example:
+compoundStmt(
+ forEachDescendant(varDecl().bind("d")),
+ forEachDescendant(declRefExpr(to(decl(equalsBoundNode("d"))))))
+will trigger a match for each combination of variable declaration
+and reference to that variable declaration within a compound statement.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt *Node</td></tr>
+<tr><td colspan="4" class="doc" id="equalsNode1"><pre>Matches if a node equals another node.
+
+Stmt has pointer identity in the AST.
+
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>></td><td class="name" onclick="toggle('isDefinition0')"><a name="isDefinition0Anchor">isDefinition</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isDefinition0"><pre>Matches if a declaration has a body attached.
+
+Example matches A, va, fa
+ class A {};
+ class B; Doesn't match, as it has no body.
+ int va;
+ extern int vb; Doesn't match, as it doesn't define the variable.
+ void fa() {}
+ void fb(); Doesn't match, as it has no body.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('equalsBoundNode2')"><a name="equalsBoundNode2Anchor">equalsBoundNode</a></td><td>std::string ID</td></tr>
+<tr><td colspan="4" class="doc" id="equalsBoundNode2"><pre>Matches if a node equals a previously bound node.
+
+Matches a node if it equals the node previously bound to ID.
+
+Given
+ class X { int a; int b; };
+recordDecl(
+ has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
+ has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
+ matches the class X, as a and b have the same type.
+
+Note that when multiple matches are involved via forEach* matchers,
+equalsBoundNodes acts as a filter.
+For example:
+compoundStmt(
+ forEachDescendant(varDecl().bind("d")),
+ forEachDescendant(declRefExpr(to(decl(equalsBoundNode("d"))))))
+will trigger a match for each combination of variable declaration
+and reference to that variable declaration within a compound statement.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>></td><td class="name" onclick="toggle('ofKind0')"><a name="ofKind0Anchor">ofKind</a></td><td>UnaryExprOrTypeTrait Kind</td></tr>
+<tr><td colspan="4" class="doc" id="ofKind0"><pre>Matches unary expressions of a certain kind.
+
+Given
+ int x;
+ int s = sizeof(x) + alignof(x)
+unaryExprOrTypeTraitExpr(ofKind(UETT_SizeOf))
+ matches sizeof(x)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryOperator.html">UnaryOperator</a>></td><td class="name" onclick="toggle('hasOperatorName1')"><a name="hasOperatorName1Anchor">hasOperatorName</a></td><td>std::string Name</td></tr>
+<tr><td colspan="4" class="doc" id="hasOperatorName1"><pre>Matches the operator Name of operator expressions (binary or
+unary).
+
+Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
+ !(a || b)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasGlobalStorage0')"><a name="hasGlobalStorage0Anchor">hasGlobalStorage</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="hasGlobalStorage0"><pre>Matches a variable declaration that does not have local storage.
+
+Example matches y and z (matcher = varDecl(hasGlobalStorage())
+void f() {
+ int x;
+ static int y;
+}
+int z;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasLocalStorage0')"><a name="hasLocalStorage0Anchor">hasLocalStorage</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="hasLocalStorage0"><pre>Matches a variable declaration that has function scope and is a
+non-static local variable.
+
+Example matches x (matcher = varDecl(hasLocalStorage())
+void f() {
+ int x;
+ static int y;
+}
+int z;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isDefinition1')"><a name="isDefinition1Anchor">isDefinition</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isDefinition1"><pre>Matches if a declaration has a body attached.
+
+Example matches A, va, fa
+ class A {};
+ class B; Doesn't match, as it has no body.
+ int va;
+ extern int vb; Doesn't match, as it doesn't define the variable.
+ void fa() {}
+ void fb(); Doesn't match, as it has no body.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isExplicitTemplateSpecialization1')"><a name="isExplicitTemplateSpecialization1Anchor">isExplicitTemplateSpecialization</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isExplicitTemplateSpecialization1"><pre>Matches explicit template specializations of function, class, or
+static member variable template instantiations.
+
+Given
+ template<typename T> void A(T t) { }
+ template<> void A(int N) { }
+functionDecl(isExplicitTemplateSpecialization())
+ matches the specialization A<int>().
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isTemplateInstantiation1')"><a name="isTemplateInstantiation1Anchor">isTemplateInstantiation</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isTemplateInstantiation1"><pre>Matches template instantiations of function, class, or static
+member variable template instantiations.
+
+Given
+ template <typename T> class X {}; class A {}; X<A> x;
+or
+ template <typename T> class X {}; class A {}; template class X<A>;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ matches the template instantiation of X<A>.
+
+But given
+ template <typename T> class X {}; class A {};
+ template <> class X<A> {}; X<A> x;
+recordDecl(hasName("::X"), isTemplateInstantiation())
+ does not match, as X<A> is an explicit template specialization.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
+</pre></td></tr>
+
+<!--END_NARROWING_MATCHERS -->
+</table>
+
+<!-- ======================================================================= -->
+<h2 id="traversal-matchers">AST Traversal Matchers</h2>
+<!-- ======================================================================= -->
+
+<p>Traversal matchers specify the relationship to other nodes that are
+reachable from the current node.</p>
+
+<p>Note that there are special traversal matchers (has, hasDescendant, forEach and
+forEachDescendant) which work on all nodes and allow users to write more generic
+match expressions.</p>
+
+<table>
+<tr style="text-align:left"><th>Return type</th><th>Name</th><th>Parameters</th></tr>
+<!-- START_TRAVERSAL_MATCHERS -->
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('eachOf0')"><a name="eachOf0Anchor">eachOf</a></td><td>Matcher<*>, ..., Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="eachOf0"><pre>Matches if any of the given matchers matches.
+
+Unlike anyOf, eachOf will generate a match result for each
+matching submatcher.
+
+For example, in:
+ class A { int a; int b; };
+The matcher:
+ recordDecl(eachOf(has(fieldDecl(hasName("a")).bind("v")),
+ has(fieldDecl(hasName("b")).bind("v"))))
+will generate two results binding "v", the first of which binds
+the field declaration of a, the second the field declaration of
+b.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('forEachDescendant0')"><a name="forEachDescendant0Anchor">forEachDescendant</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="forEachDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the
+provided matcher.
+
+Example matches X, A, B, C
+ (matcher = recordDecl(forEachDescendant(recordDecl(hasName("X")))))
+ class X {}; Matches X, because X::X is a class of name X inside X.
+ class A { class X {}; };
+ class B { class C { class X {}; }; };
+
+DescendantT must be an AST base type.
+
+As opposed to 'hasDescendant', 'forEachDescendant' will cause a match for
+each result that matches instead of only on the first one.
+
+Note: Recursively combined ForEachDescendant can cause many matches:
+ recordDecl(forEachDescendant(recordDecl(forEachDescendant(recordDecl()))))
+will match 10 times (plus injected class name matches) on:
+ class A { class B { class C { class D { class E {}; }; }; }; };
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('forEach0')"><a name="forEach0Anchor">forEach</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="forEach0"><pre>Matches AST nodes that have child AST nodes that match the
+provided matcher.
+
+Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
+ class X {}; Matches X, because X::X is a class of name X inside X.
+ class Y { class X {}; };
+ class Z { class Y { class X {}; }; }; Does not match Z.
+
+ChildT must be an AST base type.
+
+As opposed to 'has', 'forEach' will cause a match for each result that
+matches instead of only on the first one.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('hasAncestor0')"><a name="hasAncestor0Anchor">hasAncestor</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="hasAncestor0"><pre>Matches AST nodes that have an ancestor that matches the provided
+matcher.
+
+Given
+void f() { if (true) { int x = 42; } }
+void g() { for (;;) { int x = 43; } }
+expr(integerLiteral(hasAncestor(ifStmt()))) matches 42, but not 43.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('hasDescendant0')"><a name="hasDescendant0Anchor">hasDescendant</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="hasDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the
+provided matcher.
+
+Example matches X, Y, Z
+ (matcher = recordDecl(hasDescendant(recordDecl(hasName("X")))))
+ class X {}; Matches X, because X::X is a class of name X inside X.
+ class Y { class X {}; };
+ class Z { class Y { class X {}; }; };
+
+DescendantT must be an AST base type.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('has0')"><a name="has0Anchor">has</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="has0"><pre>Matches AST nodes that have child AST nodes that match the
+provided matcher.
+
+Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+ class X {}; Matches X, because X::X is a class of name X inside X.
+ class Y { class X {}; };
+ class Z { class Y { class X {}; }; }; Does not match Z.
+
+ChildT must be an AST base type.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('hasParent0')"><a name="hasParent0Anchor">hasParent</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="hasParent0"><pre>Matches AST nodes that have a parent that matches the provided
+matcher.
+
+Given
+void f() { for (;;) { int x = 42; if (true) { int x = 43; } } }
+compoundStmt(hasParent(ifStmt())) matches "{ int x = 43; }".
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>></td><td class="name" onclick="toggle('hasBase0')"><a name="hasBase0Anchor">hasBase</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBase0"><pre>Matches the base expression of an array subscript expression.
+
+Given
+ int i[5];
+ void f() { i[1] = 42; }
+arraySubscriptExpression(hasBase(implicitCastExpr(
+ hasSourceExpression(declRefExpr()))))
+ matches i[1] with the declRefExpr() matching i
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>></td><td class="name" onclick="toggle('hasIndex0')"><a name="hasIndex0Anchor">hasIndex</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasIndex0"><pre>Matches the index expression of an array subscript expression.
+
+Given
+ int i[5];
+ void f() { i[1] = 42; }
+arraySubscriptExpression(hasIndex(integerLiteral()))
+ matches i[1] with the integerLiteral() matching 1
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayTypeLoc.html">ArrayTypeLoc</a>></td><td class="name" onclick="toggle('hasElementTypeLoc0')"><a name="hasElementTypeLoc0Anchor">hasElementTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasElementTypeLoc0"><pre>Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+ struct A {};
+ A a[7];
+ int b[7];
+arrayType(hasElementType(builtinType()))
+ matches "int b[7]"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>></td><td class="name" onclick="toggle('hasElementType0')"><a name="hasElementType0Anchor">hasElementType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasElementType0"><pre>Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+ struct A {};
+ A a[7];
+ int b[7];
+arrayType(hasElementType(builtinType()))
+ matches "int b[7]"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AtomicTypeLoc.html">AtomicTypeLoc</a>></td><td class="name" onclick="toggle('hasValueTypeLoc0')"><a name="hasValueTypeLoc0Anchor">hasValueTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasValueTypeLoc0"><pre>Matches atomic types with a specific value type.
+
+Given
+ _Atomic(int) i;
+ _Atomic(float) f;
+atomicType(hasValueType(isInteger()))
+ matches "_Atomic(int) i"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AtomicType.html">AtomicType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AtomicType.html">AtomicType</a>></td><td class="name" onclick="toggle('hasValueType0')"><a name="hasValueType0Anchor">hasValueType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasValueType0"><pre>Matches atomic types with a specific value type.
+
+Given
+ _Atomic(int) i;
+ _Atomic(float) f;
+atomicType(hasValueType(isInteger()))
+ matches "_Atomic(int) i"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AtomicType.html">AtomicType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AutoType.html">AutoType</a>></td><td class="name" onclick="toggle('hasDeducedType0')"><a name="hasDeducedType0Anchor">hasDeducedType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasDeducedType0"><pre>Matches AutoType nodes where the deduced type is a specific type.
+
+Note: There is no TypeLoc for the deduced type and thus no
+getDeducedLoc() matcher.
+
+Given
+ auto a = 1;
+ auto b = 2.0;
+autoType(hasDeducedType(isInteger()))
+ matches "auto a"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AutoType.html">AutoType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasEitherOperand0')"><a name="hasEitherOperand0Anchor">hasEitherOperand</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasEitherOperand0"><pre>Matches if either the left hand side or the right hand side of a
+binary operator matches.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasLHS0')"><a name="hasLHS0Anchor">hasLHS</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasLHS0"><pre>Matches the left hand side of binary operator expressions.
+
+Example matches a (matcher = binaryOperator(hasLHS()))
+ a || b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasRHS0')"><a name="hasRHS0Anchor">hasRHS</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasRHS0"><pre>Matches the right hand side of binary operator expressions.
+
+Example matches b (matcher = binaryOperator(hasRHS()))
+ a || b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerTypeLoc.html">BlockPointerTypeLoc</a>></td><td class="name" onclick="toggle('pointeeLoc0')"><a name="pointeeLoc0Anchor">pointeeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointeeLoc0"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>></td><td class="name" onclick="toggle('pointee0')"><a name="pointee0Anchor">pointee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointee0"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasAnyArgument1')"><a name="hasAnyArgument1Anchor">hasAnyArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyArgument1"><pre>Matches any argument of a call expression or a constructor call
+expression.
+
+Given
+ void x(int, int, int) { int y; x(1, y, 42); }
+callExpr(hasAnyArgument(declRefExpr()))
+ matches x(1, y, 42)
+with hasAnyArgument(...)
+ matching y
+
+FIXME: Currently this will ignore parentheses and implicit casts on
+the argument before applying the inner matcher. We'll want to remove
+this to allow for greater control by the user once ignoreImplicit()
+has been implemented.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasArgument1')"><a name="hasArgument1Anchor">hasArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasArgument1"><pre>Matches the n'th argument of a call expression or a constructor
+call expression.
+
+Example matches y in x(y)
+ (matcher = callExpr(hasArgument(0, declRefExpr())))
+ void x(int) { int y; x(y); }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasDeclaration12')"><a name="hasDeclaration12Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration12"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>></td><td class="name" onclick="toggle('forEachConstructorInitializer0')"><a name="forEachConstructorInitializer0Anchor">forEachConstructorInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="forEachConstructorInitializer0"><pre>Matches each constructor initializer in a constructor definition.
+
+Given
+ class A { A() : i(42), j(42) {} int i; int j; };
+constructorDecl(forEachConstructorInitializer(forField(decl().bind("x"))))
+ will trigger two matches, binding for 'i' and 'j' respectively.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>></td><td class="name" onclick="toggle('hasAnyConstructorInitializer0')"><a name="hasAnyConstructorInitializer0Anchor">hasAnyConstructorInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyConstructorInitializer0"><pre>Matches a constructor initializer.
+
+Given
+ struct Foo {
+ Foo() : foo_(1) { }
+ int foo_;
+ };
+recordDecl(has(constructorDecl(hasAnyConstructorInitializer(anything()))))
+ record matches Foo, hasAnyConstructorInitializer matches foo_(1)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('forField0')"><a name="forField0Anchor">forField</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FieldDecl.html">FieldDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="forField0"><pre>Matches the field declaration of a constructor initializer.
+
+Given
+ struct Foo {
+ Foo() : foo_(1) { }
+ int foo_;
+ };
+recordDecl(has(constructorDecl(hasAnyConstructorInitializer(
+ forField(hasName("foo_"))))))
+ matches Foo
+with forField matching foo_
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('withInitializer0')"><a name="withInitializer0Anchor">withInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="withInitializer0"><pre>Matches the initializer expression of a constructor initializer.
+
+Given
+ struct Foo {
+ Foo() : foo_(1) { }
+ int foo_;
+ };
+recordDecl(has(constructorDecl(hasAnyConstructorInitializer(
+ withInitializer(integerLiteral(equals(1)))))))
+ matches Foo
+with withInitializer matching (1)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasBody3')"><a name="hasBody3Anchor">hasBody</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBody3"><pre>Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+ for (;;) {}
+hasBody(compoundStmt())
+ matches 'for (;;) {}'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasLoopVariable0')"><a name="hasLoopVariable0Anchor">hasLoopVariable</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasLoopVariable0"><pre>Matches the initialization statement of a for loop.
+
+Example:
+ forStmt(hasLoopVariable(anything()))
+matches 'int x' in
+ for (int x : a) { }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasRangeInit0')"><a name="hasRangeInit0Anchor">hasRangeInit</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasRangeInit0"><pre>Matches the range initialization statement of a for loop.
+
+Example:
+ forStmt(hasRangeInit(anything()))
+matches 'a' in
+ for (int x : a) { }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('onImplicitObjectArgument0')"><a name="onImplicitObjectArgument0Anchor">onImplicitObjectArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="onImplicitObjectArgument0"><pre></pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('on0')"><a name="on0Anchor">on</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="on0"><pre>Matches on the implicit object argument of a member call expression.
+
+Example matches y.x() (matcher = callExpr(on(hasType(recordDecl(hasName("Y"))))))
+ class Y { public: void x(); };
+ void z() { Y y; y.x(); }",
+
+FIXME: Overload to allow directly matching types?
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType1')"><a name="thisPointerType1Anchor">thisPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="thisPointerType1"><pre>Overloaded to match the type's declaration.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType0')"><a name="thisPointerType0Anchor">thisPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="thisPointerType0"><pre>Matches if the expression's type either matches the specified
+matcher, or is a pointer to a type that matches the InnerMatcher.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('ofClass0')"><a name="ofClass0Anchor">ofClass</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="ofClass0"><pre>Matches the class declaration that the given method declaration
+belongs to.
+
+FIXME: Generalize this for other kinds of declarations.
+FIXME: What other kind of declarations would we need to generalize
+this to?
+
+Example matches A() in the last line
+ (matcher = constructExpr(hasDeclaration(methodDecl(
+ ofClass(hasName("A"))))))
+ class A {
+ public:
+ A();
+ };
+ A a = A();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasMethod0')"><a name="hasMethod0Anchor">hasMethod</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasMethod0"><pre>Matches the first method of a class or struct that satisfies InnerMatcher.
+
+Given:
+ class A { void func(); };
+ class B { void member(); };
+
+recordDecl(hasMethod(hasName("func"))) matches the declaration of A
+but not B.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isDerivedFrom0')"><a name="isDerivedFrom0Anchor">isDerivedFrom</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>> Base</td></tr>
+<tr><td colspan="4" class="doc" id="isDerivedFrom0"><pre>Matches C++ classes that are directly or indirectly derived from
+a class matching Base.
+
+Note that a class is not considered to be derived from itself.
+
+Example matches Y, Z, C (Base == hasName("X"))
+ class X;
+ class Y : public X {}; directly derived
+ class Z : public Y {}; indirectly derived
+ typedef X A;
+ typedef A B;
+ class C : public B {}; derived from a typedef of X
+
+In the following example, Bar matches isDerivedFrom(hasName("X")):
+ class Foo;
+ typedef Foo X;
+ class Bar : public Foo {}; derived from a type that X is a typedef of
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom0')"><a name="isSameOrDerivedFrom0Anchor">isSameOrDerivedFrom</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>> Base</td></tr>
+<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom0"><pre>Similar to isDerivedFrom(), but also matches classes that directly
+match Base.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('callee1')"><a name="callee1Anchor">callee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="callee1"><pre>Matches if the call expression's callee's declaration matches the
+given matcher.
+
+Example matches y.x() (matcher = callExpr(callee(methodDecl(hasName("x")))))
+ class Y { public: void x(); };
+ void z() { Y y; y.x();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('callee0')"><a name="callee0Anchor">callee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="callee0"><pre>Matches if the call expression's callee expression matches.
+
+Given
+ class Y { void x() { this->x(); x(); Y y; y.x(); } };
+ void f() { f(); }
+callExpr(callee(expr()))
+ matches this->x(), x(), y.x(), f()
+with callee(...)
+ matching this->x, x, y.x, f respectively
+
+Note: Callee cannot take the more general internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>
+because this introduces ambiguous overloads with calls to Callee taking a
+internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, as the matcher hierarchy is purely
+implemented in terms of implicit casts.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasAnyArgument0')"><a name="hasAnyArgument0Anchor">hasAnyArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyArgument0"><pre>Matches any argument of a call expression or a constructor call
+expression.
+
+Given
+ void x(int, int, int) { int y; x(1, y, 42); }
+callExpr(hasAnyArgument(declRefExpr()))
+ matches x(1, y, 42)
+with hasAnyArgument(...)
+ matching y
+
+FIXME: Currently this will ignore parentheses and implicit casts on
+the argument before applying the inner matcher. We'll want to remove
+this to allow for greater control by the user once ignoreImplicit()
+has been implemented.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasArgument0')"><a name="hasArgument0Anchor">hasArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasArgument0"><pre>Matches the n'th argument of a call expression or a constructor
+call expression.
+
+Example matches y in x(y)
+ (matcher = callExpr(hasArgument(0, declRefExpr())))
+ void x(int) { int y; x(y); }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasDeclaration13')"><a name="hasDeclaration13Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration13"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CaseStmt.html">CaseStmt</a>></td><td class="name" onclick="toggle('hasCaseConstant0')"><a name="hasCaseConstant0Anchor">hasCaseConstant</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCaseConstant0"><pre>If the given case statement does not use the GNU case range
+extension, matches the constant given in the statement.
+
+Given
+ switch (1) { case 1: case 1+1: case 3 ... 4: ; }
+caseStmt(hasCaseConstant(integerLiteral()))
+ matches "case 1:"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>></td><td class="name" onclick="toggle('hasSourceExpression0')"><a name="hasSourceExpression0Anchor">hasSourceExpression</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSourceExpression0"><pre>Matches if the cast's source expression matches the given matcher.
+
+Example: matches "a string" (matcher =
+ hasSourceExpression(constructExpr()))
+class URL { URL(string); };
+URL url = "a string";
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateSpecializationDecl.html">ClassTemplateSpecializationDecl</a>></td><td class="name" onclick="toggle('hasAnyTemplateArgument0')"><a name="hasAnyTemplateArgument0Anchor">hasAnyTemplateArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyTemplateArgument0"><pre>Matches classTemplateSpecializations that have at least one
+TemplateArgument matching the given InnerMatcher.
+
+Given
+ template<typename T> class A {};
+ template<> class A<double> {};
+ A<int> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+ refersToType(asString("int"))))
+ matches the specialization A<int>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateSpecializationDecl.html">ClassTemplateSpecializationDecl</a>></td><td class="name" onclick="toggle('hasTemplateArgument0')"><a name="hasTemplateArgument0Anchor">hasTemplateArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasTemplateArgument0"><pre>Matches classTemplateSpecializations where the n'th TemplateArgument
+matches the given InnerMatcher.
+
+Given
+ template<typename T, typename U> class A {};
+ A<bool, int> b;
+ A<int, bool> c;
+classTemplateSpecializationDecl(hasTemplateArgument(
+ 1, refersToType(asString("int"))))
+ matches the specialization A<bool, int>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexTypeLoc.html">ComplexTypeLoc</a>></td><td class="name" onclick="toggle('hasElementTypeLoc1')"><a name="hasElementTypeLoc1Anchor">hasElementTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasElementTypeLoc1"><pre>Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+ struct A {};
+ A a[7];
+ int b[7];
+arrayType(hasElementType(builtinType()))
+ matches "int b[7]"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>></td><td class="name" onclick="toggle('hasElementType1')"><a name="hasElementType1Anchor">hasElementType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="hasElementType1"><pre>Matches arrays and C99 complex types that have a specific element
+type.
+
+Given
+ struct A {};
+ A a[7];
+ int b[7];
+arrayType(hasElementType(builtinType()))
+ matches "int b[7]"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>></td><td class="name" onclick="toggle('hasAnySubstatement0')"><a name="hasAnySubstatement0Anchor">hasAnySubstatement</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnySubstatement0"><pre>Matches compound statements where at least one substatement matches
+a given matcher.
+
+Given
+ { {}; 1+2; }
+hasAnySubstatement(compoundStmt())
+ matches '{ {}; 1+2; }'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>></td><td class="name" onclick="toggle('hasCondition4')"><a name="hasCondition4Anchor">hasCondition</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCondition4"><pre>Matches the condition expression of an if statement, for loop,
+or conditional operator.
+
+Example matches true (matcher = hasCondition(boolLiteral(equals(true))))
+ if (true) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>></td><td class="name" onclick="toggle('hasFalseExpression0')"><a name="hasFalseExpression0Anchor">hasFalseExpression</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasFalseExpression0"><pre>Matches the false branch expression of a conditional operator.
+
+Example matches b
+ condition ? a : b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>></td><td class="name" onclick="toggle('hasTrueExpression0')"><a name="hasTrueExpression0Anchor">hasTrueExpression</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasTrueExpression0"><pre>Matches the true branch expression of a conditional operator.
+
+Example matches a
+ condition ? a : b
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('hasDeclaration11')"><a name="hasDeclaration11Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration11"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('throughUsingDecl0')"><a name="throughUsingDecl0Anchor">throughUsingDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingShadowDecl.html">UsingShadowDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="throughUsingDecl0"><pre>Matches a DeclRefExpr that refers to a declaration through a
+specific using shadow declaration.
+
+FIXME: This currently only works for functions. Fix.
+
+Given
+ namespace a { void f() {} }
+ using a::f;
+ void g() {
+ f(); Matches this ..
+ a::f(); .. but not this.
+ }
+declRefExpr(throughUsingDeclaration(anything()))
+ matches f()
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('to0')"><a name="to0Anchor">to</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="to0"><pre>Matches a DeclRefExpr that refers to a declaration that matches the
+specified matcher.
+
+Example matches x in if(x)
+ (matcher = declRefExpr(to(varDecl(hasName("x")))))
+ bool x;
+ if (x) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">DeclStmt</a>></td><td class="name" onclick="toggle('containsDeclaration0')"><a name="containsDeclaration0Anchor">containsDeclaration</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="containsDeclaration0"><pre>Matches the n'th declaration of a declaration statement.
+
+Note that this does not work for global declarations because the AST
+breaks up multiple-declaration DeclStmt's into multiple single-declaration
+DeclStmt's.
+Example: Given non-global declarations
+ int a, b = 0;
+ int c;
+ int d = 2, e;
+declStmt(containsDeclaration(
+ 0, varDecl(hasInitializer(anything()))))
+ matches only 'int d = 2, e;', and
+declStmt(containsDeclaration(1, varDecl()))
+ matches 'int a, b = 0' as well as 'int d = 2, e;'
+ but 'int c;' is not matched.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">DeclStmt</a>></td><td class="name" onclick="toggle('hasSingleDecl0')"><a name="hasSingleDecl0Anchor">hasSingleDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSingleDecl0"><pre>Matches the Decl of a DeclStmt which has a single declaration.
+
+Given
+ int a, b;
+ int c;
+declStmt(hasSingleDecl(anything()))
+ matches 'int c;' but not 'int a, b;'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclaratorDecl.html">DeclaratorDecl</a>></td><td class="name" onclick="toggle('hasTypeLoc0')"><a name="hasTypeLoc0Anchor">hasTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
+<tr><td colspan="4" class="doc" id="hasTypeLoc0"><pre>Matches if the type location of the declarator decl's type matches
+the inner matcher.
+
+Given
+ int x;
+declaratorDecl(hasTypeLoc(loc(asString("int"))))
+ matches int x
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('hasDeclContext0')"><a name="hasDeclContext0Anchor">hasDeclContext</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclContext0"><pre>Matches declarations whose declaration context, interpreted as a
+Decl, matches InnerMatcher.
+
+Given
+ namespace N {
+ namespace M {
+ class D {};
+ }
+ }
+
+recordDecl(hasDeclContext(namedDecl(hasName("M")))) matches the
+declaration of class D.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>></td><td class="name" onclick="toggle('hasBody0')"><a name="hasBody0Anchor">hasBody</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBody0"><pre>Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+ for (;;) {}
+hasBody(compoundStmt())
+ matches 'for (;;) {}'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>></td><td class="name" onclick="toggle('hasCondition3')"><a name="hasCondition3Anchor">hasCondition</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCondition3"><pre>Matches the condition expression of an if statement, for loop,
+or conditional operator.
+
+Example matches true (matcher = hasCondition(boolLiteral(equals(true))))
+ if (true) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ElaboratedType.html">ElaboratedType</a>></td><td class="name" onclick="toggle('hasQualifier0')"><a name="hasQualifier0Anchor">hasQualifier</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasQualifier0"><pre>Matches ElaboratedTypes whose qualifier, a NestedNameSpecifier,
+matches InnerMatcher if the qualifier exists.
+
+Given
+ namespace N {
+ namespace M {
+ class D {};
+ }
+ }
+ N::M::D d;
+
+elaboratedType(hasQualifier(hasPrefix(specifiesNamespace(hasName("N"))))
+matches the type of the variable declaration of d.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ElaboratedType.html">ElaboratedType</a>></td><td class="name" onclick="toggle('namesType0')"><a name="namesType0Anchor">namesType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="namesType0"><pre>Matches ElaboratedTypes whose named type matches InnerMatcher.
+
+Given
+ namespace N {
+ namespace M {
+ class D {};
+ }
+ }
+ N::M::D d;
+
+elaboratedType(namesType(recordType(
+hasDeclaration(namedDecl(hasName("D")))))) matches the type of the variable
+declaration of d.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>></td><td class="name" onclick="toggle('hasDeclaration10')"><a name="hasDeclaration10Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration10"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ExplicitCastExpr.html">ExplicitCastExpr</a>></td><td class="name" onclick="toggle('hasDestinationType0')"><a name="hasDestinationType0Anchor">hasDestinationType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDestinationType0"><pre>Matches casts whose destination type matches a given matcher.
+
+(Note: Clang's AST refers to other conversions as "casts" too, and calls
+actual casts "explicit" casts.)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('hasType2')"><a name="hasType2Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType2"><pre>Overloaded to match the declaration of the expression's or value
+declaration's type.
+
+In case of a value declaration (for example a variable declaration),
+this resolves one layer of indirection. For example, in the value
+declaration "X x;", recordDecl(hasName("X")) matches the declaration of X,
+while varDecl(hasType(recordDecl(hasName("X")))) matches the declaration
+of x."
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('hasType0')"><a name="hasType0Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType0"><pre>Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('ignoringImpCasts0')"><a name="ignoringImpCasts0Anchor">ignoringImpCasts</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="ignoringImpCasts0"><pre>Matches expressions that match InnerMatcher after any implicit casts
+are stripped off.
+
+Parentheses and explicit casts are not discarded.
+Given
+ int arr[5];
+ int a = 0;
+ char b = 0;
+ const int c = a;
+ int *d = arr;
+ long e = (long) 0l;
+The matchers
+ varDecl(hasInitializer(ignoringImpCasts(integerLiteral())))
+ varDecl(hasInitializer(ignoringImpCasts(declRefExpr())))
+would match the declarations for a, b, c, and d, but not e.
+While
+ varDecl(hasInitializer(integerLiteral()))
+ varDecl(hasInitializer(declRefExpr()))
+only match the declarations for b, c, and d.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('ignoringParenCasts0')"><a name="ignoringParenCasts0Anchor">ignoringParenCasts</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="ignoringParenCasts0"><pre>Matches expressions that match InnerMatcher after parentheses and
+casts are stripped off.
+
+Implicit and non-C Style casts are also discarded.
+Given
+ int a = 0;
+ char b = (0);
+ void* c = reinterpret_cast<char*>(0);
+ char d = char(0);
+The matcher
+ varDecl(hasInitializer(ignoringParenCasts(integerLiteral())))
+would match the declarations for a, b, c, and d.
+while
+ varDecl(hasInitializer(integerLiteral()))
+only match the declaration for a.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('ignoringParenImpCasts0')"><a name="ignoringParenImpCasts0Anchor">ignoringParenImpCasts</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="ignoringParenImpCasts0"><pre>Matches expressions that match InnerMatcher after implicit casts and
+parentheses are stripped off.
+
+Explicit casts are not discarded.
+Given
+ int arr[5];
+ int a = 0;
+ char b = (0);
+ const int c = a;
+ int *d = (arr);
+ long e = ((long) 0l);
+The matchers
+ varDecl(hasInitializer(ignoringParenImpCasts(integerLiteral())))
+ varDecl(hasInitializer(ignoringParenImpCasts(declRefExpr())))
+would match the declarations for a, b, c, and d, but not e.
+while
+ varDecl(hasInitializer(integerLiteral()))
+ varDecl(hasInitializer(declRefExpr()))
+would only match the declaration for a.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasBody1')"><a name="hasBody1Anchor">hasBody</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBody1"><pre>Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+ for (;;) {}
+hasBody(compoundStmt())
+ matches 'for (;;) {}'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasCondition1')"><a name="hasCondition1Anchor">hasCondition</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCondition1"><pre>Matches the condition expression of an if statement, for loop,
+or conditional operator.
+
+Example matches true (matcher = hasCondition(boolLiteral(equals(true))))
+ if (true) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasIncrement0')"><a name="hasIncrement0Anchor">hasIncrement</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasIncrement0"><pre>Matches the increment statement of a for loop.
+
+Example:
+ forStmt(hasIncrement(unaryOperator(hasOperatorName("++"))))
+matches '++x' in
+ for (x; x < N; ++x) { }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasLoopInit0')"><a name="hasLoopInit0Anchor">hasLoopInit</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasLoopInit0"><pre>Matches the initialization statement of a for loop.
+
+Example:
+ forStmt(hasLoopInit(declStmt()))
+matches 'int x = 0' in
+ for (int x = 0; x < N; ++x) { }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasAnyParameter0')"><a name="hasAnyParameter0Anchor">hasAnyParameter</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyParameter0"><pre>Matches any parameter of a function declaration.
+
+Does not match the 'this' parameter of a method.
+
+Given
+ class X { void f(int x, int y, int z) {} };
+methodDecl(hasAnyParameter(hasName("y")))
+ matches f(int x, int y, int z) {}
+with hasAnyParameter(...)
+ matching int y
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasParameter0')"><a name="hasParameter0Anchor">hasParameter</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasParameter0"><pre>Matches the n'th parameter of a function declaration.
+
+Given
+ class X { void f(int x) {} };
+methodDecl(hasParameter(0, hasType(varDecl())))
+ matches f(int x) {}
+with hasParameter(...)
+ matching int x
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('returns0')"><a name="returns0Anchor">returns</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="returns0"><pre>Matches the return type of a function declaration.
+
+Given:
+ class X { int f() { return 1; } };
+methodDecl(returns(asString("int")))
+ matches int f() { return 1; }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasCondition0')"><a name="hasCondition0Anchor">hasCondition</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCondition0"><pre>Matches the condition expression of an if statement, for loop,
+or conditional operator.
+
+Example matches true (matcher = hasCondition(boolLiteral(equals(true))))
+ if (true) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasConditionVariableStatement0')"><a name="hasConditionVariableStatement0Anchor">hasConditionVariableStatement</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">DeclStmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasConditionVariableStatement0"><pre>Matches the condition variable statement in an if statement.
+
+Given
+ if (A* a = GetAPointer()) {}
+hasConditionVariableStatement(...)
+ matches 'A* a = GetAPointer()'.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasElse0')"><a name="hasElse0Anchor">hasElse</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasElse0"><pre>Matches the else-statement of an if statement.
+
+Examples matches the if statement
+ (matcher = ifStmt(hasElse(boolLiteral(equals(true)))))
+ if (false) false; else true;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasThen0')"><a name="hasThen0Anchor">hasThen</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasThen0"><pre>Matches the then-statement of an if statement.
+
+Examples matches the if statement
+ (matcher = ifStmt(hasThen(boolLiteral(equals(true)))))
+ if (false) true; else false;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ImplicitCastExpr.html">ImplicitCastExpr</a>></td><td class="name" onclick="toggle('hasImplicitDestinationType0')"><a name="hasImplicitDestinationType0Anchor">hasImplicitDestinationType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasImplicitDestinationType0"><pre>Matches implicit casts whose destination type matches a given
+matcher.
+
+FIXME: Unit test this matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>></td><td class="name" onclick="toggle('hasDeclaration9')"><a name="hasDeclaration9Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration9"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>></td><td class="name" onclick="toggle('hasDeclaration8')"><a name="hasDeclaration8Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration8"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('hasDeclaration7')"><a name="hasDeclaration7Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration7"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('hasObjectExpression0')"><a name="hasObjectExpression0Anchor">hasObjectExpression</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasObjectExpression0"><pre>Matches a member expression where the object expression is
+matched by a given matcher.
+
+Given
+ struct X { int m; };
+ void f(X x) { x.m; m; }
+memberExpr(hasObjectExpression(hasType(recordDecl(hasName("X")))))))
+ matches "x.m" and "m"
+with hasObjectExpression(...)
+ matching "x" and the implicit object expression of "m" which has type X*.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('member0')"><a name="member0Anchor">member</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="member0"><pre>Matches a member expression where the member is matched by a
+given matcher.
+
+Given
+ struct { int first, second; } first, second;
+ int i(second.first);
+ int j(first.second);
+memberExpr(member(hasName("first")))
+ matches second.first
+ but not first.second (because the member name there is "second").
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerTypeLoc.html">MemberPointerTypeLoc</a>></td><td class="name" onclick="toggle('pointeeLoc1')"><a name="pointeeLoc1Anchor">pointeeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointeeLoc1"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>></td><td class="name" onclick="toggle('pointee1')"><a name="pointee1Anchor">pointee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointee1"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('hasPrefix1')"><a name="hasPrefix1Anchor">hasPrefix</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasPrefix1"><pre>Matches on the prefix of a NestedNameSpecifierLoc.
+
+Given
+ struct A { struct B { struct C {}; }; };
+ A::B::C c;
+nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString("struct A")))))
+ matches "A::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('specifiesTypeLoc0')"><a name="specifiesTypeLoc0Anchor">specifiesTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="specifiesTypeLoc0"><pre>Matches nested name specifier locs that specify a type matching the
+given TypeLoc.
+
+Given
+ struct A { struct B { struct C {}; }; };
+ A::B::C c;
+nestedNameSpecifierLoc(specifiesTypeLoc(loc(type(
+ hasDeclaration(recordDecl(hasName("A")))))))
+ matches "A::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>></td><td class="name" onclick="toggle('hasPrefix0')"><a name="hasPrefix0Anchor">hasPrefix</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasPrefix0"><pre>Matches on the prefix of a NestedNameSpecifier.
+
+Given
+ struct A { struct B { struct C {}; }; };
+ A::B::C c;
+nestedNameSpecifier(hasPrefix(specifiesType(asString("struct A")))) and
+ matches "A::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>></td><td class="name" onclick="toggle('specifiesNamespace0')"><a name="specifiesNamespace0Anchor">specifiesNamespace</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamespaceDecl.html">NamespaceDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="specifiesNamespace0"><pre>Matches nested name specifiers that specify a namespace matching the
+given namespace matcher.
+
+Given
+ namespace ns { struct A {}; }
+ ns::A a;
+nestedNameSpecifier(specifiesNamespace(hasName("ns")))
+ matches "ns::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>></td><td class="name" onclick="toggle('specifiesType0')"><a name="specifiesType0Anchor">specifiesType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="specifiesType0"><pre>Matches nested name specifiers that specify a type matching the
+given QualType matcher without qualifiers.
+
+Given
+ struct A { struct B { struct C {}; }; };
+ A::B::C c;
+nestedNameSpecifier(specifiesType(hasDeclaration(recordDecl(hasName("A")))))
+ matches "A::"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParenType.html">ParenType</a>></td><td class="name" onclick="toggle('innerType0')"><a name="innerType0Anchor">innerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="innerType0"><pre>Matches ParenType nodes where the inner type is a specific type.
+
+Given
+ int (*ptr_to_array)[4];
+ int (*ptr_to_func)(int);
+
+varDecl(hasType(pointsTo(parenType(innerType(functionType()))))) matches
+ptr_to_func but not ptr_to_array.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParenType.html">ParenType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerTypeLoc.html">PointerTypeLoc</a>></td><td class="name" onclick="toggle('pointeeLoc2')"><a name="pointeeLoc2Anchor">pointeeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointeeLoc2"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>></td><td class="name" onclick="toggle('pointee2')"><a name="pointee2Anchor">pointee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointee2"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasCanonicalType0')"><a name="hasCanonicalType0Anchor">hasCanonicalType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCanonicalType0"><pre>Matches QualTypes whose canonical type matches InnerMatcher.
+
+Given:
+ typedef int &int_ref;
+ int a;
+ int_ref b = a;
+
+varDecl(hasType(qualType(referenceType()))))) will not match the
+declaration of b but varDecl(hasType(qualType(hasCanonicalType(referenceType())))))) does.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasDeclaration6')"><a name="hasDeclaration6Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration6"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('pointsTo1')"><a name="pointsTo1Anchor">pointsTo</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="pointsTo1"><pre>Overloaded to match the pointee type's declaration.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('pointsTo0')"><a name="pointsTo0Anchor">pointsTo</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="pointsTo0"><pre>Matches if the matched type is a pointer type and the pointee type
+matches the specified matcher.
+
+Example matches y->x()
+ (matcher = callExpr(on(hasType(pointsTo(recordDecl(hasName("Y")))))))
+ class Y { public: void x(); };
+ void z() { Y *y; y->x(); }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('references1')"><a name="references1Anchor">references</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="references1"><pre>Overloaded to match the referenced type's declaration.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('references0')"><a name="references0Anchor">references</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="references0"><pre>Matches if the matched type is a reference type and the referenced
+type matches the specified matcher.
+
+Example matches X &x and const X &y
+ (matcher = varDecl(hasType(references(recordDecl(hasName("X"))))))
+ class X {
+ void a(X b) {
+ X &x = b;
+ const X &y = b;
+ };
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>></td><td class="name" onclick="toggle('hasDeclaration5')"><a name="hasDeclaration5Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration5"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceTypeLoc.html">ReferenceTypeLoc</a>></td><td class="name" onclick="toggle('pointeeLoc3')"><a name="pointeeLoc3Anchor">pointeeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointeeLoc3"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>></td><td class="name" onclick="toggle('pointee3')"><a name="pointee3Anchor">pointee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
+<tr><td colspan="4" class="doc" id="pointee3"><pre>Narrows PointerType (and similar) matchers to those where the
+pointee matches a given matcher.
+
+Given
+ int *a;
+ int const *b;
+ float const *f;
+pointerType(pointee(isConstQualified(), isInteger()))
+ matches "int const *b"
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('alignOfExpr0')"><a name="alignOfExpr0Anchor">alignOfExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="alignOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching
+alignof.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('sizeOfExpr0')"><a name="sizeOfExpr0Anchor">sizeOfExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="sizeOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching
+sizeof.
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchStmt.html">SwitchStmt</a>></td><td class="name" onclick="toggle('forEachSwitchCase0')"><a name="forEachSwitchCase0Anchor">forEachSwitchCase</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchCase.html">SwitchCase</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="forEachSwitchCase0"><pre>Matches each case or default statement belonging to the given switch
+statement. This matcher may produce multiple matches.
+
+Given
+ switch (1) { case 1: case 2: default: switch (2) { case 3: case 4: ; } }
+switchStmt(forEachSwitchCase(caseStmt().bind("c"))).bind("s")
+ matches four times, with "c" binding each of "case 1:", "case 2:",
+"case 3:" and "case 4:", and "s" respectively binding "switch (1)",
+"switch (1)", "switch (2)" and "switch (2)".
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>></td><td class="name" onclick="toggle('hasDeclaration4')"><a name="hasDeclaration4Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration4"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('isExpr0')"><a name="isExpr0Anchor">isExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="isExpr0"><pre>Matches a sugar TemplateArgument that refers to a certain expression.
+
+Given
+ template<typename T> struct A {};
+ struct B { B* next; };
+ A<&B::next> a;
+templateSpecializationType(hasAnyTemplateArgument(
+ isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
+ matches the specialization A<&B::next> with fieldDecl(...) matching
+ B::next
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('refersToDeclaration0')"><a name="refersToDeclaration0Anchor">refersToDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="refersToDeclaration0"><pre>Matches a canonical TemplateArgument that refers to a certain
+declaration.
+
+Given
+ template<typename T> struct A {};
+ struct B { B* next; };
+ A<&B::next> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+ refersToDeclaration(fieldDecl(hasName("next"))))
+ matches the specialization A<&B::next> with fieldDecl(...) matching
+ B::next
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('refersToType0')"><a name="refersToType0Anchor">refersToType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="refersToType0"><pre>Matches a TemplateArgument that refers to a certain type.
+
+Given
+ struct X {};
+ template<typename T> struct A {};
+ A<X> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+ refersToType(class(hasName("X")))))
+ matches the specialization A<X>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasAnyTemplateArgument1')"><a name="hasAnyTemplateArgument1Anchor">hasAnyTemplateArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyTemplateArgument1"><pre>Matches classTemplateSpecializations that have at least one
+TemplateArgument matching the given InnerMatcher.
+
+Given
+ template<typename T> class A {};
+ template<> class A<double> {};
+ A<int> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+ refersToType(asString("int"))))
+ matches the specialization A<int>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasDeclaration3')"><a name="hasDeclaration3Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration3"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasTemplateArgument1')"><a name="hasTemplateArgument1Anchor">hasTemplateArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasTemplateArgument1"><pre>Matches classTemplateSpecializations where the n'th TemplateArgument
+matches the given InnerMatcher.
+
+Given
+ template<typename T, typename U> class A {};
+ A<bool, int> b;
+ A<int, bool> c;
+classTemplateSpecializationDecl(hasTemplateArgument(
+ 1, refersToType(asString("int"))))
+ matches the specialization A<bool, int>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>></td><td class="name" onclick="toggle('hasDeclaration2')"><a name="hasDeclaration2Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration2"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<T></td><td class="name" onclick="toggle('findAll0')"><a name="findAll0Anchor">findAll</a></td><td>Matcher<T> Matcher</td></tr>
+<tr><td colspan="4" class="doc" id="findAll0"><pre>Matches if the node or any descendant matches.
+
+Generates results for each match.
+
+For example, in:
+ class A { class B {}; class C {}; };
+The matcher:
+ recordDecl(hasName("::A"), findAll(recordDecl(isDefinition()).bind("m")))
+will generate results for A, B and C.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>></td><td class="name" onclick="toggle('hasDeclaration1')"><a name="hasDeclaration1Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration1"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>></td><td class="name" onclick="toggle('hasArgumentOfType0')"><a name="hasArgumentOfType0Anchor">hasArgumentOfType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasArgumentOfType0"><pre>Matches unary expressions that have a specific type of argument.
+
+Given
+ int a, c; float b; int s = sizeof(a) + sizeof(b) + alignof(c);
+unaryExprOrTypeTraitExpr(hasArgumentOfType(asString("int"))
+ matches sizeof(a) and alignof(c)
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryOperator.html">UnaryOperator</a>></td><td class="name" onclick="toggle('hasUnaryOperand0')"><a name="hasUnaryOperand0Anchor">hasUnaryOperand</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasUnaryOperand0"><pre>Matches if the operand of a unary operator matches.
+
+Example matches true (matcher = hasUnaryOperand(boolLiteral(equals(true))))
+ !true
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>></td><td class="name" onclick="toggle('hasDeclaration0')"><a name="hasDeclaration0Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasDeclaration0"><pre>Matches a node if the declaration associated with that node
+matches the given matcher.
+
+The associated declaration is:
+- for type nodes, the declaration of the underlying type
+- for CallExpr, the declaration of the callee
+- for MemberExpr, the declaration of the referenced member
+- for CXXConstructExpr, the declaration of the constructor
+
+Also usable as Matcher<T> for any T supporting the getDecl() member
+function. e.g. various subtypes of clang::Type and various expressions.
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>,
+ Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingDecl.html">UsingDecl</a>></td><td class="name" onclick="toggle('hasAnyUsingShadowDecl0')"><a name="hasAnyUsingShadowDecl0Anchor">hasAnyUsingShadowDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingShadowDecl.html">UsingShadowDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyUsingShadowDecl0"><pre>Matches any using shadow declaration.
+
+Given
+ namespace X { void b(); }
+ using X::b;
+usingDecl(hasAnyUsingShadowDecl(hasName("b"))))
+ matches using X::b </pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingShadowDecl.html">UsingShadowDecl</a>></td><td class="name" onclick="toggle('hasTargetDecl0')"><a name="hasTargetDecl0Anchor">hasTargetDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasTargetDecl0"><pre>Matches a using shadow declaration where the target declaration is
+matched by the given matcher.
+
+Given
+ namespace X { int a; void b(); }
+ using X::a;
+ using X::b;
+usingDecl(hasAnyUsingShadowDecl(hasTargetDecl(functionDecl())))
+ matches using X::b but not using X::a </pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>></td><td class="name" onclick="toggle('hasType3')"><a name="hasType3Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType3"><pre>Overloaded to match the declaration of the expression's or value
+declaration's type.
+
+In case of a value declaration (for example a variable declaration),
+this resolves one layer of indirection. For example, in the value
+declaration "X x;", recordDecl(hasName("X")) matches the declaration of X,
+while varDecl(hasType(recordDecl(hasName("X")))) matches the declaration
+of x."
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+
+Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>></td><td class="name" onclick="toggle('hasType1')"><a name="hasType1Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType1"><pre>Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasInitializer0')"><a name="hasInitializer0Anchor">hasInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasInitializer0"><pre>Matches a variable declaration that has an initializer expression
+that matches the given matcher.
+
+Example matches x (matcher = varDecl(hasInitializer(callExpr())))
+ bool y() { return true; }
+ bool x = y();
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VariableArrayType.html">VariableArrayType</a>></td><td class="name" onclick="toggle('hasSizeExpr0')"><a name="hasSizeExpr0Anchor">hasSizeExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSizeExpr0"><pre>Matches VariableArrayType nodes that have a specific size
+expression.
+
+Given
+ void f(int b) {
+ int a[b];
+ }
+variableArrayType(hasSizeExpr(ignoringImpCasts(declRefExpr(to(
+ varDecl(hasName("b")))))))
+ matches "int a[b]"
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1WhileStmt.html">WhileStmt</a>></td><td class="name" onclick="toggle('hasBody2')"><a name="hasBody2Anchor">hasBody</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBody2"><pre>Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+ for (;;) {}
+hasBody(compoundStmt())
+ matches 'for (;;) {}'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1WhileStmt.html">WhileStmt</a>></td><td class="name" onclick="toggle('hasCondition2')"><a name="hasCondition2Anchor">hasCondition</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasCondition2"><pre>Matches the condition expression of an if statement, for loop,
+or conditional operator.
+
+Example matches true (matcher = hasCondition(boolLiteral(equals(true))))
+ if (true) {}
+</pre></td></tr>
+
+
+<tr><td>Matcher<internal::BindableMatcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>>></td><td class="name" onclick="toggle('loc1')"><a name="loc1Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="loc1"><pre>Matches NestedNameSpecifierLocs for which the given inner
+NestedNameSpecifier-matcher matches.
+</pre></td></tr>
+
+
+<tr><td>Matcher<internal::BindableMatcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>></td><td class="name" onclick="toggle('loc0')"><a name="loc0Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="loc0"><pre>Matches TypeLocs for which the given inner
+QualType-matcher matches.
+</pre></td></tr>
+
+<!--END_TRAVERSAL_MATCHERS -->
+</table>
+
+</div>
+</body>
+</html>
+
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersTutorial.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersTutorial.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersTutorial.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/LibASTMatchersTutorial.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,560 @@
+===============================================================
+Tutorial for building tools using LibTooling and LibASTMatchers
+===============================================================
+
+This document is intended to show how to build a useful source-to-source
+translation tool based on Clang's `LibTooling <LibTooling.html>`_. It is
+explicitly aimed at people who are new to Clang, so all you should need
+is a working knowledge of C++ and the command line.
+
+In order to work on the compiler, you need some basic knowledge of the
+abstract syntax tree (AST). To this end, the reader is incouraged to
+skim the :doc:`Introduction to the Clang
+AST <IntroductionToTheClangAST>`
+
+Step 0: Obtaining Clang
+=======================
+
+As Clang is part of the LLVM project, you'll need to download LLVM's
+source code first. Both Clang and LLVM are maintained as Subversion
+repositories, but we'll be accessing them through the git mirror. For
+further information, see the `getting started
+guide <http://llvm.org/docs/GettingStarted.html>`_.
+
+.. code-block:: console
+
+ mkdir ~/clang-llvm && cd ~/clang-llvm
+ git clone http://llvm.org/git/llvm.git
+ cd llvm/tools
+ git clone http://llvm.org/git/clang.git
+ cd clang/tools
+ git clone http://llvm.org/git/clang-tools-extra.git extra
+
+Next you need to obtain the CMake build system and Ninja build tool. You
+may already have CMake installed, but current binary versions of CMake
+aren't built with Ninja support.
+
+.. code-block:: console
+
+ cd ~/clang-llvm
+ git clone https://github.com/martine/ninja.git
+ cd ninja
+ git checkout release
+ ./bootstrap.py
+ sudo cp ninja /usr/bin/
+
+ cd ~/clang-llvm
+ git clone git://cmake.org/stage/cmake.git
+ cd cmake
+ git checkout next
+ ./bootstrap
+ make
+ sudo make install
+
+Okay. Now we'll build Clang!
+
+.. code-block:: console
+
+ cd ~/clang-llvm
+ mkdir build && cd build
+ cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON # Enable tests; default is off.
+ ninja
+ ninja check # Test LLVM only.
+ ninja clang-test # Test Clang only.
+ ninja install
+
+And we're live.
+
+All of the tests should pass, though there is a (very) small chance that
+you can catch LLVM and Clang out of sync. Running ``'git svn rebase'``
+in both the llvm and clang directories should fix any problems.
+
+Finally, we want to set Clang as its own compiler.
+
+.. code-block:: console
+
+ cd ~/clang-llvm/build
+ ccmake ../llvm
+
+The second command will bring up a GUI for configuring Clang. You need
+to set the entry for ``CMAKE_CXX_COMPILER``. Press ``'t'`` to turn on
+advanced mode. Scroll down to ``CMAKE_CXX_COMPILER``, and set it to
+``/usr/bin/clang++``, or wherever you installed it. Press ``'c'`` to
+configure, then ``'g'`` to generate CMake's files.
+
+Finally, run ninja one last time, and you're done.
+
+Step 1: Create a ClangTool
+==========================
+
+Now that we have enough background knowledge, it's time to create the
+simplest productive ClangTool in existence: a syntax checker. While this
+already exists as ``clang-check``, it's important to understand what's
+going on.
+
+First, we'll need to create a new directory for our tool and tell CMake
+that it exists. As this is not going to be a core clang tool, it will
+live in the ``tools/extra`` repository.
+
+.. code-block:: console
+
+ cd ~/clang-llvm/llvm/tools/clang
+ mkdir tools/extra/loop-convert
+ echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt
+ vim tools/extra/loop-convert/CMakeLists.txt
+
+CMakeLists.txt should have the following contents:
+
+::
+
+ set(LLVM_LINK_COMPONENTS support)
+ set(LLVM_USED_LIBS clangTooling clangBasic clangAST)
+
+ add_clang_executable(loop-convert
+ LoopConvert.cpp
+ )
+ target_link_libraries(loop-convert
+ clangTooling
+ clangBasic
+ clangASTMatchers
+ )
+
+With that done, Ninja will be able to compile our tool. Let's give it
+something to compile! Put the following into
+``tools/extra/loop-convert/LoopConvert.cpp``. A detailed explanation of
+why the different parts are needed can be found in the `LibTooling
+documentation <LibTooling.html>`_.
+
+.. code-block:: c++
+
+ // Declares clang::SyntaxOnlyAction.
+ #include "clang/Frontend/FrontendActions.h"
+ #include "clang/Tooling/CommonOptionsParser.h"
+ #include "clang/Tooling/Tooling.h"
+ // Declares llvm::cl::extrahelp.
+ #include "llvm/Support/CommandLine.h"
+
+ using namespace clang::tooling;
+ using namespace llvm;
+
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
+ // CommonOptionsParser declares HelpMessage with a description of the common
+ // command-line options related to the compilation database and input files.
+ // It's nice to have this help message in all tools.
+ static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
+
+ // A help message for this specific tool can be added afterwards.
+ static cl::extrahelp MoreHelp("\nMore help text...");
+
+ int main(int argc, const char **argv) {
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
+ ClangTool Tool(OptionsParser.getCompilations(),
+ OptionsParser.getSourcePathList());
+ return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
+ }
+
+And that's it! You can compile our new tool by running ninja from the
+``build`` directory.
+
+.. code-block:: console
+
+ cd ~/clang-llvm/build
+ ninja
+
+You should now be able to run the syntax checker, which is located in
+``~/clang-llvm/build/bin``, on any source file. Try it!
+
+.. code-block:: console
+
+ cat "int main() { return 0; }" > test.cpp
+ bin/loop-convert test.cpp --
+
+Note the two dashes after we specify the source file. The additional
+options for the compiler are passed after the dashes rather than loading
+them from a compilation database - there just aren't any options needed
+right now.
+
+Intermezzo: Learn AST matcher basics
+====================================
+
+Clang recently introduced the :doc:`ASTMatcher
+library <LibASTMatchers>` to provide a simple, powerful, and
+concise way to describe specific patterns in the AST. Implemented as a
+DSL powered by macros and templates (see
+`ASTMatchers.h <../doxygen/ASTMatchers_8h_source.html>`_ if you're
+curious), matchers offer the feel of algebraic data types common to
+functional programming languages.
+
+For example, suppose you wanted to examine only binary operators. There
+is a matcher to do exactly that, conveniently named ``binaryOperator``.
+I'll give you one guess what this matcher does:
+
+.. code-block:: c++
+
+ binaryOperator(hasOperatorName("+"), hasLHS(integerLiteral(equals(0))))
+
+Shockingly, it will match against addition expressions whose left hand
+side is exactly the literal 0. It will not match against other forms of
+0, such as ``'\0'`` or ``NULL``, but it will match against macros that
+expand to 0. The matcher will also not match against calls to the
+overloaded operator ``'+'``, as there is a separate ``operatorCallExpr``
+matcher to handle overloaded operators.
+
+There are AST matchers to match all the different nodes of the AST,
+narrowing matchers to only match AST nodes fulfilling specific criteria,
+and traversal matchers to get from one kind of AST node to another. For
+a complete list of AST matchers, take a look at the `AST Matcher
+References <LibASTMatchersReference.html>`_
+
+All matcher that are nouns describe entities in the AST and can be
+bound, so that they can be referred to whenever a match is found. To do
+so, simply call the method ``bind`` on these matchers, e.g.:
+
+.. code-block:: c++
+
+ variable(hasType(isInteger())).bind("intvar")
+
+Step 2: Using AST matchers
+==========================
+
+Okay, on to using matchers for real. Let's start by defining a matcher
+which will capture all ``for`` statements that define a new variable
+initialized to zero. Let's start with matching all ``for`` loops:
+
+.. code-block:: c++
+
+ forStmt()
+
+Next, we want to specify that a single variable is declared in the first
+portion of the loop, so we can extend the matcher to
+
+.. code-block:: c++
+
+ forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl()))))
+
+Finally, we can add the condition that the variable is initialized to
+zero.
+
+.. code-block:: c++
+
+ forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl(
+ hasInitializer(integerLiteral(equals(0))))))))
+
+It is fairly easy to read and understand the matcher definition ("match
+loops whose init portion declares a single variable which is initialized
+to the integer literal 0"), but deciding that every piece is necessary
+is more difficult. Note that this matcher will not match loops whose
+variables are initialized to ``'\0'``, ``0.0``, ``NULL``, or any form of
+zero besides the integer 0.
+
+The last step is giving the matcher a name and binding the ``ForStmt``
+as we will want to do something with it:
+
+.. code-block:: c++
+
+ StatementMatcher LoopMatcher =
+ forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl(
+ hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop");
+
+Once you have defined your matchers, you will need to add a little more
+scaffolding in order to run them. Matchers are paired with a
+``MatchCallback`` and registered with a ``MatchFinder`` object, then run
+from a ``ClangTool``. More code!
+
+Add the following to ``LoopConvert.cpp``:
+
+.. code-block:: c++
+
+ #include "clang/ASTMatchers/ASTMatchers.h"
+ #include "clang/ASTMatchers/ASTMatchFinder.h"
+
+ using namespace clang;
+ using namespace clang::ast_matchers;
+
+ StatementMatcher LoopMatcher =
+ forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl(
+ hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop");
+
+ class LoopPrinter : public MatchFinder::MatchCallback {
+ public :
+ virtual void run(const MatchFinder::MatchResult &Result) {
+ if (const ForStmt *FS = Result.Nodes.getNodeAs<clang::ForStmt>("forLoop"))
+ FS->dump();
+ }
+ };
+
+And change ``main()`` to:
+
+.. code-block:: c++
+
+ int main(int argc, const char **argv) {
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
+ ClangTool Tool(OptionsParser.getCompilations(),
+ OptionsParser.getSourcePathList());
+
+ LoopPrinter Printer;
+ MatchFinder Finder;
+ Finder.addMatcher(LoopMatcher, &Printer);
+
+ return Tool.run(newFrontendActionFactory(&Finder).get());
+ }
+
+Now, you should be able to recompile and run the code to discover for
+loops. Create a new file with a few examples, and test out our new
+handiwork:
+
+.. code-block:: console
+
+ cd ~/clang-llvm/llvm/llvm_build/
+ ninja loop-convert
+ vim ~/test-files/simple-loops.cc
+ bin/loop-convert ~/test-files/simple-loops.cc
+
+Step 3.5: More Complicated Matchers
+===================================
+
+Our simple matcher is capable of discovering for loops, but we would
+still need to filter out many more ourselves. We can do a good portion
+of the remaining work with some cleverly chosen matchers, but first we
+need to decide exactly which properties we want to allow.
+
+How can we characterize for loops over arrays which would be eligible
+for translation to range-based syntax? Range based loops over arrays of
+size ``N`` that:
+
+- start at index ``0``
+- iterate consecutively
+- end at index ``N-1``
+
+We already check for (1), so all we need to add is a check to the loop's
+condition to ensure that the loop's index variable is compared against
+``N`` and another check to ensure that the increment step just
+increments this same variable. The matcher for (2) is straightforward:
+require a pre- or post-increment of the same variable declared in the
+init portion.
+
+Unfortunately, such a matcher is impossible to write. Matchers contain
+no logic for comparing two arbitrary AST nodes and determining whether
+or not they are equal, so the best we can do is matching more than we
+would like to allow, and punting extra comparisons to the callback.
+
+In any case, we can start building this sub-matcher. We can require that
+the increment step be a unary increment like this:
+
+.. code-block:: c++
+
+ hasIncrement(unaryOperator(hasOperatorName("++")))
+
+Specifying what is incremented introduces another quirk of Clang's AST:
+Usages of variables are represented as ``DeclRefExpr``'s ("declaration
+reference expressions") because they are expressions which refer to
+variable declarations. To find a ``unaryOperator`` that refers to a
+specific declaration, we can simply add a second condition to it:
+
+.. code-block:: c++
+
+ hasIncrement(unaryOperator(
+ hasOperatorName("++"),
+ hasUnaryOperand(declRefExpr())))
+
+Furthermore, we can restrict our matcher to only match if the
+incremented variable is an integer:
+
+.. code-block:: c++
+
+ hasIncrement(unaryOperator(
+ hasOperatorName("++"),
+ hasUnaryOperand(declRefExpr(to(varDecl(hasType(isInteger())))))))
+
+And the last step will be to attach an identifier to this variable, so
+that we can retrieve it in the callback:
+
+.. code-block:: c++
+
+ hasIncrement(unaryOperator(
+ hasOperatorName("++"),
+ hasUnaryOperand(declRefExpr(to(
+ varDecl(hasType(isInteger())).bind("incrementVariable"))))))
+
+We can add this code to the definition of ``LoopMatcher`` and make sure
+that our program, outfitted with the new matcher, only prints out loops
+that declare a single variable initialized to zero and have an increment
+step consisting of a unary increment of some variable.
+
+Now, we just need to add a matcher to check if the condition part of the
+``for`` loop compares a variable against the size of the array. There is
+only one problem - we don't know which array we're iterating over
+without looking at the body of the loop! We are again restricted to
+approximating the result we want with matchers, filling in the details
+in the callback. So we start with:
+
+.. code-block:: c++
+
+ hasCondition(binaryOperator(hasOperatorName("<"))
+
+It makes sense to ensure that the left-hand side is a reference to a
+variable, and that the right-hand side has integer type.
+
+.. code-block:: c++
+
+ hasCondition(binaryOperator(
+ hasOperatorName("<"),
+ hasLHS(declRefExpr(to(varDecl(hasType(isInteger()))))),
+ hasRHS(expr(hasType(isInteger())))))
+
+Why? Because it doesn't work. Of the three loops provided in
+``test-files/simple.cpp``, zero of them have a matching condition. A
+quick look at the AST dump of the first for loop, produced by the
+previous iteration of loop-convert, shows us the answer:
+
+::
+
+ (ForStmt 0x173b240
+ (DeclStmt 0x173afc8
+ 0x173af50 "int i =
+ (IntegerLiteral 0x173afa8 'int' 0)")
+ <<>>
+ (BinaryOperator 0x173b060 '_Bool' '<'
+ (ImplicitCastExpr 0x173b030 'int'
+ (DeclRefExpr 0x173afe0 'int' lvalue Var 0x173af50 'i' 'int'))
+ (ImplicitCastExpr 0x173b048 'int'
+ (DeclRefExpr 0x173b008 'const int' lvalue Var 0x170fa80 'N' 'const int')))
+ (UnaryOperator 0x173b0b0 'int' lvalue prefix '++'
+ (DeclRefExpr 0x173b088 'int' lvalue Var 0x173af50 'i' 'int'))
+ (CompoundStatement ...
+
+We already know that the declaration and increments both match, or this
+loop wouldn't have been dumped. The culprit lies in the implicit cast
+applied to the first operand (i.e. the LHS) of the less-than operator,
+an L-value to R-value conversion applied to the expression referencing
+``i``. Thankfully, the matcher library offers a solution to this problem
+in the form of ``ignoringParenImpCasts``, which instructs the matcher to
+ignore implicit casts and parentheses before continuing to match.
+Adjusting the condition operator will restore the desired match.
+
+.. code-block:: c++
+
+ hasCondition(binaryOperator(
+ hasOperatorName("<"),
+ hasLHS(ignoringParenImpCasts(declRefExpr(
+ to(varDecl(hasType(isInteger())))))),
+ hasRHS(expr(hasType(isInteger())))))
+
+After adding binds to the expressions we wished to capture and
+extracting the identifier strings into variables, we have array-step-2
+completed.
+
+Step 4: Retrieving Matched Nodes
+================================
+
+So far, the matcher callback isn't very interesting: it just dumps the
+loop's AST. At some point, we will need to make changes to the input
+source code. Next, we'll work on using the nodes we bound in the
+previous step.
+
+The ``MatchFinder::run()`` callback takes a
+``MatchFinder::MatchResult&`` as its parameter. We're most interested in
+its ``Context`` and ``Nodes`` members. Clang uses the ``ASTContext``
+class to represent contextual information about the AST, as the name
+implies, though the most functionally important detail is that several
+operations require an ``ASTContext*`` parameter. More immediately useful
+is the set of matched nodes, and how we retrieve them.
+
+Since we bind three variables (identified by ConditionVarName,
+InitVarName, and IncrementVarName), we can obtain the matched nodes by
+using the ``getNodeAs()`` member function.
+
+In ``LoopConvert.cpp`` add
+
+.. code-block:: c++
+
+ #include "clang/AST/ASTContext.h"
+
+Change ``LoopMatcher`` to
+
+.. code-block:: c++
+
+ StatementMatcher LoopMatcher =
+ forStmt(hasLoopInit(declStmt(
+ hasSingleDecl(varDecl(hasInitializer(integerLiteral(equals(0))))
+ .bind("initVarName")))),
+ hasIncrement(unaryOperator(
+ hasOperatorName("++"),
+ hasUnaryOperand(declRefExpr(
+ to(varDecl(hasType(isInteger())).bind("incVarName")))))),
+ hasCondition(binaryOperator(
+ hasOperatorName("<"),
+ hasLHS(ignoringParenImpCasts(declRefExpr(
+ to(varDecl(hasType(isInteger())).bind("condVarName"))))),
+ hasRHS(expr(hasType(isInteger())))))).bind("forLoop");
+
+And change ``LoopPrinter::run`` to
+
+.. code-block:: c++
+
+ void LoopPrinter::run(const MatchFinder::MatchResult &Result) {
+ ASTContext *Context = Result.Context;
+ const ForStmt *FS = Result.Nodes.getStmtAs<ForStmt>("forLoop");
+ // We do not want to convert header files!
+ if (!FS || !Context->getSourceManager().isFromMainFile(FS->getForLoc()))
+ return;
+ const VarDecl *IncVar = Result.Nodes.getNodeAs<VarDecl>("incVarName");
+ const VarDecl *CondVar = Result.Nodes.getNodeAs<VarDecl>("condVarName");
+ const VarDecl *InitVar = Result.Nodes.getNodeAs<VarDecl>("initVarName");
+
+ if (!areSameVariable(IncVar, CondVar) || !areSameVariable(IncVar, InitVar))
+ return;
+ llvm::outs() << "Potential array-based loop discovered.\n";
+ }
+
+Clang associates a ``VarDecl`` with each variable to represent the variable's
+declaration. Since the "canonical" form of each declaration is unique by
+address, all we need to do is make sure neither ``ValueDecl`` (base class of
+``VarDecl``) is ``NULL`` and compare the canonical Decls.
+
+.. code-block:: c++
+
+ static bool areSameVariable(const ValueDecl *First, const ValueDecl *Second) {
+ return First && Second &&
+ First->getCanonicalDecl() == Second->getCanonicalDecl();
+ }
+
+If execution reaches the end of ``LoopPrinter::run()``, we know that the
+loop shell that looks like
+
+.. code-block:: c++
+
+ for (int i= 0; i < expr(); ++i) { ... }
+
+For now, we will just print a message explaining that we found a loop.
+The next section will deal with recursively traversing the AST to
+discover all changes needed.
+
+As a side note, it's not as trivial to test if two expressions are the same,
+though Clang has already done the hard work for us by providing a way to
+canonicalize expressions:
+
+.. code-block:: c++
+
+ static bool areSameExpr(ASTContext *Context, const Expr *First,
+ const Expr *Second) {
+ if (!First || !Second)
+ return false;
+ llvm::FoldingSetNodeID FirstID, SecondID;
+ First->Profile(FirstID, *Context, true);
+ Second->Profile(SecondID, *Context, true);
+ return FirstID == SecondID;
+ }
+
+This code relies on the comparison between two
+``llvm::FoldingSetNodeIDs``. As the documentation for
+``Stmt::Profile()`` indicates, the ``Profile()`` member function builds
+a description of a node in the AST, based on its properties, along with
+those of its children. ``FoldingSetNodeID`` then serves as a hash we can
+use to compare expressions. We will need ``areSameExpr`` later. Before
+you run the new code on the additional loops added to
+test-files/simple.cpp, try to figure out which ones will be considered
+potentially convertible.
Added: www-releases/trunk/3.5.1/tools/clang/docs/LibFormat.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/LibFormat.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/LibFormat.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/LibFormat.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,56 @@
+=========
+LibFormat
+=========
+
+LibFormat is a library that implements automatic source code formatting based
+on Clang. This documents describes the LibFormat interface and design as well
+as some basic style discussions.
+
+If you just want to use `clang-format` as a tool or integrated into an editor,
+checkout :doc:`ClangFormat`.
+
+Design
+------
+
+FIXME: Write up design.
+
+
+Interface
+---------
+
+The core routine of LibFormat is ``reformat()``:
+
+.. code-block:: c++
+
+ tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex,
+ SourceManager &SourceMgr,
+ std::vector<CharSourceRange> Ranges);
+
+This reads a token stream out of the lexer ``Lex`` and reformats all the code
+ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during
+formatting. A list of options can be found under :ref:`style-options`.
+
+
+.. _style-options:
+
+Style Options
+-------------
+
+The style options describe specific formatting options that can be used in
+order to make `ClangFormat` comply with different style guides. Currently,
+two style guides are hard-coded:
+
+.. code-block:: c++
+
+ /// \brief Returns a format style complying with the LLVM coding standards:
+ /// http://llvm.org/docs/CodingStandards.html.
+ FormatStyle getLLVMStyle();
+
+ /// \brief Returns a format style complying with Google's C++ style guide:
+ /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
+ FormatStyle getGoogleStyle();
+
+These options are also exposed in the :doc:`standalone tools <ClangFormat>`
+through the `-style` option.
+
+In the future, we plan on making this configurable.
Added: www-releases/trunk/3.5.1/tools/clang/docs/LibTooling.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/LibTooling.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/LibTooling.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/LibTooling.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,201 @@
+==========
+LibTooling
+==========
+
+LibTooling is a library to support writing standalone tools based on Clang.
+This document will provide a basic walkthrough of how to write a tool using
+LibTooling.
+
+For the information on how to setup Clang Tooling for LLVM see
+:doc:`HowToSetupToolingForLLVM`
+
+Introduction
+------------
+
+Tools built with LibTooling, like Clang Plugins, run ``FrontendActions`` over
+code.
+
+.. See FIXME for a tutorial on how to write FrontendActions.
+
+In this tutorial, we'll demonstrate the different ways of running Clang's
+``SyntaxOnlyAction``, which runs a quick syntax check, over a bunch of code.
+
+Parsing a code snippet in memory
+--------------------------------
+
+If you ever wanted to run a ``FrontendAction`` over some sample code, for
+example to unit test parts of the Clang AST, ``runToolOnCode`` is what you
+looked for. Let me give you an example:
+
+.. code-block:: c++
+
+ #include "clang/Tooling/Tooling.h"
+
+ TEST(runToolOnCode, CanSyntaxCheckCode) {
+ // runToolOnCode returns whether the action was correctly run over the
+ // given code.
+ EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
+ }
+
+Writing a standalone tool
+-------------------------
+
+Once you unit tested your ``FrontendAction`` to the point where it cannot
+possibly break, it's time to create a standalone tool. For a standalone tool
+to run clang, it first needs to figure out what command line arguments to use
+for a specified file. To that end we create a ``CompilationDatabase``. There
+are different ways to create a compilation database, and we need to support all
+of them depending on command-line options. There's the ``CommonOptionsParser``
+class that takes the responsibility to parse command-line parameters related to
+compilation databases and inputs, so that all tools share the implementation.
+
+Parsing common tools options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``CompilationDatabase`` can be read from a build directory or the command line.
+Using ``CommonOptionsParser`` allows for explicit specification of a compile
+command line, specification of build path using the ``-p`` command-line option,
+and automatic location of the compilation database using source files paths.
+
+.. code-block:: c++
+
+ #include "clang/Tooling/CommonOptionsParser.h"
+ #include "llvm/Support/CommandLine.h"
+
+ using namespace clang::tooling;
+
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
+ int main(int argc, const char **argv) {
+ // CommonOptionsParser constructor will parse arguments and create a
+ // CompilationDatabase. In case of error it will terminate the program.
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
+
+ // Use OptionsParser.getCompilations() and OptionsParser.getSourcePathList()
+ // to retrieve CompilationDatabase and the list of input file paths.
+ }
+
+Creating and running a ClangTool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once we have a ``CompilationDatabase``, we can create a ``ClangTool`` and run
+our ``FrontendAction`` over some code. For example, to run the
+``SyntaxOnlyAction`` over the files "a.cc" and "b.cc" one would write:
+
+.. code-block:: c++
+
+ // A clang tool can run over a number of sources in the same process...
+ std::vector<std::string> Sources;
+ Sources.push_back("a.cc");
+ Sources.push_back("b.cc");
+
+ // We hand the CompilationDatabase we created and the sources to run over into
+ // the tool constructor.
+ ClangTool Tool(OptionsParser.getCompilations(), Sources);
+
+ // The ClangTool needs a new FrontendAction for each translation unit we run
+ // on. Thus, it takes a FrontendActionFactory as parameter. To create a
+ // FrontendActionFactory from a given FrontendAction type, we call
+ // newFrontendActionFactory<clang::SyntaxOnlyAction>().
+ int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
+
+Putting it together --- the first tool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now we combine the two previous steps into our first real tool. A more advanced
+version of this example tool is also checked into the clang tree at
+``tools/clang-check/ClangCheck.cpp``.
+
+.. code-block:: c++
+
+ // Declares clang::SyntaxOnlyAction.
+ #include "clang/Frontend/FrontendActions.h"
+ #include "clang/Tooling/CommonOptionsParser.h"
+ #include "clang/Tooling/Tooling.h"
+ // Declares llvm::cl::extrahelp.
+ #include "llvm/Support/CommandLine.h"
+
+ using namespace clang::tooling;
+ using namespace llvm;
+
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static cl::OptionCategory MyToolCategory("my-tool options");
+
+ // CommonOptionsParser declares HelpMessage with a description of the common
+ // command-line options related to the compilation database and input files.
+ // It's nice to have this help message in all tools.
+ static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
+
+ // A help message for this specific tool can be added afterwards.
+ static cl::extrahelp MoreHelp("\nMore help text...");
+
+ int main(int argc, const char **argv) {
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
+ ClangTool Tool(OptionsParser.getCompilations(),
+ OptionsParser.getSourcePathList());
+ return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
+ }
+
+Running the tool on some code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you check out and build clang, clang-check is already built and available
+to you in bin/clang-check inside your build directory.
+
+You can run clang-check on a file in the llvm repository by specifying all the
+needed parameters after a "``--``" separator:
+
+.. code-block:: bash
+
+ $ cd /path/to/source/llvm
+ $ export BD=/path/to/build/llvm
+ $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
+ clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
+ -Itools/clang/include -I$BD/include -Iinclude \
+ -Itools/clang/lib/Headers -c
+
+As an alternative, you can also configure cmake to output a compile command
+database into its build directory:
+
+.. code-block:: bash
+
+ # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
+ # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
+ $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
+
+This creates a file called ``compile_commands.json`` in the build directory.
+Now you can run :program:`clang-check` over files in the project by specifying
+the build path as first argument and some source files as further positional
+arguments:
+
+.. code-block:: bash
+
+ $ cd /path/to/source/llvm
+ $ export BD=/path/to/build/llvm
+ $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
+
+
+.. _libtooling_builtin_includes:
+
+Builtin includes
+^^^^^^^^^^^^^^^^
+
+Clang tools need their builtin headers and search for them the same way Clang
+does. Thus, the default location to look for builtin headers is in a path
+``$(dirname /path/to/tool)/../lib/clang/3.3/include`` relative to the tool
+binary. This works out-of-the-box for tools running from llvm's toplevel
+binary directory after building clang-headers, or if the tool is running from
+the binary directory of a clang install next to the clang binary.
+
+Tips: if your tool fails to find ``stddef.h`` or similar headers, call the tool
+with ``-v`` and look at the search paths it looks through.
+
+Linking
+^^^^^^^
+
+For a list of libraries to link, look at one of the tools' Makefiles (for
+example `clang-check/Makefile
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup>`_).
Added: www-releases/trunk/3.5.1/tools/clang/docs/MSVCCompatibility.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/MSVCCompatibility.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/MSVCCompatibility.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/MSVCCompatibility.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,141 @@
+.. raw:: html
+
+ <style type="text/css">
+ .none { background-color: #FFCCCC }
+ .partial { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+ </style>
+
+.. role:: none
+.. role:: partial
+.. role:: good
+
+==================
+MSVC compatibility
+==================
+
+When Clang compiles C++ code for Windows, it attempts to be compatible with
+MSVC. There are multiple dimensions to compatibility.
+
+First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
+should be able to link against MSVC-compiled code successfully. However, C++
+ABIs are particularly large and complicated, and Clang's support for MSVC's C++
+ABI is a work in progress. If you don't require MSVC ABI compatibility or don't
+want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
+better fit for your project.
+
+Second, Clang implements many MSVC language extensions, such as
+``__declspec(dllexport)`` and a handful of pragmas. These are typically
+controlled by ``-fms-extensions``.
+
+Third, MSVC accepts some C++ code that Clang will typically diagnose as
+invalid. When these constructs are present in widely included system headers,
+Clang attempts to recover and continue compiling the user's program. Most
+parsing and semantic compatibility tweaks are controlled by
+``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
+in progress.
+
+Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
+be compatible with MSVC's cl.exe.
+
+ABI features
+============
+
+The status of major ABI-impacting C++ features:
+
+* Record layout: :good:`Complete`. We've tested this with a fuzzer and have
+ fixed all known bugs.
+
+* Class inheritance: :good:`Mostly complete`. This covers all of the standard
+ OO features you would expect: virtual method inheritance, multiple
+ inheritance, and virtual inheritance. Every so often we uncover a bug where
+ our tables are incompatible, but this is pretty well in hand. This feature
+ has also been fuzz tested.
+
+* Name mangling: :good:`Ongoing`. Every new C++ feature generally needs its own
+ mangling. For example, member pointer template arguments have an interesting
+ and distinct mangling. Fortunately, incorrect manglings usually do not result
+ in runtime errors. Non-inline functions with incorrect manglings usually
+ result in link errors, which are relatively easy to diagnose. Incorrect
+ manglings for inline functions and templates result in multiple copies in the
+ final image. The C++ standard requires that those addresses be equal, but few
+ programs rely on this.
+
+* Member pointers: :good:`Mostly complete`. Standard C++ member pointers are
+ fully implemented and should be ABI compatible. Both `#pragma
+ pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC
+ supports an extension to allow creating a `pointer to a member of a virtual
+ base class`_. Clang does not yet support this.
+
+.. _#pragma pointers_to_members:
+ http://msdn.microsoft.com/en-us/library/83cch5a6.aspx
+.. _/vm: http://msdn.microsoft.com/en-us/library/yad46a6z.aspx
+.. _pointer to a member of a virtual base class: http://llvm.org/PR15713
+
+* Debug info: :partial:`Minimal`. Clang emits CodeView line tables into the
+ object file, similar to what MSVC emits when given the ``/Z7`` flag.
+ Microsoft's link.exe will read this information and use it to create a PDB,
+ enabling stack traces in all modern Windows debuggers. Clang does not emit
+ any type info or description of variable layout.
+
+* RTTI: :good:`Complete`. Generation of RTTI data structures has been
+ finished, along with support for the ``/GR`` flag.
+
+* Exceptions and SEH: :none:`Unstarted`. Clang can parse both constructs, but
+ does not know how to emit compatible handlers.
+
+* Thread-safe initialization of local statics: :none:`Unstarted`. We are ABI
+ compatible with MSVC 2013, which does not support thread-safe local statics.
+ MSVC "14" changed the ABI to make initialization of local statics thread safe,
+ and we have not yet implemented this.
+
+* Lambdas: :good:`Mostly complete`. Clang is compatible with Microsoft's
+ implementation of lambdas except for providing overloads for conversion to
+ function pointer for different calling conventions. However, Microsoft's
+ extension is non-conforming.
+
+Template instantiation and name lookup
+======================================
+
+MSVC allows many invalid constructs in class templates that Clang has
+historically rejected. In order to parse widely distributed headers for
+libraries such as the Active Template Library (ATL) and Windows Runtime Library
+(WRL), some template rules have been relaxed or extended in Clang on Windows.
+
+The first major semantic difference is that MSVC appears to defer all parsing
+an analysis of inline method bodies in class templates until instantiation
+time. By default on Windows, Clang attempts to follow suit. This behavior is
+controlled by the ``-fdelayed-template-parsing`` flag. While Clang delays
+parsing of method bodies, it still parses the bodies *before* template argument
+substitution, which is not what MSVC does. The following compatibility tweaks
+are necessary to parse the the template in those cases.
+
+MSVC allows some name lookup into dependent base classes. Even on other
+platforms, this has been a `frequently asked question`_ for Clang users. A
+dependent base class is a base class that depends on the value of a template
+parameter. Clang cannot see any of the names inside dependent bases while it
+is parsing your template, so the user is sometimes required to use the
+``typename`` keyword to assist the parser. On Windows, Clang attempts to
+follow the normal lookup rules, but if lookup fails, it will assume that the
+user intended to find the name in a dependent base. While parsing the
+following program, Clang will recover as if the user had written the
+commented-out code:
+
+.. _frequently asked question:
+ http://clang.llvm.org/compatibility.html#dep_lookup
+
+.. code-block:: c++
+
+ template <typename T>
+ struct Foo : T {
+ void f() {
+ /*typename*/ T::UnknownType x = /*this->*/unknownMember;
+ }
+ };
+
+After recovery, Clang warns the user that this code is non-standard and issues
+a hint suggesting how to fix the problem.
+
+As of this writing, Clang is able to compile a simple ATL hello world
+application. There are still issues parsing WRL headers for modern Windows 8
+apps, but they should be addressed soon.
Added: www-releases/trunk/3.5.1/tools/clang/docs/Makefile
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/Makefile?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/Makefile (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/Makefile Tue Jan 13 16:55:20 2015
@@ -0,0 +1,102 @@
+##===- docs/Makefile ---------------------------------------*- Makefile -*-===##
+#
+# The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+#
+##===----------------------------------------------------------------------===##
+
+CLANG_LEVEL := ..
+DIRS := tools
+
+ifdef BUILD_FOR_WEBSITE
+PROJ_OBJ_DIR = .
+DOXYGEN = doxygen
+
+$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in
+ cat $< | sed \
+ -e 's/@abs_srcdir@/./g' \
+ -e 's/@DOT@/dot/g' \
+ -e 's/@PACKAGE_VERSION@/mainline/' \
+ -e 's/@abs_builddir@/./g' \
+ -e 's/@enable_searchengine@/NO/g' \
+ -e 's/@searchengine_url@//g' \
+ -e 's/@enable_server_based_search@/NO/g' \
+ -e 's/@enable_external_search@/NO/g' \
+ -e 's/@extra_search_mappings@//g' > $@
+endif
+
+include $(CLANG_LEVEL)/Makefile
+
+HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \
+ $(wildcard $(PROJ_SRC_DIR)/*.css)
+#IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*)
+DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \
+ doxygen.intro
+EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img
+
+.PHONY: install-html install-doxygen doxygen generated
+
+install_targets :=
+ifndef ONLY_MAN_DOCS
+install_targets += install-html
+endif
+ifeq ($(ENABLE_DOXYGEN),1)
+install_targets += install-doxygen
+endif
+install-local:: $(install_targets)
+
+# Live documentation is generated for the web site using this target:
+# 'make generated BUILD_FOR_WEBSITE=1'
+generated:: doxygen
+
+install-html: $(PROJ_OBJ_DIR)/html.tar.gz
+ $(Echo) Installing HTML documentation
+ $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html
+ $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/img
+ $(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html
+# $(Verb) $(DataInstall) $(IMAGES) $(DESTDIR)$(PROJ_docsdir)/html/img
+ $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir)
+
+$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML)
+ $(Echo) Packaging HTML documentation
+ $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar
+ $(Verb) cd $(PROJ_SRC_DIR) && \
+ $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html
+ $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar
+
+install-doxygen: doxygen
+ $(Echo) Installing doxygen documentation
+ $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen
+ $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir)
+ $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \
+ $(FIND) . -type f -exec \
+ $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \;
+
+doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz
+
+regendoc:
+ $(Echo) Building doxygen documentation
+ $(Verb) $(RM) -rf $(PROJ_OBJ_DIR)/doxygen
+ $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg
+ $(Verb) sed -i "s/[$$]LatestRev[$$]/`svnversion $(PROJ_SRC_DIR)`/g" \
+ $(PROJ_OBJ_DIR)/doxygen/html/*.html
+
+$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg
+ $(Echo) Packaging doxygen documentation
+ $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar
+ $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen
+ $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar
+ $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/
+
+userloc: $(LLVM_SRC_ROOT)/docs/userloc.html
+
+$(LLVM_SRC_ROOT)/docs/userloc.html:
+ $(Echo) Making User LOC Table
+ $(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \
+ -html lib include tools runtime utils examples autoconf test > docs/userloc.html
+
+uninstall-local::
+ $(Echo) Uninstalling Documentation
+ $(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir)
Added: www-releases/trunk/3.5.1/tools/clang/docs/Makefile.sphinx
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/Makefile.sphinx?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/Makefile.sphinx (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/Makefile.sphinx Tue Jan 13 16:55:20 2015
@@ -0,0 +1,163 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default
+
+default: html
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @# FIXME: Remove this `cp` once HTML->Sphinx transition is completed.
+ @# Kind of a hack, but HTML-formatted docs are on the way out anyway.
+ @echo "Copying legacy HTML-formatted docs into $(BUILDDIR)/html"
+ @cp -a *.html $(BUILDDIR)/html
+ @# FIXME: What we really need is a way to specify redirects, so that
+ @# we can just redirect to a reST'ified version of this document.
+ @# PR14714 is tracking the issue of redirects.
+ @cp -a Block-ABI-Apple.txt $(BUILDDIR)/html
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Clang.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Clang.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/Clang"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Clang"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Added: www-releases/trunk/3.5.1/tools/clang/docs/MemorySanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/MemorySanitizer.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/MemorySanitizer.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/MemorySanitizer.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,224 @@
+================
+MemorySanitizer
+================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+MemorySanitizer is a detector of uninitialized reads. It consists of a
+compiler instrumentation module and a run-time library.
+
+Typical slowdown introduced by MemorySanitizer is **3x**.
+
+How to build
+============
+
+Follow the `clang build instructions <../get_started.html>`_. CMake
+build is supported.
+
+Usage
+=====
+
+Simply compile and link your program with ``-fsanitize=memory`` flag.
+The MemorySanitizer run-time library should be linked to the final
+executable, so make sure to use ``clang`` (not ``ld``) for the final
+link step. When linking shared libraries, the MemorySanitizer run-time
+is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it
+with MemorySanitizer). To get a reasonable performance add ``-O1`` or
+higher. To get meaninful stack traces in error messages add
+``-fno-omit-frame-pointer``. To get perfect stack traces you may need
+to disable inlining (just use ``-O1``) and tail call elimination
+(``-fno-optimize-sibling-calls``).
+
+.. code-block:: console
+
+ % cat umr.cc
+ #include <stdio.h>
+
+ int main(int argc, char** argv) {
+ int* a = new int[10];
+ a[5] = 0;
+ if (a[argc])
+ printf("xx\n");
+ return 0;
+ }
+
+ % clang -fsanitize=memory -fno-omit-frame-pointer -g -O2 umr.cc
+
+If a bug is detected, the program will print an error message to
+stderr and exit with a non-zero exit code. Currently, MemorySanitizer
+does not symbolize its output by default, so you may need to use a
+separate script to symbolize the result offline (this will be fixed in
+future).
+
+.. code-block:: console
+
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
+ #0 0x7f45944b418a in main umr.cc:6
+ #1 0x7f45938b676c in __libc_start_main libc-start.c:226
+
+By default, MemorySanitizer exits on the first detected error.
+
+``__has_feature(memory_sanitizer)``
+------------------------------------
+
+In some cases one may need to execute different code depending on
+whether MemorySanitizer is enabled. :ref:`\_\_has\_feature
+<langext-__has_feature-__has_extension>` can be used for this purpose.
+
+.. code-block:: c
+
+ #if defined(__has_feature)
+ # if __has_feature(memory_sanitizer)
+ // code that builds only under MemorySanitizer
+ # endif
+ #endif
+
+``__attribute__((no_sanitize_memory))``
+-----------------------------------------------
+
+Some code should not be checked by MemorySanitizer.
+One may use the function attribute
+:ref:`no_sanitize_memory <langext-memory_sanitizer>`
+to disable uninitialized checks in a particular function.
+MemorySanitizer may still instrument such functions to avoid false positives.
+This attribute may not be
+supported by other compilers, so we suggest to use it together with
+``__has_feature(memory_sanitizer)``.
+
+Blacklist
+---------
+
+MemorySanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to relax MemorySanitizer
+checks for certain source files and functions. All "Use of uninitialized value"
+warnings will be suppressed and all values loaded from memory will be
+considered fully initialized.
+
+Report symbolization
+====================
+
+MemorySanitizer uses an external symbolizer to print files and line numbers in
+reports. Make sure that ``llvm-symbolizer`` binary is in ``PATH``,
+or set environment variable ``MSAN_SYMBOLIZER_PATH`` to point to it.
+
+Origin Tracking
+===============
+
+MemorySanitizer can track origins of unitialized values, similar to
+Valgrind's --track-origins option. This feature is enabled by
+``-fsanitize-memory-track-origins`` Clang option. With the code from
+the example above,
+
+.. code-block:: console
+
+ % clang -fsanitize=memory -fsanitize-memory-track-origins -fno-omit-frame-pointer -g -O2 umr.cc
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
+ #0 0x7f7893912f0b in main umr2.cc:6
+ #1 0x7f789249b76c in __libc_start_main libc-start.c:226
+
+ Uninitialized value was created by a heap allocation
+ #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+ #1 0x7f7893912e06 in main umr2.cc:4
+
+Origin tracking has proved to be very useful for debugging MemorySanitizer
+reports. It slows down program execution by a factor of 1.5x-2x on top
+of the usual MemorySanitizer slowdown.
+
+MemorySanitizer can provide even more information with
+``-fsanitize-memory-track-origins=2`` flag. In this mode reports
+include information about intermediate stores the uninitialized value went
+through.
+
+.. code-block:: console
+
+ % cat umr2.cc
+ #include <stdio.h>
+
+ int main(int argc, char** argv) {
+ int* a = new int[10];
+ a[5] = 0;
+ volatile int b = a[argc];
+ if (b)
+ printf("xx\n");
+ return 0;
+ }
+
+ % clang -fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer -g -O2 umr2.cc
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
+ #0 0x7f7893912f0b in main umr2.cc:7
+ #1 0x7f789249b76c in __libc_start_main libc-start.c:226
+
+ Uninitialized value was stored to memory at
+ #0 0x7f78938b5c25 in __msan_chain_origin msan.cc:484
+ #1 0x7f7893912ecd in main umr2.cc:6
+
+ Uninitialized value was created by a heap allocation
+ #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+ #1 0x7f7893912e06 in main umr2.cc:4
+
+
+Handling external code
+============================
+
+MemorySanitizer requires that all program code is instrumented. This
+also includes any libraries that the program depends on, even libc.
+Failing to achieve this may result in false reports.
+
+Full MemorySanitizer instrumentation is very difficult to achieve. To
+make it easier, MemorySanitizer runtime library includes 70+
+interceptors for the most common libc functions. They make it possible
+to run MemorySanitizer-instrumented programs linked with
+uninstrumented libc. For example, the authors were able to bootstrap
+MemorySanitizer-instrumented Clang compiler by linking it with
+self-built instrumented libcxx (as a replacement for libstdc++).
+
+In the case when rebuilding all program dependencies with
+MemorySanitizer is problematic, an experimental MSanDR tool can be
+used. It is a DynamoRio-based tool that uses dynamic instrumentation
+to avoid false positives due to uninstrumented code. The tool simply
+marks memory from instrumented libraries as fully initialized. See
+`http://code.google.com/p/memory-sanitizer/wiki/Running#Running_with_the_dynamic_tool`
+for more information.
+
+Supported Platforms
+===================
+
+MemorySanitizer is supported on
+
+* Linux x86\_64 (tested on Ubuntu 12.04);
+
+Limitations
+===========
+
+* MemorySanitizer uses 2x more real memory than a native run, 3x with
+ origin tracking.
+* MemorySanitizer maps (but not reserves) 64 Terabytes of virtual
+ address space. This means that tools like ``ulimit`` may not work as
+ usually expected.
+* Static linking is not supported.
+* Non-position-independent executables are not supported. Therefore, the
+ ``fsanitize=memory`` flag will cause Clang to act as though the ``-fPIE``
+ flag had been supplied if compiling without ``-fPIC``, and as though the
+ ``-pie`` flag had been supplied if linking an executable.
+* Depending on the version of Linux kernel, running without ASLR may
+ be not supported. Note that GDB disables ASLR by default. To debug
+ instrumented programs, use "set disable-randomization off".
+
+Current Status
+==============
+
+MemorySanitizer is an experimental tool. It is known to work on large
+real-world programs, like Clang/LLVM itself.
+
+More Information
+================
+
+`http://code.google.com/p/memory-sanitizer <http://code.google.com/p/memory-sanitizer/>`_
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/Modules.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/Modules.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/Modules.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/Modules.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,871 @@
+=======
+Modules
+=======
+
+.. warning::
+ The functionality described on this page is supported for C and
+ Objective-C. C++ support is experimental.
+
+.. contents::
+ :local:
+
+Introduction
+============
+Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):
+
+.. code-block:: c
+
+ #include <SomeLib.h>
+
+The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.
+
+Modules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library.
+
+Problems with the current model
+-------------------------------
+The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:
+
+* **Compile-time scalability**: Each time a header is included, the
+ compiler must preprocess and parse the text in that header and every
+ header it includes, transitively. This process must be repeated for
+ every translation unit in the application, which involves a huge
+ amount of redundant work. In a project with *N* translation units
+ and *M* headers included in each translation unit, the compiler is
+ performing *M x N* work even though most of the *M* headers are
+ shared among multiple translation units. C++ is particularly bad,
+ because the compilation model for templates forces a huge amount of
+ code into headers.
+
+* **Fragility**: ``#include`` directives are treated as textual
+ inclusion by the preprocessor, and are therefore subject to any
+ active macro definitions at the time of inclusion. If any of the
+ active macro definitions happens to collide with a name in the
+ library, it can break the library API or cause compilation failures
+ in the library header itself. For an extreme example,
+ ``#define std "The C++ Standard"`` and then include a standard
+ library header: the result is a horrific cascade of failures in the
+ C++ Standard Library's implementation. More subtle real-world
+ problems occur when the headers for two different libraries interact
+ due to macro collisions, and users are forced to reorder
+ ``#include`` directives or introduce ``#undef`` directives to break
+ the (unintended) dependency.
+
+* **Conventional workarounds**: C programmers have
+ adopted a number of conventions to work around the fragility of the
+ C preprocessor model. Include guards, for example, are required for
+ the vast majority of headers to ensure that multiple inclusion
+ doesn't break the compile. Macro names are written with
+ ``LONG_PREFIXED_UPPERCASE_IDENTIFIERS`` to avoid collisions, and some
+ library/framework developers even use ``__underscored`` names
+ in headers to avoid collisions with "normal" names that (by
+ convention) shouldn't even be macros. These conventions are a
+ barrier to entry for developers coming from non-C languages, are
+ boilerplate for more experienced developers, and make our headers
+ far uglier than they should be.
+
+* **Tool confusion**: In a C-based language, it is hard to build tools
+ that work well with software libraries, because the boundaries of
+ the libraries are not clear. Which headers belong to a particular
+ library, and in what order should those headers be included to
+ guarantee that they compile correctly? Are the headers C, C++,
+ Objective-C++, or one of the variants of these languages? What
+ declarations in those headers are actually meant to be part of the
+ API, and what declarations are present only because they had to be
+ written as part of the header file?
+
+Semantic import
+---------------
+Modules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user's perspective, the code looks only slightly different, because one uses an ``import`` declaration rather than a ``#include`` preprocessor directive:
+
+.. code-block:: c
+
+ import std.io; // pseudo-code; see below for syntax discussion
+
+However, this module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the compiler sees the module import above, it loads a binary representation of the ``std.io`` module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by ``std.io``, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the ``std.io`` module will automatically be provided when the module is imported [#]_
+This semantic import model addresses many of the problems of the preprocessor inclusion model:
+
+* **Compile-time scalability**: The ``std.io`` module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the *M x N* compilation problem to an *M + N* problem.
+
+* **Fragility**: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for ``__underscored`` names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies.
+
+* **Tool confusion**: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program.
+
+Problems modules do not solve
+-----------------------------
+Many programming languages have a module or package system, and because of the variety of features provided by these languages it is important to define what modules do *not* do. In particular, all of the following are considered out-of-scope for modules:
+
+* **Rewrite the world's code**: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition.
+
+* **Versioning**: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries.
+
+* **Namespaces**: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules.
+
+* **Binary distribution of modules**: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible.
+
+Using Modules
+=============
+To enable modules, pass the command-line flag ``-fmodules`` [#]_. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later.
+
+Objective-C Import declaration
+------------------------------
+Objective-C provides syntax for importing a module via an *@import declaration*, which imports the named module:
+
+.. parsed-literal::
+
+ @import std;
+
+The @import declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g.,
+
+.. parsed-literal::
+
+ @import std.io;
+
+Redundant import declarations are ignored, and one is free to import modules at any point within the translation unit, so long as the import declaration is at global scope.
+
+At present, there is no C or C++ syntax for import declarations. Clang
+will track the modules proposal in the C++ committee. See the section
+`Includes as imports`_ to see how modules get imported today.
+
+Includes as imports
+-------------------
+The primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today's programs make extensive use of ``#include``, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate ``#include`` directives into the corresponding module import. For example, the include directive
+
+.. code-block:: c
+
+ #include <stdio.h>
+
+will be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of ``#include`` to ``import`` allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers.
+
+.. note::
+
+ The automatic mapping of ``#include`` to ``import`` also solves an implementation problem: importing a module with a definition of some entity (say, a ``struct Point``) and then parsing a header containing another definition of ``struct Point`` would cause a redefinition error, even if it is the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler can guarantee that it always sees just the already-parsed definition from the module.
+
+Module maps
+-----------
+The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
+
+Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
+
+.. note::
+
+ To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section `Modularizing a Platform`_ describes the steps one must take to write these module maps.
+
+One can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fmodule-maps`` option instead of the ``-fmodules`` option.
+
+Compilation model
+-----------------
+The binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will spawn a second instance of itself [#]_, with a fresh preprocessing context [#]_, to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered.
+
+The binary representation of modules is persisted in the *module cache*. Imports of a module will first query the module cache and, if a binary representation of the required module is already available, will load that representation directly. Thus, a module's headers will only be parsed once per language configuration, rather than once per translation unit that uses the module.
+
+Modules maintain references to each of the headers that were part of the module build. If any of those headers changes, or if any of the modules on which a module depends change, then the module will be (automatically) recompiled. The process should never require any user intervention.
+
+Command-line parameters
+-----------------------
+``-fmodules``
+ Enable the modules feature (EXPERIMENTAL).
+
+``-fcxx-modules``
+ Enable the modules feature for C++ (EXPERIMENTAL and VERY BROKEN).
+
+``-fmodule-maps``
+ Enable interpretation of module maps (EXPERIMENTAL). This option is implied by ``-fmodules``.
+
+``-fmodules-cache-path=<directory>``
+ Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.
+
+``-fno-autolink``
+ Disable automatic linking against the libraries associated with imported modules.
+
+``-fmodules-ignore-macro=macroname``
+ Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don't affect how modules are built, to improve sharing of compiled module files.
+
+``-fmodules-prune-interval=seconds``
+ Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning.
+
+``-fmodules-prune-after=seconds``
+ Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding.
+
+``-module-file-info <module file name>``
+ Debugging aid that prints information about a given module file (with a ``.pcm`` extension), including the language and preprocessor options that particular module variant was built with.
+
+``-fmodules-decluse``
+ Enable checking of module ``use`` declarations.
+
+``-fmodule-name=module-id``
+ Consider a source file as a part of the given module.
+
+``-fmodule-map-file=<file>``
+ Load the given module map file if a header from its directory or one of its subdirectories is loaded.
+
+``-fmodules-search-all``
+ If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion.
+
+Module Semantics
+================
+
+Modules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit.
+
+.. note::
+
+ This behavior is currently only approximated when building a module. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon.
+
+As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match. In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule.
+
+.. note::
+
+ Clang currently only performs minimal checking for violations of the One Definition Rule.
+
+Macros
+------
+
+The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one ``#define``\s a macro and the other ``#undef``\ines it). The rules for handling macro definitions in the presence of modules are as follows:
+
+* Each definition and undefinition of a macro is considered to be a distinct entity.
+* Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.
+* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive.
+* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it.
+* A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all ``#define`` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).
+* If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.
+
+For example, suppose:
+
+* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
+* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
+
+The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro.
+
+Module Map Language
+===================
+
+The module map language describes the mapping from header files to the
+logical structure of modules. To enable support for using a library as
+a module, one must write a ``module.modulemap`` file for that library. The
+``module.modulemap`` file is placed alongside the header files themselves,
+and is written in the module map language described below.
+
+.. note::
+ For compatibility with previous releases, if a module map file named
+ ``module.modulemap`` is not found, Clang will also search for a file named
+ ``module.map``. This behavior is deprecated and we plan to eventually
+ remove it.
+
+As an example, the module map file for the C standard library might look a bit like this:
+
+.. parsed-literal::
+
+ module std [system] [extern_c] {
+ module complex {
+ header "complex.h"
+ export *
+ }
+
+ module ctype {
+ header "ctype.h"
+ export *
+ }
+
+ module errno {
+ header "errno.h"
+ header "sys/errno.h"
+ export *
+ }
+
+ module fenv {
+ header "fenv.h"
+ export *
+ }
+
+ // ...more headers follow...
+ }
+
+Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: ``complex`` for complex numbers, ``ctype`` for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the ``export *`` command specifies that anything included by that submodule will be automatically re-exported.
+
+Lexical structure
+-----------------
+Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.
+
+.. parsed-literal::
+
+ ``config_macros`` ``export`` ``module``
+ ``conflict`` ``framework`` ``requires``
+ ``exclude`` ``header`` ``private``
+ ``explicit`` ``link`` ``umbrella``
+ ``extern`` ``use``
+
+Module map file
+---------------
+A module map file consists of a series of module declarations:
+
+.. parsed-literal::
+
+ *module-map-file*:
+ *module-declaration**
+
+Within a module map file, modules are referred to by a *module-id*, which uses periods to separate each part of a module's name:
+
+.. parsed-literal::
+
+ *module-id*:
+ *identifier* ('.' *identifier*)*
+
+Module declaration
+------------------
+A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.
+
+.. parsed-literal::
+
+ *module-declaration*:
+ ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}'
+ ``extern`` ``module`` *module-id* *string-literal*
+
+The *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition.
+
+The ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
+
+The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
+
+.. parsed-literal::
+
+ Name.framework/
+ Modules/module.modulemap Module map for the framework
+ Headers/ Subdirectory containing framework headers
+ Frameworks/ Subdirectory containing embedded frameworks
+ Resources/ Subdirectory containing additional resources
+ Name Symbolic link to the shared library for the framework
+
+The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+
+The ``extern_c`` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit ``extern "C"`` block. An import for a module with this attribute can appear within an ``extern "C"`` block. No other restrictions are lifted, however: the module currently cannot be imported within an ``extern "C"`` block in a namespace.
+
+Modules can have a number of different kinds of members, each of which is described below:
+
+.. parsed-literal::
+
+ *module-member*:
+ *requires-declaration*
+ *header-declaration*
+ *umbrella-dir-declaration*
+ *submodule-declaration*
+ *export-declaration*
+ *use-declaration*
+ *link-declaration*
+ *config-macros-declaration*
+ *conflict-declaration*
+
+An extern module references a module defined by the *module-id* in a file given by the *string-literal*. The file can be referenced either by an absolute path or by a path relative to the current map file.
+
+Requires declaration
+~~~~~~~~~~~~~~~~~~~~
+A *requires-declaration* specifies the requirements that an importing translation unit must satisfy to use the module.
+
+.. parsed-literal::
+
+ *requires-declaration*:
+ ``requires`` *feature-list*
+
+ *feature-list*:
+ *feature* (',' *feature*)*
+
+ *feature*:
+ ``!``:sub:`opt` *identifier*
+
+The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. The optional ``!`` indicates that a feature is incompatible with the module.
+
+The following features are defined:
+
+altivec
+ The target supports AltiVec.
+
+blocks
+ The "blocks" language feature is available.
+
+cplusplus
+ C++ support is available.
+
+cplusplus11
+ C++11 support is available.
+
+objc
+ Objective-C support is available.
+
+objc_arc
+ Objective-C Automatic Reference Counting (ARC) is available
+
+opencl
+ OpenCL is available
+
+tls
+ Thread local storage is available.
+
+*target feature*
+ A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
+
+
+**Example**: The ``std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
+
+.. parsed-literal::
+
+ module std {
+ // C standard library...
+
+ module vector {
+ requires cplusplus
+ header "vector"
+ }
+
+ module type_traits {
+ requires cplusplus11
+ header "type_traits"
+ }
+ }
+
+Header declaration
+~~~~~~~~~~~~~~~~~~
+A header declaration specifies that a particular header is associated with the enclosing module.
+
+.. parsed-literal::
+
+ *header-declaration*:
+ ``umbrella``:sub:`opt` ``header`` *string-literal*
+ ``private`` ``header`` *string-literal*
+ ``exclude`` ``header`` *string-literal*
+
+A header declaration that does not contain ``exclude`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule.
+
+A header with the ``umbrella`` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the ``#include`` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out ``header`` declarations for every library header. A given directory can only contain a single umbrella header.
+
+.. note::
+ Any headers not included by the umbrella header should have
+ explicit ``header`` declarations. Use the
+ ``-Wincomplete-umbrella`` warning option to ask Clang to complain
+ about headers not covered by the umbrella header or the module map.
+
+A header with the ``private`` specifier may not be included from outside the module itself.
+
+A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module.
+
+**Example**: The C header ``assert.h`` is an excellent candidate for an excluded header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings).
+
+.. parsed-literal::
+
+ module std [system] {
+ exclude header "assert.h"
+ }
+
+A given header shall not be referenced by more than one *header-declaration*.
+
+Umbrella directory declaration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.
+
+.. parsed-literal::
+
+ *umbrella-dir-declaration*:
+ ``umbrella`` *string-literal*
+
+The *string-literal* refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module.
+
+An *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella *header-declaration*. In other words, only a single kind of umbrella can be specified for a given directory.
+
+.. note::
+
+ Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
+
+
+Submodule declaration
+~~~~~~~~~~~~~~~~~~~~~
+Submodule declarations describe modules that are nested within their enclosing module.
+
+.. parsed-literal::
+
+ *submodule-declaration*:
+ *module-declaration*
+ *inferred-submodule-declaration*
+
+A *submodule-declaration* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``framework`` specifier, the enclosing module shall have a ``framework`` specifier; the submodule's contents shall be contained within the subdirectory ``Frameworks/SubName.framework``, where ``SubName`` is the name of the submodule.
+
+A *submodule-declaration* that is an *inferred-submodule-declaration* describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a *header-declaration*.
+
+.. parsed-literal::
+
+ *inferred-submodule-declaration*:
+ ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred-submodule-member** '}'
+
+ *inferred-submodule-member*:
+ ``export`` '*'
+
+A module containing an *inferred-submodule-declaration* shall have either an umbrella header or an umbrella directory. The headers to which the *inferred-submodule-declaration* applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories).
+
+For each header included by the umbrella header or in the umbrella directory that is not named by a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodule-declaration*. The module will:
+
+* Have the same name as the header (without the file extension)
+* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has the ``explicit`` specifier
+* Have the ``framework`` specifier, if the
+ *inferred-submodule-declaration* has the ``framework`` specifier
+* Have the attributes specified by the \ *inferred-submodule-declaration*
+* Contain a single *header-declaration* naming that header
+* Contain a single *export-declaration* ``export *``, if the \ *inferred-submodule-declaration* contains the \ *inferred-submodule-member* ``export *``
+
+**Example**: If the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
+
+.. parsed-literal::
+
+ module MyLib {
+ umbrella "MyLib"
+ explicit module * {
+ export *
+ }
+ }
+
+is equivalent to the (more verbose) module map:
+
+.. parsed-literal::
+
+ module MyLib {
+ explicit module A {
+ header "A.h"
+ export *
+ }
+
+ explicit module B {
+ header "B.h"
+ export *
+ }
+ }
+
+Export declaration
+~~~~~~~~~~~~~~~~~~
+An *export-declaration* specifies which imported modules will automatically be re-exported as part of a given module's API.
+
+.. parsed-literal::
+
+ *export-declaration*:
+ ``export`` *wildcard-module-id*
+
+ *wildcard-module-id*:
+ *identifier*
+ '*'
+ *identifier* '.' *wildcard-module-id*
+
+The *export-declaration* names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the *wildcard-module-id* up to, but not including, the first ``*`` will be re-exported.
+
+**Example**:: In the following example, importing ``MyLib.Derived`` also provides the API for ``MyLib.Base``:
+
+.. parsed-literal::
+
+ module MyLib {
+ module Base {
+ header "Base.h"
+ }
+
+ module Derived {
+ header "Derived.h"
+ export Base
+ }
+ }
+
+Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export everything ``Derived.h`` includes:
+
+.. parsed-literal::
+
+ module MyLib {
+ module Base {
+ header "Base.h"
+ }
+
+ module Derived {
+ header "Derived.h"
+ export *
+ }
+ }
+
+.. note::
+
+ The wildcard export syntax ``export *`` re-exports all of the
+ modules that were imported in the actual header file. Because
+ ``#include`` directives are automatically mapped to module imports,
+ ``export *`` provides the same transitive-inclusion behavior
+ provided by the C preprocessor, e.g., importing a given module
+ implicitly imports all of the modules on which it depends.
+ Therefore, liberal use of ``export *`` provides excellent backward
+ compatibility for programs that rely on transitive inclusion (i.e.,
+ all of them).
+
+Use declaration
+~~~~~~~~~~~~~~~
+A *use-declaration* specifies one of the other modules that the module is allowed to use. An import or include not matching one of these is rejected when the option *-fmodules-decluse*.
+
+.. parsed-literal::
+
+ *use-declaration*:
+ ``use`` *module-id*
+
+**Example**:: In the following example, use of A from C is not declared, so will trigger a warning.
+
+.. parsed-literal::
+
+ module A {
+ header "a.h"
+ }
+
+ module B {
+ header "b.h"
+ }
+
+ module C {
+ header "c.h"
+ use B
+ }
+
+When compiling a source file that implements a module, use the option ``-fmodule-name=module-id`` to indicate that the source file is logically part of that module.
+
+The compiler at present only applies restrictions to the module directly being built.
+
+Link declaration
+~~~~~~~~~~~~~~~~
+A *link-declaration* specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program.
+
+.. parsed-literal::
+
+ *link-declaration*:
+ ``link`` ``framework``:sub:`opt` *string-literal*
+
+The *string-literal* specifies the name of the library or framework against which the program should be linked. For example, specifying "clangBasic" would instruct the linker to link with ``-lclangBasic`` for a Unix-style linker.
+
+A *link-declaration* with the ``framework`` specifies that the linker should link against the named framework, e.g., with ``-framework MyFramework``.
+
+.. note::
+
+ Automatic linking with the ``link`` directive is not yet widely
+ implemented, because it requires support from both the object file
+ format and the linker. The notion is similar to Microsoft Visual
+ Studio's ``#pragma comment(lib...)``.
+
+Configuration macros declaration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *config-macros-declaration* specifies the set of configuration macros that have an effect on the the API of the enclosing module.
+
+.. parsed-literal::
+
+ *config-macros-declaration*:
+ ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt`
+
+ *config-macro-list*:
+ *identifier* (',' *identifier*)*
+
+Each *identifier* in the *config-macro-list* specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros.
+
+A *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.
+
+The ``exhaustive`` attribute specifies that the list of macros in the *config-macros-declaration* is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.
+
+.. note::
+
+ The ``exhaustive`` attribute implies that any macro definitions
+ for macros not listed as configuration macros should be ignored
+ completely when building the module. As an optimization, the
+ compiler could reduce the number of unique module variants by not
+ considering these non-configuration macros. This optimization is not
+ yet implemented in Clang.
+
+A translation unit shall not import the same module under different definitions of the configuration macros.
+
+.. note::
+
+ Clang implements a weak form of this requirement: the definitions
+ used for configuration macros are fixed based on the definitions
+ provided by the command line. If an import occurs and the definition
+ of any configuration macro has changed, the compiler will produce a
+ warning (under the control of ``-Wconfig-macros``).
+
+**Example:** A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the ``NDEBUG`` macro setting:
+
+.. parsed-literal::
+
+ module MyLogger {
+ umbrella header "MyLogger.h"
+ config_macros [exhaustive] NDEBUG
+ }
+
+Conflict declarations
+~~~~~~~~~~~~~~~~~~~~~
+A *conflict-declaration* describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality.
+
+.. parsed-literal::
+
+ *conflict-declaration*:
+ ``conflict`` *module-id* ',' *string-literal*
+
+The *module-id* of the *conflict-declaration* specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported.
+
+The *string-literal* provides a message to be provided as part of the compiler diagnostic when two modules conflict.
+
+.. note::
+
+ Clang emits a warning (under the control of ``-Wmodule-conflict``)
+ when a module conflict is discovered.
+
+**Example:**
+
+.. parsed-literal::
+
+ module Conflicts {
+ explicit module A {
+ header "conflict_a.h"
+ conflict B, "we just don't like B"
+ }
+
+ module B {
+ header "conflict_b.h"
+ }
+ }
+
+
+Attributes
+----------
+Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.
+
+.. parsed-literal::
+
+ *attributes*:
+ *attribute* *attributes*:sub:`opt`
+
+ *attribute*:
+ '[' *identifier* ']'
+
+Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
+
+Private Module Map Files
+------------------------
+Module map files are typically named ``module.modulemap`` and live
+either alongside the headers they describe or in a parent directory of
+the headers they describe. These module maps typically describe all of
+the API for the library.
+
+However, in some cases, the presence or absence of particular headers
+is used to distinguish between the "public" and "private" APIs of a
+particular library. For example, a library may contain the headers
+``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
+respectively. Additionally, ``Foo_Private.h`` may only be available on
+some versions of library, and absent in others. One cannot easily
+express this with a single module map file in the library:
+
+.. parsed-literal::
+
+ module Foo {
+ header "Foo.h"
+
+ explicit module Private {
+ header "Foo_Private.h"
+ }
+ }
+
+
+because the header ``Foo_Private.h`` won't always be available. The
+module map file could be customized based on whether
+``Foo_Private.h`` is available or not, but doing so requires custom
+build machinery.
+
+Private module map files, which are named ``module.private.modulemap``
+(or, for backward compatibility, ``module_private.map``), allow one to
+augment the primary module map file with an additional submodule. For
+example, we would split the module map file above into two module map
+files:
+
+.. code-block:: c
+
+ /* module.modulemap */
+ module Foo {
+ header "Foo.h"
+ }
+
+ /* module.private.modulemap */
+ explicit module Foo.Private {
+ header "Foo_Private.h"
+ }
+
+
+When a ``module.private.modulemap`` file is found alongside a
+``module.modulemap`` file, it is loaded after the ``module.modulemap``
+file. In our example library, the ``module.private.modulemap`` file
+would be available when ``Foo_Private.h`` is available, making it
+easier to split a library's public and private APIs along header
+boundaries.
+
+Modularizing a Platform
+=======================
+To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).
+
+The module maps will be written using the `module map language`_, which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
+
+**Macro-guarded copy-and-pasted definitions**
+ System headers vend core types such as ``size_t`` for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers:
+
+ .. parsed-literal::
+
+ #ifndef _SIZE_T
+ #define _SIZE_T
+ typedef __SIZE_TYPE__ size_t;
+ #endif
+
+ Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of ``size_t`` will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will *not* have a definition of ``size_t``. Importing the submodule corresponding to one of those headers will therefore not yield ``size_t`` as part of the API, because it wasn't there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere ``size_t`` is part of the API, or to eliminate the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of ``typedefs`` is not permitted.
+
+**Conflicting definitions**
+ Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don't tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply "don't do that", such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer).
+
+**Missing includes**
+ Headers are often missing ``#include`` directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don't happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes.
+
+**Headers that vend multiple APIs at different times**
+ Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend ``size_t`` only when the macro ``__need_size_t`` is defined before that header is included, and also vend ``wchar_t`` only when the macro ``__need_wchar_t`` is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
+
+To detect and help address some of these problems, the ``clang-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool's in-source documentation for information on how to check your system or library headers.
+
+Future Directions
+=================
+Modules is an experimental feature, and there is much work left to do to make it both real and useful. Here are a few ideas:
+
+**Detect unused module imports**
+ Unlike with ``#include`` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to remove the useless imports/includes.
+
+**Fix-Its for missing imports**
+ It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang should detect such cases and auto-import the required module (with a Fix-It!).
+
+**Improve modularize**
+ The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
+
+**C++ Support**
+ Modules clearly has to work for C++, or we'll never get to use it for the Clang code base.
+
+Where To Learn More About Modules
+=================================
+The Clang source code provides additional information about modules:
+
+``clang/lib/Headers/module.modulemap``
+ Module map for Clang's compiler-specific header files.
+
+``clang/test/Modules/``
+ Tests specifically related to modules functionality.
+
+``clang/include/clang/Basic/Module.h``
+ The ``Module`` class in this header describes a module, and is used throughout the compiler to implement modules.
+
+``clang/include/clang/Lex/ModuleMap.h``
+ The ``ModuleMap`` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).
+
+PCHInternals_
+ Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the ``clangSerialization`` library.
+
+.. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
+
+.. [#] Modules are only available in C and Objective-C; a separate flag ``-fcxx-modules`` enables modules support for C++, which is even more experimental and broken.
+
+.. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section `Modularizing a Platform`_ describes some of them.
+
+.. [#] The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
+
+.. [#] The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any ``-D`` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the `Configuration macros declaration`_ for more information.
+
+.. _PCHInternals: PCHInternals.html
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/ObjectiveCLiterals.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/ObjectiveCLiterals.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/ObjectiveCLiterals.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/ObjectiveCLiterals.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,548 @@
+====================
+Objective-C Literals
+====================
+
+Introduction
+============
+
+Three new features were introduced into clang at the same time:
+*NSNumber Literals* provide a syntax for creating ``NSNumber`` from
+scalar literal expressions; *Collection Literals* provide a short-hand
+for creating arrays and dictionaries; *Object Subscripting* provides a
+way to use subscripting with Objective-C objects. Users of Apple
+compiler releases can use these features starting with the Apple LLVM
+Compiler 4.0. Users of open-source LLVM.org compiler releases can use
+these features starting with clang v3.1.
+
+These language additions simplify common Objective-C programming
+patterns, make programs more concise, and improve the safety of
+container creation.
+
+This document describes how the features are implemented in clang, and
+how to use them in your own programs.
+
+NSNumber Literals
+=================
+
+The framework class ``NSNumber`` is used to wrap scalar values inside
+objects: signed and unsigned integers (``char``, ``short``, ``int``,
+``long``, ``long long``), floating point numbers (``float``,
+``double``), and boolean values (``BOOL``, C++ ``bool``). Scalar values
+wrapped in objects are also known as *boxed* values.
+
+In Objective-C, any character, numeric or boolean literal prefixed with
+the ``'@'`` character will evaluate to a pointer to an ``NSNumber``
+object initialized with that value. C's type suffixes may be used to
+control the size of numeric literals.
+
+Examples
+--------
+
+The following program illustrates the rules for ``NSNumber`` literals:
+
+.. code-block:: objc
+
+ void main(int argc, const char *argv[]) {
+ // character literals.
+ NSNumber *theLetterZ = @'Z'; // equivalent to [NSNumber numberWithChar:'Z']
+
+ // integral literals.
+ NSNumber *fortyTwo = @42; // equivalent to [NSNumber numberWithInt:42]
+ NSNumber *fortyTwoUnsigned = @42U; // equivalent to [NSNumber numberWithUnsignedInt:42U]
+ NSNumber *fortyTwoLong = @42L; // equivalent to [NSNumber numberWithLong:42L]
+ NSNumber *fortyTwoLongLong = @42LL; // equivalent to [NSNumber numberWithLongLong:42LL]
+
+ // floating point literals.
+ NSNumber *piFloat = @3.141592654F; // equivalent to [NSNumber numberWithFloat:3.141592654F]
+ NSNumber *piDouble = @3.1415926535; // equivalent to [NSNumber numberWithDouble:3.1415926535]
+
+ // BOOL literals.
+ NSNumber *yesNumber = @YES; // equivalent to [NSNumber numberWithBool:YES]
+ NSNumber *noNumber = @NO; // equivalent to [NSNumber numberWithBool:NO]
+
+ #ifdef __cplusplus
+ NSNumber *trueNumber = @true; // equivalent to [NSNumber numberWithBool:(BOOL)true]
+ NSNumber *falseNumber = @false; // equivalent to [NSNumber numberWithBool:(BOOL)false]
+ #endif
+ }
+
+Discussion
+----------
+
+NSNumber literals only support literal scalar values after the ``'@'``.
+Consequently, ``@INT_MAX`` works, but ``@INT_MIN`` does not, because
+they are defined like this:
+
+.. code-block:: objc
+
+ #define INT_MAX 2147483647 /* max value for an int */
+ #define INT_MIN (-2147483647-1) /* min value for an int */
+
+The definition of ``INT_MIN`` is not a simple literal, but a
+parenthesized expression. Parenthesized expressions are supported using
+the `boxed expression <#objc_boxed_expressions>`_ syntax, which is
+described in the next section.
+
+Because ``NSNumber`` does not currently support wrapping ``long double``
+values, the use of a ``long double NSNumber`` literal (e.g.
+``@123.23L``) will be rejected by the compiler.
+
+Previously, the ``BOOL`` type was simply a typedef for ``signed char``,
+and ``YES`` and ``NO`` were macros that expand to ``(BOOL)1`` and
+``(BOOL)0`` respectively. To support ``@YES`` and ``@NO`` expressions,
+these macros are now defined using new language keywords in
+``<objc/objc.h>``:
+
+.. code-block:: objc
+
+ #if __has_feature(objc_bool)
+ #define YES __objc_yes
+ #define NO __objc_no
+ #else
+ #define YES ((BOOL)1)
+ #define NO ((BOOL)0)
+ #endif
+
+The compiler implicitly converts ``__objc_yes`` and ``__objc_no`` to
+``(BOOL)1`` and ``(BOOL)0``. The keywords are used to disambiguate
+``BOOL`` and integer literals.
+
+Objective-C++ also supports ``@true`` and ``@false`` expressions, which
+are equivalent to ``@YES`` and ``@NO``.
+
+Boxed Expressions
+=================
+
+Objective-C provides a new syntax for boxing C expressions:
+
+.. code-block:: objc
+
+ @( <expression> )
+
+Expressions of scalar (numeric, enumerated, BOOL) and C string pointer
+types are supported:
+
+.. code-block:: objc
+
+ // numbers.
+ NSNumber *smallestInt = @(-INT_MAX - 1); // [NSNumber numberWithInt:(-INT_MAX - 1)]
+ NSNumber *piOverTwo = @(M_PI / 2); // [NSNumber numberWithDouble:(M_PI / 2)]
+
+ // enumerated types.
+ typedef enum { Red, Green, Blue } Color;
+ NSNumber *favoriteColor = @(Green); // [NSNumber numberWithInt:((int)Green)]
+
+ // strings.
+ NSString *path = @(getenv("PATH")); // [NSString stringWithUTF8String:(getenv("PATH"))]
+ NSArray *pathComponents = [path componentsSeparatedByString:@":"];
+
+Boxed Enums
+-----------
+
+Cocoa frameworks frequently define constant values using *enums.*
+Although enum values are integral, they may not be used directly as
+boxed literals (this avoids conflicts with future ``'@'``-prefixed
+Objective-C keywords). Instead, an enum value must be placed inside a
+boxed expression. The following example demonstrates configuring an
+``AVAudioRecorder`` using a dictionary that contains a boxed enumeration
+value:
+
+.. code-block:: objc
+
+ enum {
+ AVAudioQualityMin = 0,
+ AVAudioQualityLow = 0x20,
+ AVAudioQualityMedium = 0x40,
+ AVAudioQualityHigh = 0x60,
+ AVAudioQualityMax = 0x7F
+ };
+
+ - (AVAudioRecorder *)recordToFile:(NSURL *)fileURL {
+ NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
+ return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
+ }
+
+The expression ``@(AVAudioQualityMax)`` converts ``AVAudioQualityMax``
+to an integer type, and boxes the value accordingly. If the enum has a
+:ref:`fixed underlying type <objc-fixed-enum>` as in:
+
+.. code-block:: objc
+
+ typedef enum : unsigned char { Red, Green, Blue } Color;
+ NSNumber *red = @(Red), *green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]
+
+then the fixed underlying type will be used to select the correct
+``NSNumber`` creation method.
+
+Boxing a value of enum type will result in a ``NSNumber`` pointer with a
+creation method according to the underlying type of the enum, which can
+be a :ref:`fixed underlying type <objc-fixed-enum>`
+or a compiler-defined integer type capable of representing the values of
+all the members of the enumeration:
+
+.. code-block:: objc
+
+ typedef enum : unsigned char { Red, Green, Blue } Color;
+ Color col = Red;
+ NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]
+
+Boxed C Strings
+---------------
+
+A C string literal prefixed by the ``'@'`` token denotes an ``NSString``
+literal in the same way a numeric literal prefixed by the ``'@'`` token
+denotes an ``NSNumber`` literal. When the type of the parenthesized
+expression is ``(char *)`` or ``(const char *)``, the result of the
+boxed expression is a pointer to an ``NSString`` object containing
+equivalent character data, which is assumed to be '\\0'-terminated and
+UTF-8 encoded. The following example converts C-style command line
+arguments into ``NSString`` objects.
+
+.. code-block:: objc
+
+ // Partition command line arguments into positional and option arguments.
+ NSMutableArray *args = [NSMutableArray new];
+ NSMutableDictionary *options = [NSMutableDictionary new];
+ while (--argc) {
+ const char *arg = *++argv;
+ if (strncmp(arg, "--", 2) == 0) {
+ options[@(arg + 2)] = @(*++argv); // --key value
+ } else {
+ [args addObject:@(arg)]; // positional argument
+ }
+ }
+
+As with all C pointers, character pointer expressions can involve
+arbitrary pointer arithmetic, therefore programmers must ensure that the
+character data is valid. Passing ``NULL`` as the character pointer will
+raise an exception at runtime. When possible, the compiler will reject
+``NULL`` character pointers used in boxed expressions.
+
+Container Literals
+==================
+
+Objective-C now supports a new expression syntax for creating immutable
+array and dictionary container objects.
+
+Examples
+--------
+
+Immutable array expression:
+
+.. code-block:: objc
+
+ NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];
+
+This creates an ``NSArray`` with 3 elements. The comma-separated
+sub-expressions of an array literal can be any Objective-C object
+pointer typed expression.
+
+Immutable dictionary expression:
+
+.. code-block:: objc
+
+ NSDictionary *dictionary = @{
+ @"name" : NSUserName(),
+ @"date" : [NSDate date],
+ @"processInfo" : [NSProcessInfo processInfo]
+ };
+
+This creates an ``NSDictionary`` with 3 key/value pairs. Value
+sub-expressions of a dictionary literal must be Objective-C object
+pointer typed, as in array literals. Key sub-expressions must be of an
+Objective-C object pointer type that implements the
+``<NSCopying>`` protocol.
+
+Discussion
+----------
+
+Neither keys nor values can have the value ``nil`` in containers. If the
+compiler can prove that a key or value is ``nil`` at compile time, then
+a warning will be emitted. Otherwise, a runtime error will occur.
+
+Using array and dictionary literals is safer than the variadic creation
+forms commonly in use today. Array literal expressions expand to calls
+to ``+[NSArray arrayWithObjects:count:]``, which validates that all
+objects are non-``nil``. The variadic form,
+``+[NSArray arrayWithObjects:]`` uses ``nil`` as an argument list
+terminator, which can lead to malformed array objects. Dictionary
+literals are similarly created with
+``+[NSDictionary dictionaryWithObjects:forKeys:count:]`` which validates
+all objects and keys, unlike
+``+[NSDictionary dictionaryWithObjectsAndKeys:]`` which also uses a
+``nil`` parameter as an argument list terminator.
+
+Object Subscripting
+===================
+
+Objective-C object pointer values can now be used with C's subscripting
+operator.
+
+Examples
+--------
+
+The following code demonstrates the use of object subscripting syntax
+with ``NSMutableArray`` and ``NSMutableDictionary`` objects:
+
+.. code-block:: objc
+
+ NSMutableArray *array = ...;
+ NSUInteger idx = ...;
+ id newObject = ...;
+ id oldObject = array[idx];
+ array[idx] = newObject; // replace oldObject with newObject
+
+ NSMutableDictionary *dictionary = ...;
+ NSString *key = ...;
+ oldObject = dictionary[key];
+ dictionary[key] = newObject; // replace oldObject with newObject
+
+The next section explains how subscripting expressions map to accessor
+methods.
+
+Subscripting Methods
+--------------------
+
+Objective-C supports two kinds of subscript expressions: *array-style*
+subscript expressions use integer typed subscripts; *dictionary-style*
+subscript expressions use Objective-C object pointer typed subscripts.
+Each type of subscript expression is mapped to a message send using a
+predefined selector. The advantage of this design is flexibility: class
+designers are free to introduce subscripting by declaring methods or by
+adopting protocols. Moreover, because the method names are selected by
+the type of the subscript, an object can be subscripted using both array
+and dictionary styles.
+
+Array-Style Subscripting
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the subscript operand has an integral type, the expression is
+rewritten to use one of two different selectors, depending on whether
+the element is being read or written. When an expression reads an
+element using an integral index, as in the following example:
+
+.. code-block:: objc
+
+ NSUInteger idx = ...;
+ id value = object[idx];
+
+it is translated into a call to ``objectAtIndexedSubscript:``
+
+.. code-block:: objc
+
+ id value = [object objectAtIndexedSubscript:idx];
+
+When an expression writes an element using an integral index:
+
+.. code-block:: objc
+
+ object[idx] = newValue;
+
+it is translated to a call to ``setObject:atIndexedSubscript:``
+
+.. code-block:: objc
+
+ [object setObject:newValue atIndexedSubscript:idx];
+
+These message sends are then type-checked and performed just like
+explicit message sends. The method used for objectAtIndexedSubscript:
+must be declared with an argument of integral type and a return value of
+some Objective-C object pointer type. The method used for
+setObject:atIndexedSubscript: must be declared with its first argument
+having some Objective-C pointer type and its second argument having
+integral type.
+
+The meaning of indexes is left up to the declaring class. The compiler
+will coerce the index to the appropriate argument type of the method it
+uses for type-checking. For an instance of ``NSArray``, reading an
+element using an index outside the range ``[0, array.count)`` will raise
+an exception. For an instance of ``NSMutableArray``, assigning to an
+element using an index within this range will replace that element, but
+assigning to an element using an index outside this range will raise an
+exception; no syntax is provided for inserting, appending, or removing
+elements for mutable arrays.
+
+A class need not declare both methods in order to take advantage of this
+language feature. For example, the class ``NSArray`` declares only
+``objectAtIndexedSubscript:``, so that assignments to elements will fail
+to type-check; moreover, its subclass ``NSMutableArray`` declares
+``setObject:atIndexedSubscript:``.
+
+Dictionary-Style Subscripting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the subscript operand has an Objective-C object pointer type, the
+expression is rewritten to use one of two different selectors, depending
+on whether the element is being read from or written to. When an
+expression reads an element using an Objective-C object pointer
+subscript operand, as in the following example:
+
+.. code-block:: objc
+
+ id key = ...;
+ id value = object[key];
+
+it is translated into a call to the ``objectForKeyedSubscript:`` method:
+
+.. code-block:: objc
+
+ id value = [object objectForKeyedSubscript:key];
+
+When an expression writes an element using an Objective-C object pointer
+subscript:
+
+.. code-block:: objc
+
+ object[key] = newValue;
+
+it is translated to a call to ``setObject:forKeyedSubscript:``
+
+.. code-block:: objc
+
+ [object setObject:newValue forKeyedSubscript:key];
+
+The behavior of ``setObject:forKeyedSubscript:`` is class-specific; but
+in general it should replace an existing value if one is already
+associated with a key, otherwise it should add a new value for the key.
+No syntax is provided for removing elements from mutable dictionaries.
+
+Discussion
+----------
+
+An Objective-C subscript expression occurs when the base operand of the
+C subscript operator has an Objective-C object pointer type. Since this
+potentially collides with pointer arithmetic on the value, these
+expressions are only supported under the modern Objective-C runtime,
+which categorically forbids such arithmetic.
+
+Currently, only subscripts of integral or Objective-C object pointer
+type are supported. In C++, a class type can be used if it has a single
+conversion function to an integral or Objective-C pointer type, in which
+case that conversion is applied and analysis continues as appropriate.
+Otherwise, the expression is ill-formed.
+
+An Objective-C object subscript expression is always an l-value. If the
+expression appears on the left-hand side of a simple assignment operator
+(=), the element is written as described below. If the expression
+appears on the left-hand side of a compound assignment operator (e.g.
++=), the program is ill-formed, because the result of reading an element
+is always an Objective-C object pointer and no binary operators are
+legal on such pointers. If the expression appears in any other position,
+the element is read as described below. It is an error to take the
+address of a subscript expression, or (in C++) to bind a reference to
+it.
+
+Programs can use object subscripting with Objective-C object pointers of
+type ``id``. Normal dynamic message send rules apply; the compiler must
+see *some* declaration of the subscripting methods, and will pick the
+declaration seen first.
+
+Caveats
+=======
+
+Objects created using the literal or boxed expression syntax are not
+guaranteed to be uniqued by the runtime, but nor are they guaranteed to
+be newly-allocated. As such, the result of performing direct comparisons
+against the location of an object literal (using ``==``, ``!=``, ``<``,
+``<=``, ``>``, or ``>=``) is not well-defined. This is usually a simple
+mistake in code that intended to call the ``isEqual:`` method (or the
+``compare:`` method).
+
+This caveat applies to compile-time string literals as well.
+Historically, string literals (using the ``@"..."`` syntax) have been
+uniqued across translation units during linking. This is an
+implementation detail of the compiler and should not be relied upon. If
+you are using such code, please use global string constants instead
+(``NSString * const MyConst = @"..."``) or use ``isEqual:``.
+
+Grammar Additions
+=================
+
+To support the new syntax described above, the Objective-C
+``@``-expression grammar has the following new productions:
+
+::
+
+ objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal)
+ ;
+
+ object-literal : ('+' | '-')? numeric-constant
+ | character-constant
+ | boolean-constant
+ | array-literal
+ | dictionary-literal
+ ;
+
+ boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false' /* boolean keywords. */
+ ;
+
+ array-literal : '[' assignment-expression-list ']'
+ ;
+
+ assignment-expression-list : assignment-expression (',' assignment-expression-list)?
+ | /* empty */
+ ;
+
+ dictionary-literal : '{' key-value-list '}'
+ ;
+
+ key-value-list : key-value-pair (',' key-value-list)?
+ | /* empty */
+ ;
+
+ key-value-pair : assignment-expression ':' assignment-expression
+ ;
+
+Note: ``@true`` and ``@false`` are only supported in Objective-C++.
+
+Availability Checks
+===================
+
+Programs test for the new features by using clang's \_\_has\_feature
+checks. Here are examples of their use:
+
+.. code-block:: objc
+
+ #if __has_feature(objc_array_literals)
+ // new way.
+ NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
+ #else
+ // old way (equivalent).
+ id objects[] = { @"H", @"He", @"O", @"C" };
+ NSArray *elements = [NSArray arrayWithObjects:objects count:4];
+ #endif
+
+ #if __has_feature(objc_dictionary_literals)
+ // new way.
+ NSDictionary *masses = @{ @"H" : @1.0078, @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
+ #else
+ // old way (equivalent).
+ id keys[] = { @"H", @"He", @"O", @"C" };
+ id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026],
+ [NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] };
+ NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4];
+ #endif
+
+ #if __has_feature(objc_subscripting)
+ NSUInteger i, count = elements.count;
+ for (i = 0; i < count; ++i) {
+ NSString *element = elements[i];
+ NSNumber *mass = masses[element];
+ NSLog(@"the mass of %@ is %@", element, mass);
+ }
+ #else
+ NSUInteger i, count = [elements count];
+ for (i = 0; i < count; ++i) {
+ NSString *element = [elements objectAtIndex:i];
+ NSNumber *mass = [masses objectForKey:element];
+ NSLog(@"the mass of %@ is %@", element, mass);
+ }
+ #endif
+
+Code can use also ``__has_feature(objc_bool)`` to check for the
+availability of numeric literals support. This checks for the new
+``__objc_yes / __objc_no`` keywords, which enable the use of
+``@YES / @NO`` literals.
+
+To check whether boxed expressions are supported, use
+``__has_feature(objc_boxed_expressions)`` feature macro.
Added: www-releases/trunk/3.5.1/tools/clang/docs/PCHInternals.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/PCHInternals.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/PCHInternals.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/PCHInternals.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,561 @@
+========================================
+Precompiled Header and Modules Internals
+========================================
+
+.. contents::
+ :local:
+
+This document describes the design and implementation of Clang's precompiled
+headers (PCH) and modules. If you are interested in the end-user view, please
+see the :ref:`User's Manual <usersmanual-precompiled-headers>`.
+
+Using Precompiled Headers with ``clang``
+----------------------------------------
+
+The Clang compiler frontend, ``clang -cc1``, supports two command line options
+for generating and using PCH files.
+
+To generate PCH files using ``clang -cc1``, use the option :option:`-emit-pch`:
+
+.. code-block:: bash
+
+ $ clang -cc1 test.h -emit-pch -o test.h.pch
+
+This option is transparently used by ``clang`` when generating PCH files. The
+resulting PCH file contains the serialized form of the compiler's internal
+representation after it has completed parsing and semantic analysis. The PCH
+file can then be used as a prefix header with the :option:`-include-pch`
+option:
+
+.. code-block:: bash
+
+ $ clang -cc1 -include-pch test.h.pch test.c -o test.s
+
+Design Philosophy
+-----------------
+
+Precompiled headers are meant to improve overall compile times for projects, so
+the design of precompiled headers is entirely driven by performance concerns.
+The use case for precompiled headers is relatively simple: when there is a
+common set of headers that is included in nearly every source file in the
+project, we *precompile* that bundle of headers into a single precompiled
+header (PCH file). Then, when compiling the source files in the project, we
+load the PCH file first (as a prefix header), which acts as a stand-in for that
+bundle of headers.
+
+A precompiled header implementation improves performance when:
+
+* Loading the PCH file is significantly faster than re-parsing the bundle of
+ headers stored within the PCH file. Thus, a precompiled header design
+ attempts to minimize the cost of reading the PCH file. Ideally, this cost
+ should not vary with the size of the precompiled header file.
+
+* The cost of generating the PCH file initially is not so large that it
+ counters the per-source-file performance improvement due to eliminating the
+ need to parse the bundled headers in the first place. This is particularly
+ important on multi-core systems, because PCH file generation serializes the
+ build when all compilations require the PCH file to be up-to-date.
+
+Modules, as implemented in Clang, use the same mechanisms as precompiled
+headers to save a serialized AST file (one per module) and use those AST
+modules. From an implementation standpoint, modules are a generalization of
+precompiled headers, lifting a number of restrictions placed on precompiled
+headers. In particular, there can only be one precompiled header and it must
+be included at the beginning of the translation unit. The extensions to the
+AST file format required for modules are discussed in the section on
+:ref:`modules <pchinternals-modules>`.
+
+Clang's AST files are designed with a compact on-disk representation, which
+minimizes both creation time and the time required to initially load the AST
+file. The AST file itself contains a serialized representation of Clang's
+abstract syntax trees and supporting data structures, stored using the same
+compressed bitstream as `LLVM's bitcode file format
+<http://llvm.org/docs/BitCodeFormat.html>`_.
+
+Clang's AST files are loaded "lazily" from disk. When an AST file is initially
+loaded, Clang reads only a small amount of data from the AST file to establish
+where certain important data structures are stored. The amount of data read in
+this initial load is independent of the size of the AST file, such that a
+larger AST file does not lead to longer AST load times. The actual header data
+in the AST file --- macros, functions, variables, types, etc. --- is loaded
+only when it is referenced from the user's code, at which point only that
+entity (and those entities it depends on) are deserialized from the AST file.
+With this approach, the cost of using an AST file for a translation unit is
+proportional to the amount of code actually used from the AST file, rather than
+being proportional to the size of the AST file itself.
+
+When given the :option:`-print-stats` option, Clang produces statistics
+describing how much of the AST file was actually loaded from disk. For a
+simple "Hello, World!" program that includes the Apple ``Cocoa.h`` header
+(which is built as a precompiled header), this option illustrates how little of
+the actual precompiled header is required:
+
+.. code-block:: none
+
+ *** AST File Statistics:
+ 895/39981 source location entries read (2.238563%)
+ 19/15315 types read (0.124061%)
+ 20/82685 declarations read (0.024188%)
+ 154/58070 identifiers read (0.265197%)
+ 0/7260 selectors read (0.000000%)
+ 0/30842 statements read (0.000000%)
+ 4/8400 macros read (0.047619%)
+ 1/4995 lexical declcontexts read (0.020020%)
+ 0/4413 visible declcontexts read (0.000000%)
+ 0/7230 method pool entries read (0.000000%)
+ 0 method pool misses
+
+For this small program, only a tiny fraction of the source locations, types,
+declarations, identifiers, and macros were actually deserialized from the
+precompiled header. These statistics can be useful to determine whether the
+AST file implementation can be improved by making more of the implementation
+lazy.
+
+Precompiled headers can be chained. When you create a PCH while including an
+existing PCH, Clang can create the new PCH by referencing the original file and
+only writing the new data to the new file. For example, you could create a PCH
+out of all the headers that are very commonly used throughout your project, and
+then create a PCH for every single source file in the project that includes the
+code that is specific to that file, so that recompiling the file itself is very
+fast, without duplicating the data from the common headers for every file. The
+mechanisms behind chained precompiled headers are discussed in a :ref:`later
+section <pchinternals-chained>`.
+
+AST File Contents
+-----------------
+
+Clang's AST files are organized into several different blocks, each of which
+contains the serialized representation of a part of Clang's internal
+representation. Each of the blocks corresponds to either a block or a record
+within `LLVM's bitstream format <http://llvm.org/docs/BitCodeFormat.html>`_.
+The contents of each of these logical blocks are described below.
+
+.. image:: PCHLayout.png
+
+For a given AST file, the `llvm-bcanalyzer
+<http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html>`_ utility can be used
+to examine the actual structure of the bitstream for the AST file. This
+information can be used both to help understand the structure of the AST file
+and to isolate areas where AST files can still be optimized, e.g., through the
+introduction of abbreviations.
+
+Metadata Block
+^^^^^^^^^^^^^^
+
+The metadata block contains several records that provide information about how
+the AST file was built. This metadata is primarily used to validate the use of
+an AST file. For example, a precompiled header built for a 32-bit x86 target
+cannot be used when compiling for a 64-bit x86 target. The metadata block
+contains information about:
+
+Language options
+ Describes the particular language dialect used to compile the AST file,
+ including major options (e.g., Objective-C support) and more minor options
+ (e.g., support for "``//``" comments). The contents of this record correspond to
+ the ``LangOptions`` class.
+
+Target architecture
+ The target triple that describes the architecture, platform, and ABI for
+ which the AST file was generated, e.g., ``i386-apple-darwin9``.
+
+AST version
+ The major and minor version numbers of the AST file format. Changes in the
+ minor version number should not affect backward compatibility, while changes
+ in the major version number imply that a newer compiler cannot read an older
+ precompiled header (and vice-versa).
+
+Original file name
+ The full path of the header that was used to generate the AST file.
+
+Predefines buffer
+ Although not explicitly stored as part of the metadata, the predefines buffer
+ is used in the validation of the AST file. The predefines buffer itself
+ contains code generated by the compiler to initialize the preprocessor state
+ according to the current target, platform, and command-line options. For
+ example, the predefines buffer will contain "``#define __STDC__ 1``" when we
+ are compiling C without Microsoft extensions. The predefines buffer itself
+ is stored within the :ref:`pchinternals-sourcemgr`, but its contents are
+ verified along with the rest of the metadata.
+
+A chained PCH file (that is, one that references another PCH) and a module
+(which may import other modules) have additional metadata containing the list
+of all AST files that this AST file depends on. Each of those files will be
+loaded along with this AST file.
+
+For chained precompiled headers, the language options, target architecture and
+predefines buffer data is taken from the end of the chain, since they have to
+match anyway.
+
+.. _pchinternals-sourcemgr:
+
+Source Manager Block
+^^^^^^^^^^^^^^^^^^^^
+
+The source manager block contains the serialized representation of Clang's
+:ref:`SourceManager <SourceManager>` class, which handles the mapping from
+source locations (as represented in Clang's abstract syntax tree) into actual
+column/line positions within a source file or macro instantiation. The AST
+file's representation of the source manager also includes information about all
+of the headers that were (transitively) included when building the AST file.
+
+The bulk of the source manager block is dedicated to information about the
+various files, buffers, and macro instantiations into which a source location
+can refer. Each of these is referenced by a numeric "file ID", which is a
+unique number (allocated starting at 1) stored in the source location. Clang
+serializes the information for each kind of file ID, along with an index that
+maps file IDs to the position within the AST file where the information about
+that file ID is stored. The data associated with a file ID is loaded only when
+required by the front end, e.g., to emit a diagnostic that includes a macro
+instantiation history inside the header itself.
+
+The source manager block also contains information about all of the headers
+that were included when building the AST file. This includes information about
+the controlling macro for the header (e.g., when the preprocessor identified
+that the contents of the header dependent on a macro like
+``LLVM_CLANG_SOURCEMANAGER_H``).
+
+.. _pchinternals-preprocessor:
+
+Preprocessor Block
+^^^^^^^^^^^^^^^^^^
+
+The preprocessor block contains the serialized representation of the
+preprocessor. Specifically, it contains all of the macros that have been
+defined by the end of the header used to build the AST file, along with the
+token sequences that comprise each macro. The macro definitions are only read
+from the AST file when the name of the macro first occurs in the program. This
+lazy loading of macro definitions is triggered by lookups into the
+:ref:`identifier table <pchinternals-ident-table>`.
+
+.. _pchinternals-types:
+
+Types Block
+^^^^^^^^^^^
+
+The types block contains the serialized representation of all of the types
+referenced in the translation unit. Each Clang type node (``PointerType``,
+``FunctionProtoType``, etc.) has a corresponding record type in the AST file.
+When types are deserialized from the AST file, the data within the record is
+used to reconstruct the appropriate type node using the AST context.
+
+Each type has a unique type ID, which is an integer that uniquely identifies
+that type. Type ID 0 represents the NULL type, type IDs less than
+``NUM_PREDEF_TYPE_IDS`` represent predefined types (``void``, ``float``, etc.),
+while other "user-defined" type IDs are assigned consecutively from
+``NUM_PREDEF_TYPE_IDS`` upward as the types are encountered. The AST file has
+an associated mapping from the user-defined types block to the location within
+the types block where the serialized representation of that type resides,
+enabling lazy deserialization of types. When a type is referenced from within
+the AST file, that reference is encoded using the type ID shifted left by 3
+bits. The lower three bits are used to represent the ``const``, ``volatile``,
+and ``restrict`` qualifiers, as in Clang's :ref:`QualType <QualType>` class.
+
+.. _pchinternals-decls:
+
+Declarations Block
+^^^^^^^^^^^^^^^^^^
+
+The declarations block contains the serialized representation of all of the
+declarations referenced in the translation unit. Each Clang declaration node
+(``VarDecl``, ``FunctionDecl``, etc.) has a corresponding record type in the
+AST file. When declarations are deserialized from the AST file, the data
+within the record is used to build and populate a new instance of the
+corresponding ``Decl`` node. As with types, each declaration node has a
+numeric ID that is used to refer to that declaration within the AST file. In
+addition, a lookup table provides a mapping from that numeric ID to the offset
+within the precompiled header where that declaration is described.
+
+Declarations in Clang's abstract syntax trees are stored hierarchically. At
+the top of the hierarchy is the translation unit (``TranslationUnitDecl``),
+which contains all of the declarations in the translation unit but is not
+actually written as a specific declaration node. Its child declarations (such
+as functions or struct types) may also contain other declarations inside them,
+and so on. Within Clang, each declaration is stored within a :ref:`declaration
+context <DeclContext>`, as represented by the ``DeclContext`` class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named ``x`` in a structure) and
+iterate over the declarations stored within a context (e.g., iterate over all
+of the fields of a structure for structure layout).
+
+In Clang's AST file format, deserializing a declaration that is a
+``DeclContext`` is a separate operation from deserializing all of the
+declarations stored within that declaration context. Therefore, Clang will
+deserialize the translation unit declaration without deserializing the
+declarations within that translation unit. When required, the declarations
+stored within a declaration context will be deserialized. There are two
+representations of the declarations within a declaration context, which
+correspond to the name-lookup and iteration behavior described above:
+
+* When the front end performs name lookup to find a name ``x`` within a given
+ declaration context (for example, during semantic analysis of the expression
+ ``p->x``, where ``p``'s type is defined in the precompiled header), Clang
+ refers to an on-disk hash table that maps from the names within that
+ declaration context to the declaration IDs that represent each visible
+ declaration with that name. The actual declarations will then be
+ deserialized to provide the results of name lookup.
+* When the front end performs iteration over all of the declarations within a
+ declaration context, all of those declarations are immediately
+ de-serialized. For large declaration contexts (e.g., the translation unit),
+ this operation is expensive; however, large declaration contexts are not
+ traversed in normal compilation, since such a traversal is unnecessary.
+ However, it is common for the code generator and semantic analysis to
+ traverse declaration contexts for structs, classes, unions, and
+ enumerations, although those contexts contain relatively few declarations in
+ the common case.
+
+Statements and Expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Statements and expressions are stored in the AST file in both the :ref:`types
+<pchinternals-types>` and the :ref:`declarations <pchinternals-decls>` blocks,
+because every statement or expression will be associated with either a type or
+declaration. The actual statement and expression records are stored
+immediately following the declaration or type that owns the statement or
+expression. For example, the statement representing the body of a function
+will be stored directly following the declaration of the function.
+
+As with types and declarations, each statement and expression kind in Clang's
+abstract syntax tree (``ForStmt``, ``CallExpr``, etc.) has a corresponding
+record type in the AST file, which contains the serialized representation of
+that statement or expression. Each substatement or subexpression within an
+expression is stored as a separate record (which keeps most records to a fixed
+size). Within the AST file, the subexpressions of an expression are stored, in
+reverse order, prior to the expression that owns those expression, using a form
+of `Reverse Polish Notation
+<http://en.wikipedia.org/wiki/Reverse_Polish_notation>`_. For example, an
+expression ``3 - 4 + 5`` would be represented as follows:
+
++-----------------------+
+| ``IntegerLiteral(5)`` |
++-----------------------+
+| ``IntegerLiteral(4)`` |
++-----------------------+
+| ``IntegerLiteral(3)`` |
++-----------------------+
+| ``IntegerLiteral(-)`` |
++-----------------------+
+| ``IntegerLiteral(+)`` |
++-----------------------+
+| ``STOP`` |
++-----------------------+
+
+When reading this representation, Clang evaluates each expression record it
+encounters, builds the appropriate abstract syntax tree node, and then pushes
+that expression on to a stack. When a record contains *N* subexpressions ---
+``BinaryOperator`` has two of them --- those expressions are popped from the
+top of the stack. The special STOP code indicates that we have reached the end
+of a serialized expression or statement; other expression or statement records
+may follow, but they are part of a different expression.
+
+.. _pchinternals-ident-table:
+
+Identifier Table Block
+^^^^^^^^^^^^^^^^^^^^^^
+
+The identifier table block contains an on-disk hash table that maps each
+identifier mentioned within the AST file to the serialized representation of
+the identifier's information (e.g, the ``IdentifierInfo`` structure). The
+serialized representation contains:
+
+* The actual identifier string.
+* Flags that describe whether this identifier is the name of a built-in, a
+ poisoned identifier, an extension token, or a macro.
+* If the identifier names a macro, the offset of the macro definition within
+ the :ref:`pchinternals-preprocessor`.
+* If the identifier names one or more declarations visible from translation
+ unit scope, the :ref:`declaration IDs <pchinternals-decls>` of these
+ declarations.
+
+When an AST file is loaded, the AST file reader mechanism introduces itself
+into the identifier table as an external lookup source. Thus, when the user
+program refers to an identifier that has not yet been seen, Clang will perform
+a lookup into the identifier table. If an identifier is found, its contents
+(macro definitions, flags, top-level declarations, etc.) will be deserialized,
+at which point the corresponding ``IdentifierInfo`` structure will have the
+same contents it would have after parsing the headers in the AST file.
+
+Within the AST file, the identifiers used to name declarations are represented
+with an integral value. A separate table provides a mapping from this integral
+value (the identifier ID) to the location within the on-disk hash table where
+that identifier is stored. This mapping is used when deserializing the name of
+a declaration, the identifier of a token, or any other construct in the AST
+file that refers to a name.
+
+.. _pchinternals-method-pool:
+
+Method Pool Block
+^^^^^^^^^^^^^^^^^
+
+The method pool block is represented as an on-disk hash table that serves two
+purposes: it provides a mapping from the names of Objective-C selectors to the
+set of Objective-C instance and class methods that have that particular
+selector (which is required for semantic analysis in Objective-C) and also
+stores all of the selectors used by entities within the AST file. The design
+of the method pool is similar to that of the :ref:`identifier table
+<pchinternals-ident-table>`: the first time a particular selector is formed
+during the compilation of the program, Clang will search in the on-disk hash
+table of selectors; if found, Clang will read the Objective-C methods
+associated with that selector into the appropriate front-end data structure
+(``Sema::InstanceMethodPool`` and ``Sema::FactoryMethodPool`` for instance and
+class methods, respectively).
+
+As with identifiers, selectors are represented by numeric values within the AST
+file. A separate index maps these numeric selector values to the offset of the
+selector within the on-disk hash table, and will be used when de-serializing an
+Objective-C method declaration (or other Objective-C construct) that refers to
+the selector.
+
+AST Reader Integration Points
+-----------------------------
+
+The "lazy" deserialization behavior of AST files requires their integration
+into several completely different submodules of Clang. For example, lazily
+deserializing the declarations during name lookup requires that the name-lookup
+routines be able to query the AST file to find entities stored there.
+
+For each Clang data structure that requires direct interaction with the AST
+reader logic, there is an abstract class that provides the interface between
+the two modules. The ``ASTReader`` class, which handles the loading of an AST
+file, inherits from all of these abstract classes to provide lazy
+deserialization of Clang's data structures. ``ASTReader`` implements the
+following abstract classes:
+
+``ExternalSLocEntrySource``
+ This abstract interface is associated with the ``SourceManager`` class, and
+ is used whenever the :ref:`source manager <pchinternals-sourcemgr>` needs to
+ load the details of a file, buffer, or macro instantiation.
+
+``IdentifierInfoLookup``
+ This abstract interface is associated with the ``IdentifierTable`` class, and
+ is used whenever the program source refers to an identifier that has not yet
+ been seen. In this case, the AST reader searches for this identifier within
+ its :ref:`identifier table <pchinternals-ident-table>` to load any top-level
+ declarations or macros associated with that identifier.
+
+``ExternalASTSource``
+ This abstract interface is associated with the ``ASTContext`` class, and is
+ used whenever the abstract syntax tree nodes need to loaded from the AST
+ file. It provides the ability to de-serialize declarations and types
+ identified by their numeric values, read the bodies of functions when
+ required, and read the declarations stored within a declaration context
+ (either for iteration or for name lookup).
+
+``ExternalSemaSource``
+ This abstract interface is associated with the ``Sema`` class, and is used
+ whenever semantic analysis needs to read information from the :ref:`global
+ method pool <pchinternals-method-pool>`.
+
+.. _pchinternals-chained:
+
+Chained precompiled headers
+---------------------------
+
+Chained precompiled headers were initially intended to improve the performance
+of IDE-centric operations such as syntax highlighting and code completion while
+a particular source file is being edited by the user. To minimize the amount
+of reparsing required after a change to the file, a form of precompiled header
+--- called a precompiled *preamble* --- is automatically generated by parsing
+all of the headers in the source file, up to and including the last
+``#include``. When only the source file changes (and none of the headers it
+depends on), reparsing of that source file can use the precompiled preamble and
+start parsing after the ``#include``\ s, so parsing time is proportional to the
+size of the source file (rather than all of its includes). However, the
+compilation of that translation unit may already use a precompiled header: in
+this case, Clang will create the precompiled preamble as a chained precompiled
+header that refers to the original precompiled header. This drastically
+reduces the time needed to serialize the precompiled preamble for use in
+reparsing.
+
+Chained precompiled headers get their name because each precompiled header can
+depend on one other precompiled header, forming a chain of dependencies. A
+translation unit will then include the precompiled header that starts the chain
+(i.e., nothing depends on it). This linearity of dependencies is important for
+the semantic model of chained precompiled headers, because the most-recent
+precompiled header can provide information that overrides the information
+provided by the precompiled headers it depends on, just like a header file
+``B.h`` that includes another header ``A.h`` can modify the state produced by
+parsing ``A.h``, e.g., by ``#undef``'ing a macro defined in ``A.h``.
+
+There are several ways in which chained precompiled headers generalize the AST
+file model:
+
+Numbering of IDs
+ Many different kinds of entities --- identifiers, declarations, types, etc.
+ --- have ID numbers that start at 1 or some other predefined constant and
+ grow upward. Each precompiled header records the maximum ID number it has
+ assigned in each category. Then, when a new precompiled header is generated
+ that depends on (chains to) another precompiled header, it will start
+ counting at the next available ID number. This way, one can determine, given
+ an ID number, which AST file actually contains the entity.
+
+Name lookup
+ When writing a chained precompiled header, Clang attempts to write only
+ information that has changed from the precompiled header on which it is
+ based. This changes the lookup algorithm for the various tables, such as the
+ :ref:`identifier table <pchinternals-ident-table>`: the search starts at the
+ most-recent precompiled header. If no entry is found, lookup then proceeds
+ to the identifier table in the precompiled header it depends on, and so one.
+ Once a lookup succeeds, that result is considered definitive, overriding any
+ results from earlier precompiled headers.
+
+Update records
+ There are various ways in which a later precompiled header can modify the
+ entities described in an earlier precompiled header. For example, later
+ precompiled headers can add entries into the various name-lookup tables for
+ the translation unit or namespaces, or add new categories to an Objective-C
+ class. Each of these updates is captured in an "update record" that is
+ stored in the chained precompiled header file and will be loaded along with
+ the original entity.
+
+.. _pchinternals-modules:
+
+Modules
+-------
+
+Modules generalize the chained precompiled header model yet further, from a
+linear chain of precompiled headers to an arbitrary directed acyclic graph
+(DAG) of AST files. All of the same techniques used to make chained
+precompiled headers work --- ID number, name lookup, update records --- are
+shared with modules. However, the DAG nature of modules introduce a number of
+additional complications to the model:
+
+Numbering of IDs
+ The simple, linear numbering scheme used in chained precompiled headers falls
+ apart with the module DAG, because different modules may end up with
+ different numbering schemes for entities they imported from common shared
+ modules. To account for this, each module file provides information about
+ which modules it depends on and which ID numbers it assigned to the entities
+ in those modules, as well as which ID numbers it took for its own new
+ entities. The AST reader then maps these "local" ID numbers into a "global"
+ ID number space for the current translation unit, providing a 1-1 mapping
+ between entities (in whatever AST file they inhabit) and global ID numbers.
+ If that translation unit is then serialized into an AST file, this mapping
+ will be stored for use when the AST file is imported.
+
+Declaration merging
+ It is possible for a given entity (from the language's perspective) to be
+ declared multiple times in different places. For example, two different
+ headers can have the declaration of ``printf`` or could forward-declare
+ ``struct stat``. If each of those headers is included in a module, and some
+ third party imports both of those modules, there is a potentially serious
+ problem: name lookup for ``printf`` or ``struct stat`` will find both
+ declarations, but the AST nodes are unrelated. This would result in a
+ compilation error, due to an ambiguity in name lookup. Therefore, the AST
+ reader performs declaration merging according to the appropriate language
+ semantics, ensuring that the two disjoint declarations are merged into a
+ single redeclaration chain (with a common canonical declaration), so that it
+ is as if one of the headers had been included before the other.
+
+Name Visibility
+ Modules allow certain names that occur during module creation to be "hidden",
+ so that they are not part of the public interface of the module and are not
+ visible to its clients. The AST reader maintains a "visible" bit on various
+ AST nodes (declarations, macros, etc.) to indicate whether that particular
+ AST node is currently visible; the various name lookup mechanisms in Clang
+ inspect the visible bit to determine whether that entity, which is still in
+ the AST (because other, visible AST nodes may depend on it), can actually be
+ found by name lookup. When a new (sub)module is imported, it may make
+ existing, non-visible, already-deserialized AST nodes visible; it is the
+ responsibility of the AST reader to find and update these AST nodes when it
+ is notified of the import.
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.graffle
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.graffle?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.graffle
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.png?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/PCHLayout.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/3.5.1/tools/clang/docs/PTHInternals.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/PTHInternals.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/PTHInternals.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/PTHInternals.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,163 @@
+==========================
+Pretokenized Headers (PTH)
+==========================
+
+This document first describes the low-level interface for using PTH and
+then briefly elaborates on its design and implementation. If you are
+interested in the end-user view, please see the :ref:`User's Manual
+<usersmanual-precompiled-headers>`.
+
+Using Pretokenized Headers with ``clang`` (Low-level Interface)
+===============================================================
+
+The Clang compiler frontend, ``clang -cc1``, supports three command line
+options for generating and using PTH files.
+
+To generate PTH files using ``clang -cc1``, use the option ``-emit-pth``:
+
+.. code-block:: console
+
+ $ clang -cc1 test.h -emit-pth -o test.h.pth
+
+This option is transparently used by ``clang`` when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+``-include-pth`` option:
+
+.. code-block:: console
+
+ $ clang -cc1 -include-pth test.h.pth test.c -o test.s
+
+Alternatively, Clang's PTH files can be used as a raw "token-cache" (or
+"content" cache) of the source included by the original header file.
+This means that the contents of the PTH file are searched as substitutes
+for *any* source files that are used by ``clang -cc1`` to process a
+source file. This is done by specifying the ``-token-cache`` option:
+
+.. code-block:: console
+
+ $ cat test.h
+ #include <stdio.h>
+ $ clang -cc1 -emit-pth test.h -o test.h.pth
+ $ cat test.c
+ #include "test.h"
+ $ clang -cc1 test.c -o test -token-cache test.h.pth
+
+In this example the contents of ``stdio.h`` (and the files it includes)
+will be retrieved from ``test.h.pth``, as the PTH file is being used in
+this case as a raw cache of the contents of ``test.h``. This is a
+low-level interface used to both implement the high-level PTH interface
+as well as to provide alternative means to use PTH-style caching.
+
+PTH Design and Implementation
+=============================
+
+Unlike GCC's precompiled headers, which cache the full ASTs and
+preprocessor state of a header file, Clang's pretokenized header files
+mainly cache the raw lexer *tokens* that are needed to segment the
+stream of characters in a source file into keywords, identifiers, and
+operators. Consequently, PTH serves to mainly directly speed up the
+lexing and preprocessing of a source file, while parsing and
+type-checking must be completely redone every time a PTH file is used.
+
+Basic Design Tradeoffs
+----------------------
+
+In the long term there are plans to provide an alternate PCH
+implementation for Clang that also caches the work for parsing and type
+checking the contents of header files. The current implementation of PCH
+in Clang as pretokenized header files was motivated by the following
+factors:
+
+**Language independence**
+ PTH files work with any language that
+ Clang's lexer can handle, including C, Objective-C, and (in the early
+ stages) C++. This means development on language features at the
+ parsing level or above (which is basically almost all interesting
+ pieces) does not require PTH to be modified.
+
+**Simple design**
+ Relatively speaking, PTH has a simple design and
+ implementation, making it easy to test. Further, because the
+ machinery for PTH resides at the lower-levels of the Clang library
+ stack it is fairly straightforward to profile and optimize.
+
+Further, compared to GCC's PCH implementation (which is the dominate
+precompiled header file implementation that Clang can be directly
+compared against) the PTH design in Clang yields several attractive
+features:
+
+**Architecture independence**
+ In contrast to GCC's PCH files (and
+ those of several other compilers), Clang's PTH files are architecture
+ independent, requiring only a single PTH file when building a
+ program for multiple architectures.
+
+ For example, on Mac OS X one may wish to compile a "universal binary"
+ that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
+ architectures. In contrast, GCC requires a PCH file for each
+ architecture, as the definitions of types in the AST are
+ architecture-specific. Since a Clang PTH file essentially represents
+ a lexical cache of header files, a single PTH file can be safely used
+ when compiling for multiple architectures. This can also reduce
+ compile times because only a single PTH file needs to be generated
+ during a build instead of several.
+
+**Reduced memory pressure**
+ Similar to GCC, Clang reads PTH files
+ via the use of memory mapping (i.e., ``mmap``). Clang, however,
+ memory maps PTH files as read-only, meaning that multiple invocations
+ of ``clang -cc1`` can share the same pages in memory from a
+ memory-mapped PTH file. In comparison, GCC also memory maps its PCH
+ files but also modifies those pages in memory, incurring the
+ copy-on-write costs. The read-only nature of PTH can greatly reduce
+ memory pressure for builds involving multiple cores, thus improving
+ overall scalability.
+
+**Fast generation**
+ PTH files can be generated in a small fraction
+ of the time needed to generate GCC's PCH files. Since PTH/PCH
+ generation is a serial operation that typically blocks progress
+ during a build, faster generation time leads to improved processor
+ utilization with parallel builds on multicore machines.
+
+Despite these strengths, PTH's simple design suffers some algorithmic
+handicaps compared to other PCH strategies such as those used by GCC.
+While PTH can greatly speed up the processing time of a header file, the
+amount of work required to process a header file is still roughly linear
+in the size of the header file. In contrast, the amount of work done by
+GCC to process a precompiled header is (theoretically) constant (the
+ASTs for the header are literally memory mapped into the compiler). This
+means that only the pieces of the header file that are referenced by the
+source file including the header are the only ones the compiler needs to
+process during actual compilation. While GCC's particular implementation
+of PCH mitigates some of these algorithmic strengths via the use of
+copy-on-write pages, the approach itself can fundamentally dominate at
+an algorithmic level, especially when one considers header files of
+arbitrary size.
+
+There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).
+
+Internal PTH Optimizations
+--------------------------
+
+While the main optimization employed by PTH is to reduce lexing time of
+header files by caching pre-lexed tokens, PTH also employs several other
+optimizations to speed up the processing of header files:
+
+- ``stat`` caching: PTH files cache information obtained via calls to
+ ``stat`` that ``clang -cc1`` uses to resolve which files are included
+ by ``#include`` directives. This greatly reduces the overhead
+ involved in context-switching to the kernel to resolve included
+ files.
+
+- Fast skipping of ``#ifdef`` ... ``#endif`` chains: PTH files
+ record the basic structure of nested preprocessor blocks. When the
+ condition of the preprocessor block is false, all of its tokens are
+ immediately skipped instead of requiring them to be handled by
+ Clang's preprocessor.
+
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/RAVFrontendAction.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/RAVFrontendAction.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/RAVFrontendAction.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/RAVFrontendAction.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,216 @@
+==========================================================
+How to write RecursiveASTVisitor based ASTFrontendActions.
+==========================================================
+
+Introduction
+============
+
+In this tutorial you will learn how to create a FrontendAction that uses
+a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified
+name.
+
+Creating a FrontendAction
+=========================
+
+When writing a clang based tool like a Clang Plugin or a standalone tool
+based on LibTooling, the common entry point is the FrontendAction.
+FrontendAction is an interface that allows execution of user specific
+actions as part of the compilation. To run tools over the AST clang
+provides the convenience interface ASTFrontendAction, which takes care
+of executing the action. The only part left is to implement the
+CreateASTConsumer method that returns an ASTConsumer per translation
+unit.
+
+::
+
+ class FindNamedClassAction : public clang::ASTFrontendAction {
+ public:
+ virtual clang::ASTConsumer *CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return new FindNamedClassConsumer;
+ }
+ };
+
+Creating an ASTConsumer
+=======================
+
+ASTConsumer is an interface used to write generic actions on an AST,
+regardless of how the AST was produced. ASTConsumer provides many
+different entry points, but for our use case the only one needed is
+HandleTranslationUnit, which is called with the ASTContext for the
+translation unit.
+
+::
+
+ class FindNamedClassConsumer : public clang::ASTConsumer {
+ public:
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ // Traversing the translation unit decl via a RecursiveASTVisitor
+ // will visit all nodes in the AST.
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+ private:
+ // A RecursiveASTVisitor implementation.
+ FindNamedClassVisitor Visitor;
+ };
+
+Using the RecursiveASTVisitor
+=============================
+
+Now that everything is hooked up, the next step is to implement a
+RecursiveASTVisitor to extract the relevant information from the AST.
+
+The RecursiveASTVisitor provides hooks of the form bool
+VisitNodeType(NodeType \*) for most AST nodes; the exception are TypeLoc
+nodes, which are passed by-value. We only need to implement the methods
+for the relevant node types.
+
+Let's start by writing a RecursiveASTVisitor that visits all
+CXXRecordDecl's.
+
+::
+
+ class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+ public:
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ // For debugging, dumping the AST nodes will show which nodes are already
+ // being visited.
+ Declaration->dump();
+
+ // The return value indicates whether we want the visitation to proceed.
+ // Return false to stop the traversal of the AST.
+ return true;
+ }
+ };
+
+In the methods of our RecursiveASTVisitor we can now use the full power
+of the Clang AST to drill through to the parts that are interesting for
+us. For example, to find all class declaration with a certain name, we
+can check for a specific qualified name:
+
+::
+
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C")
+ Declaration->dump();
+ return true;
+ }
+
+Accessing the SourceManager and ASTContext
+==========================================
+
+Some of the information about the AST, like source locations and global
+identifier information, are not stored in the AST nodes themselves, but
+in the ASTContext and its associated source manager. To retrieve them we
+need to hand the ASTContext into our RecursiveASTVisitor implementation.
+
+The ASTContext is available from the CompilerInstance during the call to
+CreateASTConsumer. We can thus extract it there and hand it into our
+freshly created FindNamedClassConsumer:
+
+::
+
+ virtual clang::ASTConsumer *CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return new FindNamedClassConsumer(&Compiler.getASTContext());
+ }
+
+Now that the ASTContext is available in the RecursiveASTVisitor, we can
+do more interesting things with AST nodes, like looking up their source
+locations:
+
+::
+
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ // getFullLoc uses the ASTContext's SourceManager to resolve the source
+ // location and break it up into its line and column parts.
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+ }
+
+Putting it all together
+=======================
+
+Now we can combine all of the above into a small example program:
+
+::
+
+ #include "clang/AST/ASTConsumer.h"
+ #include "clang/AST/RecursiveASTVisitor.h"
+ #include "clang/Frontend/CompilerInstance.h"
+ #include "clang/Frontend/FrontendAction.h"
+ #include "clang/Tooling/Tooling.h"
+
+ using namespace clang;
+
+ class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+ public:
+ explicit FindNamedClassVisitor(ASTContext *Context)
+ : Context(Context) {}
+
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+ }
+
+ private:
+ ASTContext *Context;
+ };
+
+ class FindNamedClassConsumer : public clang::ASTConsumer {
+ public:
+ explicit FindNamedClassConsumer(ASTContext *Context)
+ : Visitor(Context) {}
+
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+ private:
+ FindNamedClassVisitor Visitor;
+ };
+
+ class FindNamedClassAction : public clang::ASTFrontendAction {
+ public:
+ virtual clang::ASTConsumer *CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return new FindNamedClassConsumer(&Compiler.getASTContext());
+ }
+ };
+
+ int main(int argc, char **argv) {
+ if (argc > 1) {
+ clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+ }
+ }
+
+We store this into a file called FindClassDecls.cpp and create the
+following CMakeLists.txt to link it:
+
+::
+
+ set(LLVM_USED_LIBS clangTooling)
+
+ add_clang_executable(find-class-decls FindClassDecls.cpp)
+
+When running this tool over a small code snippet it will output all
+declarations of a class n::m::C it found:
+
+::
+
+ $ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+ Found declaration at 1:29
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/README.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/README.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/README.txt (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/README.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1 @@
+See llvm/docs/README.txt
Added: www-releases/trunk/3.5.1/tools/clang/docs/ReleaseNotes.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/ReleaseNotes.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/ReleaseNotes.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/ReleaseNotes.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,267 @@
+=======================
+Clang 3.5 Release Notes
+=======================
+
+.. contents::
+ :local:
+ :depth: 2
+
+Written by the `LLVM Team <http://llvm.org/>`_
+
+Introduction
+============
+
+This document contains the release notes for the Clang C/C++/Objective-C
+frontend, part of the LLVM Compiler Infrastructure, release 3.5. Here we
+describe the status of Clang in some detail, including major
+improvements from the previous release and new feature work. For the
+general LLVM release notes, see `the LLVM
+documentation <http://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
+releases may be downloaded from the `LLVM releases web
+site <http://llvm.org/releases/>`_.
+
+For more information about Clang or LLVM, including information about
+the latest release, please check out the main please see the `Clang Web
+Site <http://clang.llvm.org>`_ or the `LLVM Web
+Site <http://llvm.org>`_.
+
+Note that if you are reading this file from a Subversion checkout or the
+main Clang web page, this document applies to the *next* release, not
+the current one. To see the release notes for a specific release, please
+see the `releases page <http://llvm.org/releases/>`_.
+
+What's New in Clang 3.5?
+========================
+
+Some of the major new features and improvements to Clang are listed
+here. Generic improvements to Clang as a whole or to its underlying
+infrastructure are described first, followed by language-specific
+sections with improvements to Clang's support for those languages.
+
+Major New Features
+------------------
+
+- Clang uses the new MingW ABI
+ GCC 4.7 changed the mingw ABI. Clang 3.4 and older use the GCC 4.6
+ ABI. Clang 3.5 and newer use the GCC 4.7 abi.
+
+- The __has_attribute feature test is now target-aware. Older versions of Clang
+ would return true when the attribute spelling was known, regardless of whether
+ the attribute was available to the specific target. Clang now returns true
+ only when the attribute pertains to the current compilation target.
+
+- Clang 3.5 now has parsing and semantic-analysis support for all OpenMP 3.1
+ pragmas (except atomics and ordered). LLVM's OpenMP runtime library,
+ originally developed by Intel, has been modified to work on ARM, PowerPC,
+ as well as X86. Code generation support is minimal at this point and will
+ continue to be developed for 3.6, along with the rest of OpenMP 3.1.
+ Support for OpenMP 4.0 features, such as SIMD and target accelerator
+ directives, is also in progress. Contributors to this work include AMD,
+ Argonne National Lab., IBM, Intel, Texas Instruments, University of Houston
+ and many others.
+
+Improvements to Clang's diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang's diagnostics are constantly being improved to catch more issues,
+explain them more clearly, and provide more accurate source information
+about them. The improvements since the 3.4 release include:
+
+- GCC compatibility: Clang displays a warning on unsupported gcc
+ optimization flags instead of an error.
+
+- Remarks system: Clang supports `-R` flags for enabling remarks. These are
+ diagnostic messages that provide information about the compilation process,
+ but don't suggest that a problem has been detected. As such, they cannot
+ be upgraded to errors with `-Werror` or `-Rerror`. A `-Reverything` flag
+ is provided (paralleling `-Weverything`) to turn on all remarks.
+
+- New remark `-Rpass`: Clang provides information about decisions made by
+ optimization passes during compilation. See :ref:`opt_rpass`.
+
+- New warning `-Wabsolute-value`: Clang warns about incorrect or useless usage
+ of the absolute functions (`abs`, `fabsf`, etc).
+
+ .. code-block:: c
+
+ #include <stdlib.h>
+ void foo() {
+ unsigned int i=0;
+ abs(i);
+ }
+
+ returns
+ `warning: taking the absolute value of unsigned type 'unsigned int' has no effect [-Wabsolute-value]`
+
+ or
+
+ .. code-block:: c
+
+ #include <stdlib.h>
+ void plop() {
+ long long i=0;
+ abs(i);
+ }
+
+ returns
+ `warning: absolute value function 'abs' given an argument of type 'long long' but has parameter of type 'int' which may cause truncation of value [-Wabsolute-value] use function 'llabs' instead`
+
+- New warning `-Wtautological-pointer-compare`:
+
+ .. code-block:: c++
+
+ #include <stddef.h>
+ void foo() {
+ int arr[5];
+ int x;
+ // warn on these conditionals
+ if (foo);
+ if (arr);
+ if (&x);
+ if (foo == NULL);
+ if (arr == NULL);
+ if (&x == NULL);
+ }
+
+ returns
+ `warning: comparison of address of 'x' equal to a null pointer is always false [-Wtautological-pointer-compare]`
+
+- New warning `-Wtautological-undefined-compare`:
+
+ .. code-block:: c++
+
+ #include <stddef.h>
+ void f(int &x) {
+ if (&x == nullptr) { }
+ }
+
+ returns
+ `warning: reference cannot be bound to dereferenced null pointer in well-defined C++ code; comparison may be assumed to always evaluate to false [-Wtautological-undefined-compare]`
+
+- ...
+
+New Compiler Flags
+------------------
+
+The integrated assembler is now turned on by default on ARM (and Thumb),
+so the use of the option `-fintegrated-as` is now redundant on those
+architectures. This is an important move to both *eat our own dog food*
+and to ease cross-compilation tremendously.
+
+We are aware of the problems that this may cause for code bases that
+rely on specific GNU syntax or extensions, and we're working towards
+getting them all fixed. Please, report bugs or feature requests if
+you find anything. In the meantime, use `-fno-integrated-as` to revert
+back the call to GNU assembler.
+
+In order to provide better diagnostics, the integrated assembler validates
+inline assembly when the integrated assembler is enabled. Because this is
+considered a feature of the compiler, it is controlled via the `fintegrated-as`
+and `fno-integrated-as` flags which enable and disable the integrated assembler
+respectively. `-integrated-as` and `-no-integrated-as` are now considered
+legacy flags (but are available as an alias to prevent breaking existing users),
+and users are encouraged to switch to the equivalent new feature flag.
+
+Deprecated flags `-faddress-sanitizer`, `-fthread-sanitizer`,
+`-fcatch-undefined-behavior` and `-fbounds-checking` were removed in favor of
+`-fsanitize=` family of flags.
+
+It is now possible to get optimization reports from the major transformation
+passes via three new flags: `-Rpass`, `-Rpass-missed` and `-Rpass-analysis`.
+These flags take a POSIX regular expression which indicates the name
+of the pass (or passes) that should emit optimization remarks.
+
+Options `-u` and `-z` are forwarded to the linker on gnutools toolchains.
+
+
+New Pragmas in Clang
+-----------------------
+
+Loop optimization hints can be specified using the new `#pragma clang loop`
+directive just prior to the desired loop. The directive allows vectorization and
+interleaving to be enabled or disabled. Vector width as well as interleave count
+can be manually specified. See :ref:`langext-pragma-loop` for details.
+
+C++ Language Changes in Clang
+-----------------------------
+
+- Reference parameters and return values from functions are more aggressively
+ assumed to refer to valid objects when optimizing. Clang will attempt to
+ issue a warning by default if it sees null checks being performed on
+ references, and `-fsanitize=null` can be used to detect null references
+ being formed at runtime.
+
+C++17 Feature Support
+^^^^^^^^^^^^^^^^^^^^^
+
+Clang has experimental support for some proposed C++1z (tentatively, C++17)
+features. This support can be enabled using the `-std=c++1z` flag. The
+supported features are:
+
+- `static_assert(expr)` with no message
+
+- `for (identifier : range)` as a synonym for `for (auto &&identifier : range)`
+
+- `template<template<...> typename>` as a synonym for `template<template<...> class>`
+
+Additionally, trigraphs are not recognized by default in this mode.
+`-ftrigraphs` can be used if you need to parse legacy code that uses trigraphs.
+Note that these features may be changed or removed in future Clang releases
+without notice.
+
+OpenMP C/C++ Language Changes in Clang
+--------------------------------------
+
+- `Status of supported OpenMP constructs
+ <https://github.com/clang-omp/clang/wiki/Status-of-supported-OpenMP-constructs>`_.
+
+
+Internal API Changes
+--------------------
+
+These are major API changes that have happened since the 3.4 release of
+Clang. If upgrading an external codebase that uses Clang as a library,
+this section should help get you past the largest hurdles of upgrading.
+
+- Clang uses `std::unique_ptr<T>` in many places where it used to use
+ raw `T *` pointers.
+
+Static Analyzer
+---------------
+
+Check for code testing a variable for 0 after using it as a denominator.
+This new checker, alpha.core.TestAfterDivZero, catches issues like this:
+
+.. code-block:: c
+
+ int sum = ...
+ int avg = sum / count; // potential division by zero...
+ if (count == 0) { ... } // ...caught here
+
+
+The `-analyzer-config` options are now passed from scan-build through to
+ccc-analyzer and then to Clang.
+
+With the option `-analyzer-config stable-report-filename=true`,
+instead of `report-XXXXXX.html`, scan-build/clang analyzer generate
+`report-<filename>-<function, method name>-<function position>-<id>.html`.
+(id = i++ for several issues found in the same function/method).
+
+List the function/method name in the index page of scan-build.
+
+Significant Known Problems
+==========================
+
+Additional Information
+======================
+
+A wide variety of additional information is available on the `Clang web
+page <http://clang.llvm.org/>`_. The web page contains versions of the
+API documentation which are up-to-date with the Subversion version of
+the source code. You can access versions of these documents specific to
+this release by going into the "``clang/docs/``" directory in the Clang
+tree.
+
+If you have any questions or comments about Clang, please feel free to
+contact us via the `mailing
+list <http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev>`_.
Added: www-releases/trunk/3.5.1/tools/clang/docs/SanitizerSpecialCaseList.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/SanitizerSpecialCaseList.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/SanitizerSpecialCaseList.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/SanitizerSpecialCaseList.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,79 @@
+===========================
+Sanitizer special case list
+===========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document describes the way to disable or alter the behavior of
+sanitizer tools for certain source-level entities by providing a special
+file at compile-time.
+
+Goal and usage
+==============
+
+User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer`
+or :doc:`MemorySanitizer` may want to disable or alter some checks for
+certain source-level entities to:
+
+* speedup hot function, which is known to be correct;
+* ignore a function that does some low-level magic (e.g. walks through the
+ thread stack, bypassing the frame boundaries);
+* ignore a known problem.
+
+To achieve this, user may create a file listing the entities they want to
+ignore, and pass it to clang at compile-time using
+``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details.
+
+Example
+=======
+
+.. code-block:: bash
+
+ $ cat foo.c
+ #include <stdlib.h>
+ void bad_foo() {
+ int *a = (int*)malloc(40);
+ a[10] = 1;
+ }
+ int main() { bad_foo(); }
+ $ cat blacklist.txt
+ # Ignore reports from bad_foo function.
+ fun:bad_foo
+ $ clang -fsanitize=address foo.c ; ./a.out
+ # AddressSanitizer prints an error report.
+ $ clang -fsanitize=address -fsanitize-blacklist=blacklist.txt foo.c ; ./a.out
+ # No error report here.
+
+Format
+======
+
+Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with "#" are ignored. The meanining of ``*`` in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are ``src`` and ``fun``, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.
+
+.. code-block:: bash
+
+ # Lines starting with # are ignored.
+ # Turn off checks for the source file (use absolute path or path relative
+ # to the current working directory):
+ src:/path/to/source/file.c
+ # Turn off checks for a particular functions (use mangled names):
+ fun:MyFooBar
+ fun:_Z8MyFooBarv
+ # Extended regular expressions are supported:
+ fun:bad_(foo|bar)
+ src:bad_source[1-9].c
+ # Shell like usage of * is supported (* is treated as .*):
+ src:bad/sources/*
+ fun:*BadFunction*
+ # Specific sanitizer tools may introduce categories.
+ src:/special/path/*=special_sources
Added: www-releases/trunk/3.5.1/tools/clang/docs/ThreadSafetyAnalysis.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/ThreadSafetyAnalysis.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/ThreadSafetyAnalysis.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/ThreadSafetyAnalysis.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,818 @@
+
+======================
+Thread Safety Analysis
+======================
+
+Introduction
+============
+
+Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code. The analysis is completely static (i.e.
+compile-time); there is no run-time overhead. The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting. It being developed by Google, and is used extensively
+on their internal code base.
+
+Thread safety analysis works very much like a type system for multi-threaded
+programs. In addition to declaring the *type* of data (e.g. ``int``, ``float``,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if ``foo`` is
+*guarded by* the mutex ``mu``, then the analysis will issue a warning whenever
+a piece of code reads or writes to ``foo`` without first locking ``mu``.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.
+
+Getting Started
+----------------
+
+.. code-block:: c++
+
+ #include "mutex.h"
+
+ class BankAccount {
+ private:
+ Mutex mu;
+ int balance GUARDED_BY(mu);
+
+ void depositImpl(int amount) {
+ balance += amount; // WARNING! Cannot write balance without locking mu.
+ }
+
+ void withdrawImpl(int amount) EXCLUSIVE_LOCKS_REQUIRED(mu) {
+ balance -= amount; // OK. Caller must have locked mu.
+ }
+
+ public:
+ void withdraw(int amount) {
+ mu.Lock();
+ withdrawImpl(amount); // OK. We've locked mu.
+ } // WARNING! Failed to unlock mu.
+
+ void transferFrom(BankAccount& b, int amount) {
+ mu.Lock();
+ b.withdrawImpl(amount); // WARNING! Calling withdrawImpl() requires locking b.mu.
+ depositImpl(amount); // OK. depositImpl() has no requirements.
+ mu.Unlock();
+ }
+ };
+
+This example demonstrates the basic concepts behind the analysis. The
+``GUARDED_BY`` attribute declares that a thread must lock ``mu`` before it can
+read or write to ``balance``, thus ensuring that the increment and decrement
+operations are atomic. Similarly, ``EXCLUSIVE_LOCKS_REQUIRED`` declares that
+the calling thread must lock ``mu`` before calling ``withdrawImpl``.
+Because the caller is assumed to have locked ``mu``, it is safe to modify
+``balance`` within the body of the method.
+
+The ``depositImpl()`` method does not have ``EXCLUSIVE_LOCKS_REQUIRED``, so the
+analysis issues a warning. Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in ``transferFrom()``, because although the method
+locks ``this->mu``, it does not lock ``b.mu``. The analysis understands
+that these are two separate mutexes, in two different objects.
+
+Finally, there is a warning in the ``withdraw()`` method, because it fails to
+unlock ``mu``. Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks. A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using ``LOCK``/``UNLOCK_FUNCTION``).
+
+
+Running The Analysis
+--------------------
+
+To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g.
+
+.. code-block:: bash
+
+ clang -c -Wthread-safety example.cpp
+
+Note that this example assumes the presence of a suitably annotated
+:ref:`mutexheader` that declares which methods perform locking,
+unlocking, and so on.
+
+
+Basic Concepts: Capabilities
+============================
+
+Thread safety analysis provides a way of protecting *resources* with
+*capabilities*. A resource is either a data member, or a function/method
+that provides access to some underlying resource. The analysis ensures that
+the calling thread cannot access the *resource* (i.e. call the function, or
+read/write the data) unless it has the *capability* to do so.
+
+Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability. The name of the object serves
+to identify the capability. The most common example is a mutex. For example,
+if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread
+to acquire the capability to access data that is protected by ``mu``. Similarly,
+calling ``mu.Unlock()`` releases that capability.
+
+A thread may hold a capability either *exclusively* or *shared*. An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time. This mechanism enforces a
+multiple-reader, single-writer pattern. Write operations to protected data
+require exclusive access, while read operations require only shared access.
+
+At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.) These act like keys
+or tokens that allow the thread to access a given resource. Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one. A thread can only release a capability to another thread, or acquire one
+from another thread. The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.
+
+The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept. The static analysis works
+by calculating an approximation of that set, called the *capability
+environment*. The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point. This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.
+
+
+Reference Guide
+===============
+
+The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are *strongly advised* to define macros for the various
+attributes; example definitions can be found in :ref:`mutexheader`, below.
+The following documentation assumes the use of macros.
+
+
+GUARDED_BY(c) and PT_GUARDED_BY(c)
+----------------------------------
+
+``GUARDED_BY`` is an attribute on data members, which declares that the data
+member is protected by the given capability. Read operations on the data
+require shared access, while write operations require exclusive access.
+
+``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the *data that
+it points to* is protected by the given capability.
+
+.. code-block:: c++
+
+ Mutex mu;
+ int *p1 GUARDED_BY(mu);
+ int *p2 PT_GUARDED_BY(mu);
+ unique_ptr<int> p3 PT_GUARDED_BY(mu);
+
+ void test() {
+ p1 = 0; // Warning!
+
+ p2 = new int; // OK.
+ *p2 = 42; // Warning!
+
+ p3.reset(new int); // OK.
+ *p3 = 42; // Warning!
+ }
+
+
+EXCLUSIVE_LOCKS_REQUIRED(...), SHARED_LOCKS_REQUIRED(...)
+---------------------------------------------------------
+
+``EXCLUSIVE_LOCKS_REQUIRED`` is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities. More than one capability may be specified. The capabilities
+must be held on entry to the function, *and must still be held on exit*.
+
+``SHARED_LOCKS_REQUIRED`` is similar, but requires only shared access.
+
+.. code-block:: c++
+
+ Mutex mu1, mu2;
+ int a GUARDED_BY(mu1);
+ int b GUARDED_BY(mu2);
+
+ void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) {
+ a = 0;
+ b = 0;
+ }
+
+ void test() {
+ mu1.Lock();
+ foo(); // Warning! Requires mu2.
+ mu1.Unlock();
+ }
+
+
+EXCLUSIVE_LOCK_FUNCTION(...), SHARED_LOCK_FUNCTION(...), UNLOCK_FUNCTION(...)
+-----------------------------------------------------------------------------
+
+``EXCLUSIVE_LOCK_FUNCTION`` is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it. The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit. ``SHARED_LOCK_FUNCTION`` is similar.
+
+``UNLOCK_FUNCTION`` declares that the function releases the given capability.
+The caller must hold the capability on entry, and will no longer hold it on
+exit. It does not matter whether the given capability is shared or exclusive.
+
+.. code-block:: c++
+
+ Mutex mu;
+ MyClass myObject GUARDED_BY(mu);
+
+ void lockAndInit() EXCLUSIVE_LOCK_FUNCTION(mu) {
+ mu.Lock();
+ myObject.init();
+ }
+
+ void cleanupAndUnlock() UNLOCK_FUNCTION(mu) {
+ myObject.cleanup();
+ } // Warning! Need to unlock mu.
+
+ void test() {
+ lockAndInit();
+ myObject.doSomething();
+ cleanupAndUnlock();
+ myObject.doSomething(); // Warning, mu is not locked.
+ }
+
+If no argument is passed to ``(UN)LOCK_FUNCTION``, then the argument is assumed
+to be ``this``, and the analysis will not check the body of the function. This
+pattern is intended for use by classes which hide locking details behind an
+abstract interface. E.g.
+
+.. code-block:: c++
+
+ template <class T>
+ class LOCKABLE Container {
+ private:
+ Mutex mu;
+ T* data;
+
+ public:
+ // Hide mu from public interface.
+ void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu.Lock(); }
+ void Unlock() UNLOCK_FUNCTION() { mu.Unlock(); }
+
+ T& getElem(int i) { return data[i]; }
+ };
+
+ void test() {
+ Container<int> c;
+ c.Lock();
+ int i = c.getElem(0);
+ c.Unlock();
+ }
+
+
+LOCKS_EXCLUDED(...)
+-------------------
+
+``LOCKS_EXCLUDED`` is an attribute on functions or methods, which declares that
+the caller must *not* hold the given capabilities. This annotation is
+used to prevent deadlock. Many mutex implementations are not re-entrant, so
+deadlock can occur if the function in question acquires the mutex a second time.
+
+.. code-block:: c++
+
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void clear() LOCKS_EXCLUDED(mu) {
+ mu.Lock();
+ a = 0;
+ mu.Unlock();
+ }
+
+ void reset() {
+ mu.Lock();
+ clear(); // Warning! Caller cannot hold 'mu'.
+ mu.Unlock();
+ }
+
+Unlike ``LOCKS_REQUIRED``, ``LOCKS_EXCLUDED`` is optional. The analysis will
+not issue a warning if the attribute is missing. See :ref:`limitations`.
+
+
+NO_THREAD_SAFETY_ANALYSIS
+-------------------------
+
+``NO_THREAD_SAFETY_ANALYSIS`` is an attribute on functions or methods, which
+turns off thread safety checking for that method. It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand. Reasons for
+(2) will be described in the :ref:`limitations`, below.
+
+.. code-block:: c++
+
+ class Counter {
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
+ };
+
+
+LOCK_RETURNED(c)
+----------------
+
+``LOCK_RETURNED`` is an attribute on functions or methods, which declares that
+the function returns a reference to the given capability. It is used to
+annotate getter methods that return mutexes.
+
+.. code-block:: c++
+
+ class MyClass {
+ private:
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ public:
+ Mutex* getMu() LOCK_RETURNED(mu) { return μ }
+
+ // analysis knows that getMu() == mu
+ void clear() EXCLUSIVE_LOCKS_REQUIRED(getMu()) { a = 0; }
+ };
+
+
+ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)
+-----------------------------------------
+
+``ACQUIRED_BEFORE`` and ``ACQUIRED_AFTER`` are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.
+
+.. code-block:: c++
+
+ Mutex m1;
+ Mutex m2 ACQUIRED_AFTER(m1);
+
+ // Alternative declaration
+ // Mutex m2;
+ // Mutex m1 ACQUIRED_BEFORE(m2);
+
+ void foo() {
+ m2.Lock();
+ m1.Lock(); // Warning! m2 must be acquired after m1.
+ m1.Unlock();
+ m2.Unlock();
+ }
+
+
+LOCKABLE
+--------
+
+``LOCKABLE`` is an attribute on classes, which specifies that objects of the
+class can be used as a capability. See the ``Container`` example given above,
+or the ``Mutex`` class in :ref:`mutexheader`.
+
+
+SCOPED_LOCKABLE
+---------------
+
+``SCOPED_LOCKABLE`` is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor. Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+``MutexLocker`` class in :ref:`mutexheader`, below.
+
+
+EXCLUSIVE_TRYLOCK_FUNCTION(<bool>, ...), SHARED_TRYLOCK_FUNCTION(<bool>, ...)
+-----------------------------------------------------------------------------
+
+These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be ``true`` or ``false``, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as ``(UN)LOCK_FUNCTION``. See :ref:`mutexheader`, below, for example uses.
+
+
+ASSERT_EXCLUSIVE_LOCK(...) and ASSERT_SHARED_LOCK(...)
+------------------------------------------------------
+
+These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability. The function is assumed
+to fail (no return) if the capability is not held. See :ref:`mutexheader`,
+below, for example uses.
+
+
+GUARDED_VAR and PT_GUARDED_VAR
+------------------------------
+
+Use of these attributes has been deprecated.
+
+
+Warning flags
+-------------
+
+* ``-Wthread-safety``: Umbrella flag which turns on the following three:
+
+ + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax.
+ + ``-Wthread-safety-analysis``: The core analysis.
+ + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely.
+ This warning can be disabled for code which has a lot of aliases.
+
+When new features and checks are added to the analysis, they can often introduce
+additional warnings. Those warnings are initially released as *beta* warnings
+for a period of time, after which they are migrated to the standard analysis.
+
+* ``-Wthread-safety-beta``: New features. Off by default.
+
+
+.. _faq:
+
+Frequently Asked Questions
+==========================
+
+(Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
+
+(A) Attributes should always go in the header.
+
+
+(Q) "*Mutex is not locked on every path through here?*" What does that mean?
+
+(A) See :ref:`conditional_locks`, below.
+
+
+.. _limitations:
+
+Known Limitations
+=================
+
+Lexical scope
+-------------
+
+Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules. In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.) However, use-before-declaration is not allowed
+between classes, as illustrated below.
+
+.. code-block:: c++
+
+ class Foo;
+
+ class Bar {
+ void bar(Foo* f) EXCLUSIVE_LOCKS_REQUIRED(f->mu); // Error: mu undeclared.
+ };
+
+ class Foo {
+ Mutex mu;
+ };
+
+
+Private Mutexes
+---------------
+
+Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation. However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if ``mu``
+is a private member of ``c``, then it is an error to write ``c.mu`` in an
+attribute.
+
+One workround is to (ab)use the ``LOCK_RETURNED`` attribute to provide a public
+*name* for a private mutex, without actually exposing the underlying mutex.
+For example:
+
+.. code-block:: c++
+
+ class MyClass {
+ private:
+ Mutex mu;
+
+ public:
+ // For thread safety analysis only. Does not actually return mu.
+ Mutex* getMu() LOCK_RETURNED(mu) { return 0; }
+
+ void doSomething() EXCLUSIVE_LOCKS_REQUIRED(mu);
+ };
+
+ void doSomethingTwice(MyClass& c) EXCLUSIVE_LOCKS_REQUIRED(c.getMu()) {
+ // The analysis thinks that c.getMu() == c.mu
+ c.doSomething();
+ c.doSomething();
+ }
+
+In the above example, ``doSomethingTwice()`` is an external routine that
+requires ``c.mu`` to be locked, which cannot be declared directly because ``mu``
+is private. This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base. The workaround is to define ``getMu()``
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.
+
+
+False negatives on pass by reference.
+-------------------------------------
+
+The current version of the analysis only checks operations which refer to
+guarded data members directly by name. If the data members are accessed
+indirectly, via a pointer or reference, then no warning is generated. Thus,
+no warnings will be generated for the following code:
+
+.. code-block:: c++
+
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void clear(int& ra) { ra = 0; }
+
+ void test() {
+ int *p = &a;
+ *p = 0; // No warning. *p is an alias to a.
+
+ clear(a); // No warning. 'a' is passed by reference.
+ }
+
+This issue is by far the biggest source of false negatives in the current
+version of the analysis. At a fundamental level, the
+false negatives are caused by the fact that annotations are attached to data
+members, rather than types. The type of ``&a`` should really be
+``int GUARDED_BY(mu)*``, rather than ``int*``, and the statement ``p = &a``
+should thus generate a type error. However, attaching attributes to types
+would be an invasive change to the C++ type system, with potential
+ramifications with respect to template instantation, function overloading,
+and so on. Thus, a complete solution to this issue is simply not feasible.
+
+Future versions of the analysis will include better support for pointer
+alias analysis, along with limited checking of guarded types, in order to
+reduce the number of false negatives.
+
+
+.. _conditional_locks:
+
+No conditionally held locks.
+----------------------------
+
+The analysis must be able to determine whether a lock is held, or not held, at
+every program point. Thus, sections of code where a lock *might be held* will
+generate spurious warnings (false positives). For example:
+
+.. code-block:: c++
+
+ void foo() {
+ bool b = needsToLock();
+ if (b) mu.Lock();
+ ... // Warning! Mutex 'mu' is not held on every path through here.
+ if (b) mu.Unlock();
+ }
+
+
+No checking inside constructors and destructors.
+------------------------------------------------
+
+The analysis currently does not do any checking inside constructors or
+destructors. In other words, every constructor and destructor is treated as
+if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.
+
+Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else. However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is "owned by" the enclosing object.
+
+No inlining.
+------------
+
+Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking. It relies only on the declared attributes of a function, and will
+not attempt to "step inside", or inline any method calls. As a result, code
+such as the following will not work:
+
+.. code-block:: c++
+
+ template<class T>
+ class AutoCleanup {
+ T* object;
+ void (T::*mp)();
+
+ public:
+ AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
+ ~AutoCleanup() { (object->*mp)(); }
+ };
+
+ Mutex mu;
+ void foo() {
+ mu.Lock();
+ AutoCleanup<Mutex>(&mu, &Mutex::Unlock);
+ ...
+ } // Warning, mu is not unlocked.
+
+In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so
+the warning is bogus. However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor. Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.
+
+
+LOCKS_EXCLUDED is not transitive.
+---------------------------------
+
+A function which calls a method marked with LOCKS_EXCLUDED is not required to
+put LOCKS_EXCLUDED in its own interface. LOCKS_EXCLUDED behaves differently
+from LOCKS_REQUIRED in this respect, and it can result in false negatives:
+
+.. code-block:: c++
+
+ class Foo {
+ Mutex mu;
+
+ void foo() {
+ mu.Lock();
+ bar(); // No warning
+ mu.Unlock();
+ }
+
+ void bar() { baz(); } // No warning. (Should have LOCKS_EXCLUDED(mu).)
+
+ void baz() LOCKS_EXCLUDED(mu);
+ };
+
+The lack of transitivity is due to the fact that LOCKS_EXCLUDED can easily
+break encapsulation; it would be a bad idea to require functions to list the
+names private locks which happen to be acquired internally.
+
+
+No alias analysis.
+------------------
+
+The analysis currently does not track pointer aliases. Thus, there can be
+false positives if two pointers both point to the same mutex.
+
+
+.. code-block:: c++
+
+ class MutexUnlocker {
+ Mutex* mu;
+
+ public:
+ MutexUnlocker(Mutex* m) UNLOCK_FUNCTION(m) : mu(m) { mu->Unlock(); }
+ ~MutexUnlocker() EXCLUSIVE_LOCK_FUNCTION(mu) { mu->Lock(); }
+ };
+
+ Mutex mutex;
+ void test() EXCLUSIVE_LOCKS_REQUIRED(mutex) {
+ {
+ MutexUnlocker munl(&mutex); // unlocks mutex
+ doSomeIO();
+ } // Warning: locks munl.mu
+ }
+
+The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in :ref:`mutexheader`. However, it doesn't work because the analysis
+doesn't know that munl.mu == mutex. The SCOPED_LOCKABLE attribute handles
+aliasing
+
+
+ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
+-------------------------------------------------------------------------
+
+To be fixed in a future update.
+
+
+.. _mutexheader:
+
+mutex.h
+=======
+
+Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations. The following code provides ``mutex.h`` as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.
+
+
+.. code-block:: c++
+
+ #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
+ #define THREAD_SAFETY_ANALYSIS_MUTEX_H
+
+ // Enable thread safety attributes only with clang.
+ // The attributes can be safely erased when compiling with other compilers.
+ #if defined(__clang__) && (!defined(SWIG))
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
+ #else
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
+ #endif
+
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
+
+ #define GUARDED_BY(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
+
+ #define GUARDED_VAR \
+ THREAD_ANNOTATION_ATTRIBUTE__(guarded)
+
+ #define PT_GUARDED_BY(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
+
+ #define PT_GUARDED_VAR \
+ THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded)
+
+ #define ACQUIRED_AFTER(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
+
+ #define ACQUIRED_BEFORE(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
+
+ #define EXCLUSIVE_LOCKS_REQUIRED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
+
+ #define SHARED_LOCKS_REQUIRED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
+
+ #define LOCKS_EXCLUDED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
+
+ #define LOCK_RETURNED(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
+
+ #define LOCKABLE \
+ THREAD_ANNOTATION_ATTRIBUTE__(lockable)
+
+ #define SCOPED_LOCKABLE \
+ THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
+
+ #define EXCLUSIVE_LOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
+
+ #define SHARED_LOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
+
+ #define ASSERT_EXCLUSIVE_LOCK(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
+
+ #define ASSERT_SHARED_LOCK(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
+
+ #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
+
+ #define SHARED_TRYLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
+
+ #define UNLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
+
+ #define NO_THREAD_SAFETY_ANALYSIS \
+ THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
+
+
+ // Defines an annotated interface for mutexes.
+ // These methods can be implemented to use any internal mutex implementation.
+ class LOCKABLE Mutex {
+ public:
+ // Acquire/lock this mutex exclusively. Only one thread can have exclusive
+ // access at any one time. Write operations to guarded data require an
+ // exclusive lock.
+ void Lock() EXCLUSIVE_LOCK_FUNCTION();
+
+ // Acquire/lock this mutex for read operations, which require only a shared
+ // lock. This assumes a multiple-reader, single writer semantics. Multiple
+ // threads may acquire the mutex simultaneously as readers, but a writer must
+ // wait for all of them to release the mutex before it can acquire it
+ // exclusively.
+ void ReaderLock() SHARED_LOCK_FUNCTION();
+
+ // Release/unlock the mutex, regardless of whether it is exclusive or shared.
+ void Unlock() UNLOCK_FUNCTION();
+
+ // Try to acquire the mutex. Returns true on success, and false on failure.
+ bool TryLock() EXCLUSIVE_TRYLOCK_FUNCTION(true);
+
+ // Try to acquire the mutex for read operations.
+ bool ReaderTryLock() SHARED_TRYLOCK_FUNCTION(true);
+
+ // Assert that this mutex is currently held by the calling thread.
+ void AssertHeld() ASSERT_EXCLUSIVE_LOCK();
+
+ // Assert that is mutex is currently held for read operations.
+ void AssertReaderHeld() ASSERT_SHARED_LOCK();
+ };
+
+
+ // MutexLocker is an RAII class that acquires a mutex in its constructor, and
+ // releases it in its destructor.
+ class SCOPED_LOCKABLE MutexLocker {
+ private:
+ Mutex* mut;
+
+ public:
+ MutexLocker(Mutex *mu) EXCLUSIVE_LOCK_FUNCTION(mu) : mut(mu) {
+ mu->Lock();
+ }
+ ~MutexLocker() UNLOCK_FUNCTION() {
+ mut->Unlock();
+ }
+ };
+
+ #endif // THREAD_SAFETY_ANALYSIS_MUTEX_H
Added: www-releases/trunk/3.5.1/tools/clang/docs/ThreadSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/ThreadSanitizer.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/ThreadSanitizer.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/ThreadSanitizer.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,139 @@
+ThreadSanitizer
+===============
+
+Introduction
+------------
+
+ThreadSanitizer is a tool that detects data races. It consists of a compiler
+instrumentation module and a run-time library. Typical slowdown introduced by
+ThreadSanitizer is about **5x-15x**. Typical memory overhead introduced by
+ThreadSanitizer is about **5x-10x**.
+
+How to build
+------------
+
+Follow the `Clang build instructions <../get_started.html>`_. CMake build is
+supported.
+
+Supported Platforms
+-------------------
+
+ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.
+
+Usage
+-----
+
+Simply compile and link your program with ``-fsanitize=thread``. To get a
+reasonable performance add ``-O1`` or higher. Use ``-g`` to get file names
+and line numbers in the warning messages.
+
+Example:
+
+.. code-block:: c++
+
+ % cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
+ #include <pthread.h>
+ int Global;
+ void *Thread1(void *x) {
+ Global = 42;
+ return x;
+ }
+ int main() {
+ pthread_t t;
+ pthread_create(&t, NULL, Thread1, NULL);
+ Global = 43;
+ pthread_join(t, NULL);
+ return Global;
+ }
+
+ $ clang -fsanitize=thread -g -O1 tiny_race.c
+
+If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+``addr2line`` process (this will be fixed in future).
+
+.. code-block:: bash
+
+ % ./a.out
+ WARNING: ThreadSanitizer: data race (pid=19219)
+ Write of size 4 at 0x7fcf47b21bc0 by thread T1:
+ #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
+
+ Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+ #0 main tiny_race.c:10 (exe+0x00000000a3b4)
+
+ Thread T1 (running) created at:
+ #0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)
+ #1 main tiny_race.c:9 (exe+0x00000000a3a4)
+
+``__has_feature(thread_sanitizer)``
+------------------------------------
+
+In some cases one may need to execute different code depending on whether
+ThreadSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
+
+.. code-block:: c
+
+ #if defined(__has_feature)
+ # if __has_feature(thread_sanitizer)
+ // code that builds only under ThreadSanitizer
+ # endif
+ #endif
+
+``__attribute__((no_sanitize_thread))``
+-----------------------------------------------
+
+Some code should not be instrumented by ThreadSanitizer.
+One may use the function attribute
+:ref:`no_sanitize_thread <langext-thread_sanitizer>`
+to disable instrumentation of plain (non-atomic) loads/stores in a particular function.
+ThreadSanitizer still instruments such functions to avoid false positives and
+provide meaningful stack traces.
+This attribute may not be
+supported by other compilers, so we suggest to use it together with
+``__has_feature(thread_sanitizer)``.
+
+Blacklist
+---------
+
+ThreadSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports in
+the specified source files or functions. Unlike functions marked with
+:ref:`no_sanitize_thread <langext-thread_sanitizer>` attribute,
+blacklisted functions are not instrumented at all. This can lead to false positives
+due to missed synchronization via atomic operations and missed stack frames in reports.
+
+Limitations
+-----------
+
+* ThreadSanitizer uses more real memory than a native run. At the default
+ settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
+ (less accurate analysis) and 9x (more accurate analysis) overhead are also
+ available.
+* ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+ This means that tools like ``ulimit`` may not work as usually expected.
+* Libc/libstdc++ static linking is not supported.
+* Non-position-independent executables are not supported. Therefore, the
+ ``fsanitize=thread`` flag will cause Clang to act as though the ``-fPIE``
+ flag had been supplied if compiling without ``-fPIC``, and as though the
+ ``-pie`` flag had been supplied if linking an executable.
+
+Current Status
+--------------
+
+ThreadSanitizer is in beta stage. It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet). C++11 threading is
+supported with llvm libc++. The test suite is integrated into CMake build
+and can be run with ``make check-tsan`` command.
+
+We are actively working on enhancing the tool --- stay tuned. Any help,
+especially in the form of minimized standalone tests is more than welcome.
+
+More Information
+----------------
+`http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_.
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/Tooling.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/Tooling.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/Tooling.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/Tooling.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,97 @@
+=================================================
+Choosing the Right Interface for Your Application
+=================================================
+
+Clang provides infrastructure to write tools that need syntactic and semantic
+information about a program. This document will give a short introduction of
+the different ways to write clang tools, and their pros and cons.
+
+LibClang
+--------
+
+`LibClang <http://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high
+level C interface to clang. When in doubt LibClang is probably the interface
+you want to use. Consider the other interfaces only when you have a good
+reason not to use LibClang.
+
+Canonical examples of when to use LibClang:
+
+* Xcode
+* Clang Python Bindings
+
+Use LibClang when you...:
+
+* want to interface with clang from other languages than C++
+* need a stable interface that takes care to be backwards compatible
+* want powerful high-level abstractions, like iterating through an AST with a
+ cursor, and don't want to learn all the nitty gritty details of Clang's AST.
+
+Do not use LibClang when you...:
+
+* want full control over the Clang AST
+
+Clang Plugins
+-------------
+
+:doc:`Clang Plugins <ClangPlugins>` allow you to run additional actions on the
+AST as part of a compilation. Plugins are dynamic libraries that are loaded at
+runtime by the compiler, and they're easy to integrate into your build
+environment.
+
+Canonical examples of when to use Clang Plugins:
+
+* special lint-style warnings or errors for your project
+* creating additional build artifacts from a single compile step
+
+Use Clang Plugins when you...:
+
+* need your tool to rerun if any of the dependencies change
+* want your tool to make or break a build
+* need full control over the Clang AST
+
+Do not use Clang Plugins when you...:
+
+* want to run tools outside of your build environment
+* want full control on how Clang is set up, including mapping of in-memory
+ virtual files
+* need to run over a specific subset of files in your project which is not
+ necessarily related to any changes which would trigger rebuilds
+
+LibTooling
+----------
+
+:doc:`LibTooling <LibTooling>` is a C++ interface aimed at writing standalone
+tools, as well as integrating into services that run clang tools. Canonical
+examples of when to use LibTooling:
+
+* a simple syntax checker
+* refactoring tools
+
+Use LibTooling when you...:
+
+* want to run tools over a single file, or a specific subset of files,
+ independently of the build system
+* want full control over the Clang AST
+* want to share code with Clang Plugins
+
+Do not use LibTooling when you...:
+
+* want to run as part of the build triggered by dependency changes
+* want a stable interface so you don't need to change your code when the AST API
+ changes
+* want high level abstractions like cursors and code completion out of the box
+* do not want to write your tools in C++
+
+:doc:`Clang tools <ClangTools>` are a collection of specific developer tools
+built on top of the LibTooling infrastructure as part of the Clang project.
+They are targeted at automating and improving core development activities of
+C/C++ developers.
+
+Examples of tools we are building or planning as part of the Clang project:
+
+* Syntax checking (:program:`clang-check`)
+* Automatic fixing of compile errors (:program:`clang-fixit`)
+* Automatic code formatting (:program:`clang-format`)
+* Migration tools for new features in new language standards
+* Core refactoring tools
+
Added: www-releases/trunk/3.5.1/tools/clang/docs/UsersManual.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/UsersManual.rst?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/UsersManual.rst (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/UsersManual.rst Tue Jan 13 16:55:20 2015
@@ -0,0 +1,1908 @@
+============================
+Clang Compiler User's Manual
+============================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+The Clang Compiler is an open-source compiler for the C family of
+programming languages, aiming to be the best in class implementation of
+these languages. Clang builds on the LLVM optimizer and code generator,
+allowing it to provide high-quality optimization and code generation
+support for many targets. For more general information, please see the
+`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
+Site <http://llvm.org>`_.
+
+This document describes important notes about using Clang as a compiler
+for an end-user, documenting the supported features, command line
+options, etc. If you are interested in using Clang to build a tool that
+processes code, please see :doc:`InternalsManual`. If you are interested in the
+`Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
+page.
+
+Clang is designed to support the C family of programming languages,
+which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
+:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:
+
+- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+ C99 (+TC1, TC2, TC3).
+- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
+ variants depending on base language.
+- :ref:`C++ Language <cxx>`
+- :ref:`Objective C++ Language <objcxx>`
+
+In addition to these base languages and their dialects, Clang supports a
+broad variety of language extensions, which are documented in the
+corresponding language section. These extensions are provided to be
+compatible with the GCC, Microsoft, and other popular compilers as well
+as to improve functionality through Clang-specific features. The Clang
+driver and language features are intentionally designed to be as
+compatible with the GNU GCC compiler as reasonably possible, easing
+migration from GCC to Clang. In most cases, code "just works".
+Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.
+
+In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the :ref:`Target-Specific Features and
+Limitations <target_features>` section for more details.
+
+The rest of the introduction introduces some basic :ref:`compiler
+terminology <terminology>` that is used throughout this manual and
+contains a basic :ref:`introduction to using Clang <basicusage>` as a
+command line compiler.
+
+.. _terminology:
+
+Terminology
+-----------
+
+Front end, parser, backend, preprocessor, undefined behavior,
+diagnostic, optimizer
+
+.. _basicusage:
+
+Basic Usage
+-----------
+
+Intro to how to use a C compiler for newbies.
+
+compile + link compile then link debug info enabling optimizations
+picking a language to use, defaults to C99 by default. Autosenses based
+on extension. using a makefile
+
+Command Line Options
+====================
+
+This section is generally an index into other sections. It does not go
+into depth on the ones that are covered by other sections. However, the
+first part introduces the language selection and other high level
+options like :option:`-c`, :option:`-g`, etc.
+
+Options to Control Error and Warning Messages
+---------------------------------------------
+
+.. option:: -Werror
+
+ Turn warnings into errors.
+
+.. This is in plain monospaced font because it generates the same label as
+.. -Werror, and Sphinx complains.
+
+``-Werror=foo``
+
+ Turn warning "foo" into an error.
+
+.. option:: -Wno-error=foo
+
+ Turn warning "foo" into an warning even if :option:`-Werror` is specified.
+
+.. option:: -Wfoo
+
+ Enable warning "foo".
+
+.. option:: -Wno-foo
+
+ Disable warning "foo".
+
+.. option:: -w
+
+ Disable all diagnostics.
+
+.. option:: -Weverything
+
+ :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
+
+.. option:: -pedantic
+
+ Warn on language extensions.
+
+.. option:: -pedantic-errors
+
+ Error on language extensions.
+
+.. option:: -Wsystem-headers
+
+ Enable warnings from system headers.
+
+.. option:: -ferror-limit=123
+
+ Stop emitting diagnostics after 123 errors have been produced. The default is
+ 20, and the error limit can be disabled with :option:`-ferror-limit=0`.
+
+.. option:: -ftemplate-backtrace-limit=123
+
+ Only emit up to 123 template instantiation notes within the template
+ instantiation backtrace for a single warning or error. The default is 10, and
+ the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`.
+
+.. _cl_diag_formatting:
+
+Formatting of Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang aims to produce beautiful diagnostics by default, particularly for
+new users that first come to Clang. However, different people have
+different preferences, and sometimes Clang is driven by another program
+that wants to parse simple and consistent output, not a person. For
+these cases, Clang provides a wide range of options to control the exact
+output format of the diagnostics that it generates.
+
+.. _opt_fshow-column:
+
+**-f[no-]show-column**
+ Print column number in diagnostic.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the column number of a diagnostic. For example, when this is
+ enabled, Clang will print something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ When this is disabled, Clang will print "test.c:28: warning..." with
+ no column number.
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+.. _opt_fshow-source-location:
+
+**-f[no-]show-source-location**
+ Print source file/line/column information in diagnostic.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the filename, line number and column number of a diagnostic.
+ For example, when this is enabled, Clang will print something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ When this is disabled, Clang will not print the "test.c:28:8: "
+ part.
+
+.. _opt_fcaret-diagnostics:
+
+**-f[no-]caret-diagnostics**
+ Print source line and ranges from source code in diagnostic.
+ This option, which defaults to on, controls whether or not Clang
+ prints the source line, source ranges, and caret when emitting a
+ diagnostic. For example, when this is enabled, Clang will print
+ something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+**-f[no-]color-diagnostics**
+ This option, which defaults to on when a color-capable terminal is
+ detected, controls whether or not Clang prints diagnostics in color.
+
+ When this option is enabled, Clang will use colors to highlight
+ specific parts of the diagnostic, e.g.,
+
+ .. nasty hack to not lose our dignity
+
+ .. raw:: html
+
+ <pre>
+ <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
+ #endif bad
+ <span style="color:green">^</span>
+ <span style="color:green">//</span>
+ </pre>
+
+ When this is disabled, Clang will just print:
+
+ ::
+
+ test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+**-fansi-escape-codes**
+ Controls whether ANSI escape codes are used instead of the Windows Console
+ API to output colored diagnostics. This option is only used on Windows and
+ defaults to off.
+
+.. option:: -fdiagnostics-format=clang/msvc/vi
+
+ Changes diagnostic output format to better match IDEs and command line tools.
+
+ This option controls the output format of the filename, line number,
+ and column printed in diagnostic messages. The options, and their
+ affect on formatting a simple conversion diagnostic, follow:
+
+ **clang** (default)
+ ::
+
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+
+ **msvc**
+ ::
+
+ t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
+
+ **vi**
+ ::
+
+ t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+
+.. _opt_fdiagnostics-show-option:
+
+**-f[no-]diagnostics-show-option**
+ Enable ``[-Woption]`` information in diagnostic line.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the associated :ref:`warning group <cl_diag_warning_groups>`
+ option name when outputting a warning diagnostic. For example, in
+ this output:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ Passing **-fno-diagnostics-show-option** will prevent Clang from
+ printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
+ the diagnostic. This information tells you the flag needed to enable
+ or disable the diagnostic, either from the command line or through
+ :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
+
+.. _opt_fdiagnostics-show-category:
+
+.. option:: -fdiagnostics-show-category=none/id/name
+
+ Enable printing category information in diagnostic line.
+
+ This option, which defaults to "none", controls whether or not Clang
+ prints the category associated with a diagnostic when emitting it.
+ Each diagnostic may or many not have an associated category, if it
+ has one, it is listed in the diagnostic categorization field of the
+ diagnostic line (in the []'s).
+
+ For example, a format string warning will produce these three
+ renditions based on the setting of this option:
+
+ ::
+
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+
+ This category can be used by clients that want to group diagnostics
+ by category, so it should be a high level category. We want dozens
+ of these, not hundreds or thousands of them.
+
+.. _opt_fdiagnostics-fixit-info:
+
+**-f[no-]diagnostics-fixit-info**
+ Enable "FixIt" information in the diagnostics output.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the information on how to fix a specific diagnostic
+ underneath it when it knows. For example, in this output:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ Passing **-fno-diagnostics-fixit-info** will prevent Clang from
+ printing the "//" line at the end of the message. This information
+ is useful for users who may not understand what is wrong, but can be
+ confusing for machine parsing.
+
+.. _opt_fdiagnostics-print-source-range-info:
+
+**-fdiagnostics-print-source-range-info**
+ Print machine parsable information about source ranges.
+ This option makes Clang print information about source ranges in a machine
+ parsable format after the file/line/column number information. The
+ information is a simple sequence of brace enclosed ranges, where each range
+ lists the start and end line/column locations. For example, in this output:
+
+ ::
+
+ exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+ P = (P-42) + Gamma*4;
+ ~~~~~~ ^ ~~~~~~~
+
+ The {}'s are generated by -fdiagnostics-print-source-range-info.
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+.. option:: -fdiagnostics-parseable-fixits
+
+ Print Fix-Its in a machine parseable form.
+
+ This option makes Clang print available Fix-Its in a machine
+ parseable format at the end of diagnostics. The following example
+ illustrates the format:
+
+ ::
+
+ fix-it:"t.cpp":{7:25-7:29}:"Gamma"
+
+ The range printed is a half-open range, so in this example the
+ characters at column 25 up to but not including column 29 on line 7
+ in t.cpp should be replaced with the string "Gamma". Either the
+ range or the replacement string may be empty (representing strict
+ insertions and strict erasures, respectively). Both the file name
+ and the insertion string escape backslash (as "\\\\"), tabs (as
+ "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
+ non-printable characters (as octal "\\xxx").
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+.. option:: -fno-elide-type
+
+ Turns off elision in template type printing.
+
+ The default for template type printing is to elide as many template
+ arguments as possible, removing those which are the same in both
+ template types, leaving only the differences. Adding this flag will
+ print all the template arguments. If supported by the terminal,
+ highlighting will still appear on differing arguments.
+
+ Default:
+
+ ::
+
+ t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+
+ -fno-elide-type:
+
+ ::
+
+ t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+
+.. option:: -fdiagnostics-show-template-tree
+
+ Template type diffing prints a text tree.
+
+ For diffing large templated types, this option will cause Clang to
+ display the templates as an indented text tree, one argument per
+ line, with differences marked inline. This is compatible with
+ -fno-elide-type.
+
+ Default:
+
+ ::
+
+ t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+
+ With :option:`-fdiagnostics-show-template-tree`:
+
+ ::
+
+ t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+ vector<
+ map<
+ [...],
+ map<
+ [float != double],
+ [...]>>>
+
+.. _cl_diag_warning_groups:
+
+Individual Warning Groups
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO: Generate this from tblgen. Define one anchor per warning group.
+
+.. _opt_wextra-tokens:
+
+.. option:: -Wextra-tokens
+
+ Warn about excess tokens at the end of a preprocessor directive.
+
+ This option, which defaults to on, enables warnings about extra
+ tokens at the end of preprocessor directives. For example:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+
+ These extra tokens are not strictly conforming, and are usually best
+ handled by commenting them out.
+
+.. option:: -Wambiguous-member-template
+
+ Warn about unqualified uses of a member template whose name resolves to
+ another template at the location of the use.
+
+ This option, which defaults to on, enables a warning in the
+ following code:
+
+ ::
+
+ template<typename T> struct set{};
+ template<typename T> struct trait { typedef const T& type; };
+ struct Value {
+ template<typename T> void set(typename trait<T>::type value) {}
+ };
+ void foo() {
+ Value v;
+ v.set<double>(3.2);
+ }
+
+ C++ [basic.lookup.classref] requires this to be an error, but,
+ because it's hard to work around, Clang downgrades it to a warning
+ as an extension.
+
+.. option:: -Wbind-to-temporary-copy
+
+ Warn about an unusable copy constructor when binding a reference to a
+ temporary.
+
+ This option, which defaults to on, enables warnings about binding a
+ reference to a temporary when the temporary doesn't have a usable
+ copy constructor. For example:
+
+ ::
+
+ struct NonCopyable {
+ NonCopyable();
+ private:
+ NonCopyable(const NonCopyable&);
+ };
+ void foo(const NonCopyable&);
+ void bar() {
+ foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
+ }
+
+ ::
+
+ struct NonCopyable2 {
+ NonCopyable2();
+ NonCopyable2(NonCopyable2&);
+ };
+ void foo(const NonCopyable2&);
+ void bar() {
+ foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
+ }
+
+ Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
+ whose instantiation produces a compile error, that error will still
+ be a hard error in C++98 mode even if this warning is turned off.
+
+Options to Control Clang Crash Diagnostics
+------------------------------------------
+
+As unbelievable as it may sound, Clang does crash from time to time.
+Generally, this only occurs to those living on the `bleeding
+edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
+lengths to assist you in filing a bug report. Specifically, Clang
+generates preprocessed source file(s) and associated run script(s) upon
+a crash. These files should be attached to a bug report to ease
+reproducibility of the failure. Below are the command line options to
+control the crash diagnostics.
+
+.. option:: -fno-crash-diagnostics
+
+ Disable auto-generation of preprocessed source files during a clang crash.
+
+The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.
+
+.. _opt_rpass:
+
+Options to Emit Optimization Reports
+------------------------------------
+
+Optimization reports trace, at a high-level, all the major decisions
+done by compiler transformations. For instance, when the inliner
+decides to inline function ``foo()`` into ``bar()``, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.
+
+Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:
+
+1. When the pass makes a transformation (:option:`-Rpass`).
+
+2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
+
+3. When the pass determines whether or not to make a transformation
+ (:option:`-Rpass-analysis`).
+
+NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact
+same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`.
+
+Since there are dozens of passes inside the compiler, each of these flags
+take a regular expression that identifies the name of the pass which should
+emit the associated diagnostic. For example, to get a report from the inliner,
+compile the code with:
+
+.. code-block:: console
+
+ $ clang -O2 -Rpass=inline code.cc -o code
+ code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
+ int bar(int j) { return foo(j, j - 2); }
+ ^
+
+Note that remarks from the inliner are identified with `[-Rpass=inline]`.
+To request a report from every optimization pass, you should use
+:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular
+expression). However, do not expect a report from every transformation
+made by the compiler. Optimization remarks do not really make sense
+outside of the major transformations (e.g., inlining, vectorization,
+loop optimizations) and not every optimization pass supports this
+feature.
+
+Current limitations
+^^^^^^^^^^^^^^^^^^^
+
+1. Optimization remarks that refer to function names will display the
+ mangled name of the function. Since these remarks are emitted by the
+ back end of the compiler, it does not know anything about the input
+ language, nor its mangling rules.
+
+2. Some source locations are not displayed correctly. The front end has
+ a more detailed source location tracking than the locations included
+ in the debug info (e.g., the front end can locate code inside macro
+ expansions). However, the locations used by :option:`-Rpass` are
+ translated from debug annotations. That translation can be lossy,
+ which results in some remarks having no location information.
+
+
+Language and Target-Independent Features
+========================================
+
+Controlling Errors and Warnings
+-------------------------------
+
+Clang provides a number of ways to control which code constructs cause
+it to emit errors and warning messages, and how they are displayed to
+the console.
+
+Controlling How Clang Displays Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:
+
+#. A file/line/column indicator that shows exactly where the diagnostic
+ occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
+ :ref:`-fshow-source-location <opt_fshow-source-location>`].
+#. A categorization of the diagnostic as a note, warning, error, or
+ fatal error.
+#. A text string that describes what the problem is.
+#. An option that indicates how to control the diagnostic (for
+ diagnostics that support it)
+ [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
+#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
+ for clients that want to group diagnostics by class (for diagnostics
+ that support it)
+ [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
+#. The line of source code that the issue occurs on, along with a caret
+ and ranges that indicate the important locations
+ [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
+#. "FixIt" information, which is a concise explanation of how to fix the
+ problem (when Clang is certain it knows)
+ [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
+#. A machine-parsable representation of the ranges involved (off by
+ default)
+ [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
+
+For more information please see :ref:`Formatting of
+Diagnostics <cl_diag_formatting>`.
+
+Diagnostic Mappings
+^^^^^^^^^^^^^^^^^^^
+
+All diagnostics are mapped into one of these 5 classes:
+
+- Ignored
+- Note
+- Remark
+- Warning
+- Error
+- Fatal
+
+.. _diagnostics_categories:
+
+Diagnostic Categories
+^^^^^^^^^^^^^^^^^^^^^
+
+Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.
+
+Categories are not shown by default, but they can be turned on with the
+:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
+When set to "``name``", the category is printed textually in the
+diagnostic output. When it is set to "``id``", a category number is
+printed. The mapping of category names to category id's can be obtained
+by running '``clang --print-diagnostic-categories``'.
+
+Controlling Diagnostics via Command Line Flags
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO: -W flags, -pedantic, etc
+
+.. _pragma_gcc_diagnostic:
+
+Controlling Diagnostics via Pragmas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCC's pragma for
+compatibility with existing source code, as well as several extensions.
+
+The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:
+
+.. code-block:: c
+
+ #pragma GCC diagnostic ignored "-Wall"
+
+In addition to all of the functionality provided by GCC's pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you don't know what warning flags they build with.
+
+In the below example :option:`-Wmultichar` is ignored for only a single line of
+code, after which the diagnostics return to whatever state had previously
+existed.
+
+.. code-block:: c
+
+ #pragma clang diagnostic push
+ #pragma clang diagnostic ignored "-Wmultichar"
+
+ char b = 'df'; // no warning.
+
+ #pragma clang diagnostic pop
+
+The push and pop pragmas will save and restore the full diagnostic state
+of the compiler, regardless of how it was set. That means that it is
+possible to use push and pop around GCC compatible diagnostics and Clang
+will push and pop them appropriately, while GCC will ignore the pushes
+and pops as unknown pragmas. It should be noted that while Clang
+supports the GCC pragma, Clang and GCC do not support the exact same set
+of warnings, so even when using GCC compatible #pragmas there is no
+guarantee that they will have identical behaviour on both compilers.
+
+In addition to controlling warnings and errors generated by the compiler, it is
+possible to generate custom warning and error messages through the following
+pragmas:
+
+.. code-block:: c
+
+ // The following will produce warning messages
+ #pragma message "some diagnostic message"
+ #pragma GCC warning "TODO: replace deprecated feature"
+
+ // The following will produce an error message
+ #pragma GCC error "Not supported"
+
+These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 ``_Pragma`` operator, for example:
+
+.. code-block:: c
+
+ #define STR(X) #X
+ #define DEFER(M,...) M(__VA_ARGS__)
+ #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
+
+ CUSTOM_ERROR("Feature not available");
+
+Controlling Diagnostics in System Headers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by ``-isystem``, but this can be overridden in
+several ways.
+
+The ``system_header`` pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.
+
+.. code-block:: c
+
+ char a = 'xy'; // warning
+
+ #pragma clang system_header
+
+ char b = 'ab'; // no warning
+
+The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a ``#include`` directive
+is found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:
+
+.. code-block:: console
+
+ $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
+ --no-system-header-prefix=x/y/
+
+Here, ``#include "x/a.h"`` is treated as including a system header, even
+if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
+as not including a system header, even if the header is found in
+``bar``.
+
+A ``#include`` directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.
+
+.. _diagnostics_enable_everything:
+
+Enabling All Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the traditional ``-W`` flags, one can enable **all**
+diagnostics by passing :option:`-Weverything`. This works as expected
+with
+:option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
+
+Note that when combined with :option:`-w` (which disables all warnings), that
+flag wins.
+
+Controlling Static Analyzer Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While not strictly part of the compiler, the diagnostics from Clang's
+`static analyzer <http://clang-analyzer.llvm.org>`_ can also be
+influenced by the user via changes to the source code. See the available
+`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
+analyzer's `FAQ
+page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
+information.
+
+.. _usersmanual-precompiled-headers:
+
+Precompiled Headers
+-------------------
+
+`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
+are a general approach employed by many compilers to reduce compilation
+time. The underlying motivation of the approach is that it is common for
+the same (and often large) header files to be included by multiple
+source files. Consequently, compile times can often be greatly improved
+by caching some of the (redundant) work done by a compiler to process
+headers. Precompiled header files, which represent one of many ways to
+implement this optimization, are literally files that represent an
+on-disk cache that contains the vital information necessary to reduce
+some of the work needed to process a corresponding header file. While
+details of precompiled headers vary between compilers, precompiled
+headers have been shown to be highly effective at speeding up program
+compilation on systems with very large system headers (e.g., Mac OS X).
+
+Generating a PCH File
+^^^^^^^^^^^^^^^^^^^^^
+
+To generate a PCH file using Clang, one invokes Clang with the
+:option:`-x <language>-header` option. This mirrors the interface in GCC
+for generating PCH files:
+
+.. code-block:: console
+
+ $ gcc -x c-header test.h -o test.h.gch
+ $ clang -x c-header test.h -o test.h.pch
+
+Using a PCH File
+^^^^^^^^^^^^^^^^
+
+A PCH file can then be used as a prefix header when a :option:`-include`
+option is passed to ``clang``:
+
+.. code-block:: console
+
+ $ clang -include test.h test.c -o test
+
+The ``clang`` driver will first check if a PCH file for ``test.h`` is
+available; if so, the contents of ``test.h`` (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of ``test.h``. This mirrors the behavior
+of GCC.
+
+.. note::
+
+ Clang does *not* automatically use PCH files for headers that are directly
+ included within a source file. For example:
+
+ .. code-block:: console
+
+ $ clang -x c-header test.h -o test.h.pch
+ $ cat test.c
+ #include "test.h"
+ $ clang test.c -o test
+
+ In this example, ``clang`` will not automatically use the PCH file for
+ ``test.h`` since ``test.h`` was included directly in the source file and not
+ specified on the command line using :option:`-include`.
+
+Relocatable PCH Files
+^^^^^^^^^^^^^^^^^^^^^
+
+It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of "relocatable" precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.
+
+To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header ``mylib.h``
+that will be installed into ``/usr/include``, create a subdirectory
+``build/usr/include`` and place the header ``mylib.h`` into that
+subdirectory. If ``mylib.h`` depends on other headers, then they can be
+stored within ``build/usr/include`` in a way that mimics the installed
+location.
+
+Building a relocatable precompiled header requires two additional
+arguments. First, pass the ``--relocatable-pch`` flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+:option:`-isysroot /path/to/build`, which makes all includes for your library
+relative to the build directory. For example:
+
+.. code-block:: console
+
+ # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+
+When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, ``mylib.h``
+can be found in ``/usr/include/mylib.h``. If the headers are installed
+in some other system root, the :option:`-isysroot` option can be used provide
+a different system root from which the headers will be based. For
+example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
+``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
+
+Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed.
+
+Controlling Code Generation
+---------------------------
+
+Clang provides a number of ways to control code generation. The options
+are listed below.
+
+**-f[no-]sanitize=check1,check2,...**
+ Turn on runtime checks for various forms of undefined or suspicious
+ behavior.
+
+ This option controls whether Clang adds runtime checks for various
+ forms of undefined or suspicious behavior, and is disabled by
+ default. If a check fails, a diagnostic message is produced at
+ runtime explaining the problem. The main checks are:
+
+ - .. _opt_fsanitize_address:
+
+ ``-fsanitize=address``:
+ :doc:`AddressSanitizer`, a memory error
+ detector.
+ - ``-fsanitize=integer``: Enables checks for undefined or
+ suspicious integer behavior.
+ - .. _opt_fsanitize_thread:
+
+ ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
+ - .. _opt_fsanitize_memory:
+
+ ``-fsanitize=memory``: :doc:`MemorySanitizer`,
+ an *experimental* detector of uninitialized reads. Not ready for
+ widespread use.
+ - .. _opt_fsanitize_undefined:
+
+ ``-fsanitize=undefined``: Fast and compatible undefined behavior
+ checker. Enables the undefined behavior checks that have small
+ runtime cost and no impact on address space layout or ABI. This
+ includes all of the checks listed below other than
+ ``unsigned-integer-overflow``.
+
+ - ``-fsanitize=undefined-trap``: This includes all sanitizers
+ included by ``-fsanitize=undefined``, except those that require
+ runtime support. This group of sanitizers is intended to be
+ used in conjunction with the ``-fsanitize-undefined-trap-on-error``
+ flag. This includes all of the checks listed below other than
+ ``unsigned-integer-overflow`` and ``vptr``.
+ - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
+ flow analysis.
+
+ The following more fine-grained checks are also available:
+
+ - ``-fsanitize=alignment``: Use of a misaligned pointer or creation
+ of a misaligned reference.
+ - ``-fsanitize=bool``: Load of a ``bool`` value which is neither
+ ``true`` nor ``false``.
+ - ``-fsanitize=bounds``: Out of bounds array indexing, in cases
+ where the array bound can be statically determined.
+ - ``-fsanitize=enum``: Load of a value of an enumerated type which
+ is not in the range of representable values for that enumerated
+ type.
+ - ``-fsanitize=float-cast-overflow``: Conversion to, from, or
+ between floating-point types which would overflow the
+ destination.
+ - ``-fsanitize=float-divide-by-zero``: Floating point division by
+ zero.
+ - ``-fsanitize=function``: Indirect call of a function through a
+ function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
+ - ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
+ - ``-fsanitize=null``: Use of a null pointer or creation of a null
+ reference.
+ - ``-fsanitize=object-size``: An attempt to use bytes which the
+ optimizer can determine are not part of the object being
+ accessed. The sizes of objects are determined using
+ ``__builtin_object_size``, and consequently may be able to detect
+ more problems at higher optimization levels.
+ - ``-fsanitize=return``: In C++, reaching the end of a
+ value-returning function without returning a value.
+ - ``-fsanitize=shift``: Shift operators where the amount shifted is
+ greater or equal to the promoted bit-width of the left hand side
+ or less than zero, or where the left hand side is negative. For a
+ signed left shift, also checks for signed overflow in C, and for
+ unsigned overflow in C++.
+ - ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
+ including all the checks added by ``-ftrapv``, and checking for
+ overflow in signed division (``INT_MIN / -1``).
+ - ``-fsanitize=unreachable``: If control flow reaches
+ ``__builtin_unreachable``.
+ - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
+ overflows.
+ - ``-fsanitize=vla-bound``: A variable-length array whose bound
+ does not evaluate to a positive value.
+ - ``-fsanitize=vptr``: Use of an object whose vptr indicates that
+ it is of the wrong dynamic type, or that its lifetime has not
+ begun or has ended. Incompatible with ``-fno-rtti``.
+
+ You can turn off or modify checks for certain source files, functions
+ or even variables by providing a special file:
+
+ - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
+ sanitizer checks for objects listed in the file. See
+ :doc:`SanitizerSpecialCaseList` for file format description.
+ - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
+ specified earlier in the command line.
+
+ Extra features of MemorySanitizer (require explicit
+ ``-fsanitize=memory``):
+
+ - ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
+ MemorySanitizer. Adds a second section to MemorySanitizer
+ reports pointing to the heap or stack allocation the
+ uninitialized bits came from. Slows down execution by additional
+ 1.5x-2x.
+
+ Possible values for level are 0 (off), 1 (default), 2. Level 2 adds more
+ sections to MemorySanitizer reports describing the order of memory stores
+ the uninitialized value went through. Beware, this mode may use a lot of
+ extra memory.
+
+ Extra features of UndefinedBehaviorSanitizer:
+
+ - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
+ an issue, it will attempt to continue executing the program if there
+ is a reasonable behavior it can give to the faulting operation. This
+ option causes the program to abort instead.
+ - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted
+ rather than calls to runtime libraries when a problem is detected.
+ This option is intended for use in cases where the sanitizer runtime
+ cannot be used (for instance, when building libc or a kernel module).
+ This is only compatible with the sanitizers in the ``undefined-trap``
+ group.
+
+ The ``-fsanitize=`` argument must also be provided when linking, in
+ order to link to the appropriate runtime library. When using
+ ``-fsanitize=vptr`` (or a group that includes it, such as
+ ``-fsanitize=undefined``) with a C++ program, the link must be
+ performed by ``clang++``, not ``clang``, in order to link against the
+ C++-specific parts of the runtime library.
+
+ It is not possible to combine more than one of the ``-fsanitize=address``,
+ ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
+ program. The ``-fsanitize=undefined`` checks can be combined with other
+ sanitizers.
+
+.. option:: -fno-assume-sane-operator-new
+
+ Don't assume that the C++'s new operator is sane.
+
+ This option tells the compiler to do not assume that C++'s global
+ new operator will always return a pointer that does not alias any
+ other pointer when the function returns.
+
+.. option:: -ftrap-function=[name]
+
+ Instruct code generator to emit a function call to the specified
+ function name for ``__builtin_trap()``.
+
+ LLVM code generator translates ``__builtin_trap()`` to a trap
+ instruction if it is supported by the target ISA. Otherwise, the
+ builtin is translated into a call to ``abort``. If this option is
+ set, then the code generator will always lower the builtin to a call
+ to the specified function regardless of whether the target ISA has a
+ trap instruction. This option is useful for environments (e.g.
+ deeply embedded) where a trap cannot be properly handled, or when
+ some custom behavior is desired.
+
+.. option:: -ftls-model=[model]
+
+ Select which TLS model to use.
+
+ Valid values are: ``global-dynamic``, ``local-dynamic``,
+ ``initial-exec`` and ``local-exec``. The default value is
+ ``global-dynamic``. The compiler may use a different model if the
+ selected model is not supported by the target, or if a more
+ efficient model can be used. The TLS model can be overridden per
+ variable using the ``tls_model`` attribute.
+
+.. option:: -mhwdiv=[values]
+
+ Select the ARM modes (arm or thumb) that support hardware division
+ instructions.
+
+ Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
+ This option is used to indicate which mode (arm or thumb) supports
+ hardware division instructions. This only applies to the ARM
+ architecture.
+
+.. option:: -m[no-]crc
+
+ Enable or disable CRC instructions.
+
+ This option is used to indicate whether CRC instructions are to
+ be generated. This only applies to the ARM architecture.
+
+ CRC instructions are enabled by default on ARMv8.
+
+.. option:: -mgeneral-regs-only
+
+ Generate code which only uses the general purpose registers.
+
+ This option restricts the generated code to use general registers
+ only. This only applies to the AArch64 architecture.
+
+
+Profile Guided Optimization
+---------------------------
+
+Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function ``foo`` is called more
+frequently than another function ``bar`` helps the inliner.
+
+Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.
+
+Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.
+
+Using Sampling Profilers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.
+
+Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:
+
+1. Build the code with source line table information. You can use all the
+ usual build flags that you always build your application with. The only
+ requirement is that you add ``-gline-tables-only`` or ``-g`` to the
+ command line. This is important for the profiler to be able to map
+ instructions back to source line locations.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -gline-tables-only code.cc -o code
+
+2. Run the executable under a sampling profiler. The specific profiler
+ you use does not really matter, as long as its output can be converted
+ into the format that the LLVM optimizer understands. Currently, there
+ exists a conversion tool for the Linux Perf profiler
+ (https://perf.wiki.kernel.org/), so these examples assume that you
+ are using Linux Perf to profile your code.
+
+ .. code-block:: console
+
+ $ perf record -b ./code
+
+ Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
+ Record (LBR) to record call chains. While this is not strictly required,
+ it provides better call information, which improves the accuracy of
+ the profile data.
+
+3. Convert the collected profile data to LLVM's sample profile format.
+ This is currently supported via the AutoFDO converter ``create_llvm_prof``.
+ It is available at http://github.com/google/autofdo. Once built and
+ installed, you can convert the ``perf.data`` file to LLVM using
+ the command:
+
+ .. code-block:: console
+
+ $ create_llvm_prof --binary=./code --out=code.prof
+
+ This will read ``perf.data`` and the binary file ``./code`` and emit
+ the profile data in ``code.prof``. Note that if you ran ``perf``
+ without the ``-b`` flag, you need to use ``--use_lbr=false`` when
+ calling ``create_llvm_prof``.
+
+4. Build the code again using the collected profile. This step feeds
+ the profile back to the optimizers. This should result in a binary
+ that executes faster than the original one. Note that you are not
+ required to build the code with the exact same arguments that you
+ used in the first step. The only requirement is that you build the code
+ with ``-gline-tables-only`` and ``-fprofile-sample-use``.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
+
+
+Sample Profile Format
+"""""""""""""""""""""
+
+If you are not using Linux Perf to collect profiles, you will need to
+write a conversion tool from your profiler to LLVM's format. This section
+explains the file format expected by the backend.
+
+Sample profiles are written as ASCII text. The file is divided into sections,
+which correspond to each of the functions executed at runtime. Each
+section has the following format (taken from
+https://github.com/google/autofdo/blob/master/profile_writer.h):
+
+.. code-block:: console
+
+ function1:total_samples:total_head_samples
+ offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
+ offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
+ ...
+ offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
+
+The file may contain blank lines between sections and within a
+section. However, the spacing within a single line is fixed. Additional
+spaces will result in an error while reading the file.
+
+Function names must be mangled in order for the profile loader to
+match them in the current translation unit. The two numbers in the
+function header specify how many total samples were accumulated in the
+function (first number), and the total number of samples accumulated
+in the prologue of the function (second number). This head sample
+count provides an indicator of how frequently the function is invoked.
+
+Each sampled line may contain several items. Some are optional (marked
+below):
+
+a. Source line offset. This number represents the line number
+ in the function where the sample was collected. The line number is
+ always relative to the line where symbol of the function is
+ defined. So, if the function has its header at line 280, the offset
+ 13 is at line 293 in the file.
+
+ Note that this offset should never be a negative number. This could
+ happen in cases like macros. The debug machinery will register the
+ line number at the point of macro expansion. So, if the macro was
+ expanded in a line before the start of the function, the profile
+ converter should emit a 0 as the offset (this means that the optimizers
+ will not be able to associate a meaningful weight to the instructions
+ in the macro).
+
+b. [OPTIONAL] Discriminator. This is used if the sampled program
+ was compiled with DWARF discriminator support
+ (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
+ DWARF discriminators are unsigned integer values that allow the
+ compiler to distinguish between multiple execution paths on the
+ same source line location.
+
+ For example, consider the line of code ``if (cond) foo(); else bar();``.
+ If the predicate ``cond`` is true 80% of the time, then the edge
+ into function ``foo`` should be considered to be taken most of the
+ time. But both calls to ``foo`` and ``bar`` are at the same source
+ line, so a sample count at that line is not sufficient. The
+ compiler needs to know which part of that line is taken more
+ frequently.
+
+ This is what discriminators provide. In this case, the calls to
+ ``foo`` and ``bar`` will be at the same line, but will have
+ different discriminator values. This allows the compiler to correctly
+ set edge weights into ``foo`` and ``bar``.
+
+c. Number of samples. This is an integer quantity representing the
+ number of samples collected by the profiler at this source
+ location.
+
+d. [OPTIONAL] Potential call targets and samples. If present, this
+ line contains a call instruction. This models both direct and
+ number of samples. For example,
+
+ .. code-block:: console
+
+ 130: 7 foo:3 bar:2 baz:7
+
+ The above means that at relative line offset 130 there is a call
+ instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
+ with ``baz()`` being the relatively more frequently called target.
+
+
+Profiling with Instrumentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.
+
+Here are the steps for using profile guided optimization with
+instrumentation:
+
+1. Build an instrumented version of the code by compiling and linking with the
+ ``-fprofile-instr-generate`` option.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -fprofile-instr-generate code.cc -o code
+
+2. Run the instrumented executable with inputs that reflect the typical usage.
+ By default, the profile data will be written to a ``default.profraw`` file
+ in the current directory. You can override that default by setting the
+ ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
+ Any instance of ``%p`` in that file name will be replaced by the process
+ ID, so that you can easily distinguish the profile output from multiple
+ runs.
+
+ .. code-block:: console
+
+ $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
+
+3. Combine profiles from multiple runs and convert the "raw" profile format to
+ the input expected by clang. Use the ``merge`` command of the llvm-profdata
+ tool to do this.
+
+ .. code-block:: console
+
+ $ llvm-profdata merge -output=code.profdata code-*.profraw
+
+ Note that this step is necessary even when there is only one "raw" profile,
+ since the merge operation also changes the file format.
+
+4. Build the code again using the ``-fprofile-instr-use`` option to specify the
+ collected profile data.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
+
+ You can repeat step 4 as often as you like without regenerating the
+ profile. As you make changes to your code, clang may no longer be able to
+ use the profile data. It will warn you when this happens.
+
+
+Controlling Size of Debug Information
+-------------------------------------
+
+Debug info kind generated by Clang can be set by one of the flags listed
+below. If multiple flags are present, the last one is used.
+
+.. option:: -g0
+
+ Don't generate any debug info (default).
+
+.. option:: -gline-tables-only
+
+ Generate line number tables only.
+
+ This kind of debug info allows to obtain stack traces with function names,
+ file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
+ doesn't contain any other data (e.g. description of local variables or
+ function parameters).
+
+.. option:: -fstandalone-debug
+
+ Clang supports a number of optimizations to reduce the size of debug
+ information in the binary. They work based on the assumption that
+ the debug type information can be spread out over multiple
+ compilation units. For instance, Clang will not emit type
+ definitions for types that are not needed by a module and could be
+ replaced with a forward declaration. Further, Clang will only emit
+ type info for a dynamic C++ class in the module that contains the
+ vtable for the class.
+
+ The **-fstandalone-debug** option turns off these optimizations.
+ This is useful when working with 3rd-party libraries that don't come
+ with debug information. Note that Clang will never emit type
+ information for types that are not referenced at all by the program.
+
+.. option:: -fno-standalone-debug
+
+ On Darwin **-fstandalone-debug** is enabled by default. The
+ **-fno-standalone-debug** option can be used to get to turn on the
+ vtable-based optimization described above.
+
+.. option:: -g
+
+ Generate complete debug info.
+
+Comment Parsing Options
+-----------------------
+
+Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes. By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with ``//`` and
+``/*``.
+
+.. option:: -Wdocumentation
+
+ Emit warnings about use of documentation comments. This warning group is off
+ by default.
+
+ This includes checking that ``\param`` commands name parameters that actually
+ present in the function signature, checking that ``\returns`` is used only on
+ functions that actually return a value etc.
+
+.. option:: -Wno-documentation-unknown-command
+
+ Don't warn when encountering an unknown Doxygen command.
+
+.. option:: -fparse-all-comments
+
+ Parse all comments as documentation comments (including ordinary comments
+ starting with ``//`` and ``/*``).
+
+.. option:: -fcomment-block-commands=[commands]
+
+ Define custom documentation commands as block commands. This allows Clang to
+ construct the correct AST for these custom commands, and silences warnings
+ about unknown commands. Several commands must be separated by a comma
+ *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
+ custom commands ``\foo`` and ``\bar``.
+
+ It is also possible to use ``-fcomment-block-commands`` several times; e.g.
+ ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
+ as above.
+
+.. _c:
+
+C Language Features
+===================
+
+The support for standard C in clang is feature-complete except for the
+C99 floating-point pragmas.
+
+Extensions supported by clang
+-----------------------------
+
+See :doc:`LanguageExtensions`.
+
+Differences between various standard modes
+------------------------------------------
+
+clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
+various aliases for those modes. If no -std option is specified, clang
+defaults to gnu99 mode.
+
+Differences between all ``c*`` and ``gnu*`` modes:
+
+- ``c*`` modes define "``__STRICT_ANSI__``".
+- Target-specific defines not prefixed by underscores, like "linux",
+ are defined in ``gnu*`` modes.
+- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
+ the -trigraphs option.
+- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
+ the variants "``__asm__``" and "``__typeof__``" are recognized in all
+ modes.
+- The Apple "blocks" extension is recognized by default in ``gnu*`` modes
+ on some platforms; it can be enabled in any mode with the "-fblocks"
+ option.
+- Arrays that are VLA's according to the standard, but which can be
+ constant folded by the frontend are treated as fixed size arrays.
+ This occurs for things like "int X[(1, 2)];", which is technically a
+ VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
+
+Differences between ``*89`` and ``*99`` modes:
+
+- The ``*99`` modes default to implementing "inline" as specified in C99,
+ while the ``*89`` modes implement the GNU version. This can be
+ overridden for individual functions with the ``__gnu_inline__``
+ attribute.
+- Digraphs are not recognized in c89 mode.
+- The scope of names defined inside a "for", "if", "switch", "while",
+ or "do" statement is different. (example: "``if ((struct x {int
+ x;}*)0) {}``".)
+- ``__STDC_VERSION__`` is not defined in ``*89`` modes.
+- "inline" is not recognized as a keyword in c89 mode.
+- "restrict" is not recognized as a keyword in ``*89`` modes.
+- Commas are allowed in integer constant expressions in ``*99`` modes.
+- Arrays which are not lvalues are not implicitly promoted to pointers
+ in ``*89`` modes.
+- Some warnings are different.
+
+c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
+
+GCC extensions not implemented yet
+----------------------------------
+
+clang tries to be compatible with gcc as much as possible, but some gcc
+extensions are not implemented yet:
+
+- clang does not support #pragma weak (`bug
+ 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
+ described in the bug, this is likely to be implemented at some point,
+ at least partially.
+- clang does not support decimal floating point types (``_Decimal32`` and
+ friends) or fixed-point types (``_Fract`` and friends); nobody has
+ expressed interest in these features yet, so it's hard to say when
+ they will be implemented.
+- clang does not support nested functions; this is a complex feature
+ which is infrequently used, so it is unlikely to be implemented
+ anytime soon. In C++11 it can be emulated by assigning lambda
+ functions to local variables, e.g:
+
+ .. code-block:: cpp
+
+ auto const local_function = [&](int parameter) {
+ // Do something
+ };
+ ...
+ local_function(1);
+
+- clang does not support global register variables; this is unlikely to
+ be implemented soon because it requires additional LLVM backend
+ support.
+- clang does not support static initialization of flexible array
+ members. This appears to be a rarely used extension, but could be
+ implemented pending user demand.
+- clang does not support
+ ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
+ used rarely, but in some potentially interesting places, like the
+ glibc headers, so it may be implemented pending user demand. Note
+ that because clang pretends to be like GCC 4.2, and this extension
+ was introduced in 4.3, the glibc headers will not try to use this
+ extension with clang at the moment.
+- clang does not support the gcc extension for forward-declaring
+ function parameters; this has not shown up in any real-world code
+ yet, though, so it might never be implemented.
+
+This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
+list does not include bugs in mostly-implemented features; please see
+the `bug
+tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
+for known existing bugs (FIXME: Is there a section for bug-reporting
+guidelines somewhere?).
+
+Intentionally unsupported GCC extensions
+----------------------------------------
+
+- clang does not support the gcc extension that allows variable-length
+ arrays in structures. This is for a few reasons: one, it is tricky to
+ implement, two, the extension is completely undocumented, and three,
+ the extension appears to be rarely used. Note that clang *does*
+ support flexible array members (arrays with a zero or unspecified
+ size at the end of a structure).
+- clang does not have an equivalent to gcc's "fold"; this means that
+ clang doesn't accept some constructs gcc might accept in contexts
+ where a constant expression is required, like "x-x" where x is a
+ variable.
+- clang does not support ``__builtin_apply`` and friends; this extension
+ is extremely obscure and difficult to implement reliably.
+
+.. _c_ms:
+
+Microsoft extensions
+--------------------
+
+clang has some experimental support for extensions from Microsoft Visual
+C++; to enable it, use the ``-fms-extensions`` command-line option. This is
+the default for Windows targets. Note that the support is incomplete.
+Some constructs such as ``dllexport`` on classes are ignored with a warning,
+and others such as `Microsoft IDL annotations
+<http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently
+ignored.
+
+clang has a ``-fms-compatibility`` flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. For example, it
+allows `unqualified lookup of dependent base class members
+<http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
+a common compatibility issue with clang. This flag is enabled by default
+for Windows targets.
+
+``-fdelayed-template-parsing`` lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.
+
+- clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
+ 1700 which is the same as Visual C/C++ 2012. Any number is supported
+ and can greatly affect what Windows SDK and c++stdlib headers clang
+ can compile.
+- clang does not support the Microsoft extension where anonymous record
+ members can be declared using user defined typedefs.
+- clang supports the Microsoft ``#pragma pack`` feature for controlling
+ record layout. GCC also contains support for this feature, however
+ where MSVC and GCC are incompatible clang follows the MSVC
+ definition.
+- clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
+ automatically linking against the specified library. Currently this feature
+ only works with the Visual C++ linker.
+- clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
+ for adding linker flags to COFF object files. The user is responsible for
+ ensuring that the linker understands the flags.
+- clang defaults to C++11 for Windows targets.
+
+.. _cxx:
+
+C++ Language Features
+=====================
+
+clang fully implements all of standard C++98 except for exported
+templates (which were removed in C++11), and all of standard C++11
+and the current draft standard for C++1y.
+
+Controlling implementation limits
+---------------------------------
+
+.. option:: -fbracket-depth=N
+
+ Sets the limit for nested parentheses, brackets, and braces to N. The
+ default is 256.
+
+.. option:: -fconstexpr-depth=N
+
+ Sets the limit for recursive constexpr function invocations to N. The
+ default is 512.
+
+.. option:: -ftemplate-depth=N
+
+ Sets the limit for recursively nested template instantiations to N. The
+ default is 256.
+
+.. option:: -foperator-arrow-depth=N
+
+ Sets the limit for iterative calls to 'operator->' functions to N. The
+ default is 256.
+
+.. _objc:
+
+Objective-C Language Features
+=============================
+
+.. _objcxx:
+
+Objective-C++ Language Features
+===============================
+
+
+.. _target_features:
+
+Target-Specific Features and Limitations
+========================================
+
+CPU Architectures Features and Limitations
+------------------------------------------
+
+X86
+^^^
+
+The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.
+
+On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
+
+For the X86 target, clang supports the :option:`-m16` command line
+argument which enables 16-bit code output. This is broadly similar to
+using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.
+
+ARM
+^^^
+
+The support for ARM (specifically ARMv6 and ARMv7) is considered stable
+on Darwin (iOS): it has been tested to correctly compile many large C,
+C++, Objective-C, and Objective-C++ codebases. Clang only supports a
+limited number of ARM architectures. It does not yet fully support
+ARMv5, for example.
+
+PowerPC
+^^^^^^^
+
+The support for PowerPC (especially PowerPC64) is considered stable
+on Linux and FreeBSD: it has been tested to correctly compile many
+large C and C++ codebases. PowerPC (32bit) is still missing certain
+features (e.g. PIC code on ELF platforms).
+
+Other platforms
+^^^^^^^^^^^^^^^
+
+clang currently contains some support for other architectures (e.g. Sparc);
+however, significant pieces of code generation are still missing, and they
+haven't undergone significant testing.
+
+clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.
+
+Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.
+
+Operating System Features and Limitations
+-----------------------------------------
+
+Darwin (Mac OS X)
+^^^^^^^^^^^^^^^^^
+
+Thread Sanitizer is not supported.
+
+Windows
+^^^^^^^
+
+Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
+platforms.
+
+See also :ref:`Microsoft Extensions <c_ms>`.
+
+Cygwin
+""""""
+
+Clang works on Cygwin-1.7.
+
+MinGW32
+"""""""
+
+Clang works on some mingw32 distributions. Clang assumes directories as
+below;
+
+- ``C:/mingw/include``
+- ``C:/mingw/lib``
+- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
+
+On MSYS, a few tests might fail.
+
+MinGW-w64
+"""""""""
+
+For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
+assumes as below;
+
+- ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)``
+- ``some_directory/bin/gcc.exe``
+- ``some_directory/bin/clang.exe``
+- ``some_directory/bin/clang++.exe``
+- ``some_directory/bin/../include/c++/GCC_version``
+- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
+- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
+- ``some_directory/bin/../include/c++/GCC_version/backward``
+- ``some_directory/bin/../x86_64-w64-mingw32/include``
+- ``some_directory/bin/../i686-w64-mingw32/include``
+- ``some_directory/bin/../include``
+
+This directory layout is standard for any toolchain you will find on the
+official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
+
+Clang expects the GCC executable "gcc.exe" compiled for
+``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
+
+`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
+``x86_64-w64-mingw32``.
+
+.. _clang-cl:
+
+clang-cl
+========
+
+clang-cl is an alternative command-line interface to Clang driver, designed for
+compatibility with the Visual C++ compiler, cl.exe.
+
+To enable clang-cl to find system headers, libraries, and the linker when run
+from the command-line, it should be executed inside a Visual Studio Native Tools
+Command Prompt or a regular Command Prompt where the environment has been set
+up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
+
+clang-cl can also be used from inside Visual Studio by using an LLVM Platform
+Toolset.
+
+Command-Line Options
+--------------------
+
+To be compatible with cl.exe, clang-cl supports most of the same command-line
+options. Those options can start with either ``/`` or ``-``. It also supports
+some of Clang's core options, such as the ``-W`` options.
+
+Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:
+
+ ::
+
+ clang-cl.exe: warning: argument unused during compilation: '/Zi'
+
+To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
+
+Options that are not known to clang-cl will cause errors. If they are spelled with a
+leading ``/``, they will be mistaken for a filename:
+
+ ::
+
+ clang-cl.exe: error: no such file or directory: '/foobar'
+
+Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
+for any valid cl.exe flags that clang-cl does not understand.
+
+Execute ``clang-cl /?`` to see a list of supported options:
+
+ ::
+
+ CL.EXE COMPATIBILITY OPTIONS:
+ /? Display available options
+ /arch:<value> Set architecture for code generation
+ /C Don't discard comments when preprocessing
+ /c Compile only
+ /D <macro[=value]> Define macro
+ /EH<value> Exception handling model
+ /EP Disable linemarker output and preprocess to stdout
+ /E Preprocess to stdout
+ /fallback Fall back to cl.exe if clang-cl fails to compile
+ /FA Output assembly code file during compilation
+ /Fa<file or directory> Output assembly code to this file during compilation
+ /Fe<file or directory> Set output executable file or directory (ends in / or \)
+ /FI <value> Include file before parsing
+ /Fi<file> Set preprocess output file name
+ /Fo<file or directory> Set output object file, or directory (ends in / or \)
+ /GF- Disable string pooling
+ /GR- Disable emission of RTTI data
+ /GR Enable emission of RTTI data
+ /Gw- Don't put each data item in its own section
+ /Gw Put each data item in its own section
+ /Gy- Don't put each function in its own section
+ /Gy Put each function in its own section
+ /help Display available options
+ /I <dir> Add directory to include search path
+ /J Make char type unsigned
+ /LDd Create debug DLL
+ /LD Create DLL
+ /link <options> Forward options to the linker
+ /MDd Use DLL debug run-time
+ /MD Use DLL run-time
+ /MTd Use static debug run-time
+ /MT Use static run-time
+ /Ob0 Disable inlining
+ /Od Disable optimization
+ /Oi- Disable use of builtin functions
+ /Oi Enable use of builtin functions
+ /Os Optimize for size
+ /Ot Optimize for speed
+ /Ox Maximum optimization
+ /Oy- Disable frame pointer omission
+ /Oy Enable frame pointer omission
+ /O<n> Optimization level
+ /P Preprocess to file
+ /showIncludes Print info about included files to stderr
+ /TC Treat all source files as C
+ /Tc <filename> Specify a C source file
+ /TP Treat all source files as C++
+ /Tp <filename> Specify a C++ source file
+ /U <macro> Undefine macro
+ /vd<value> Control vtordisp placement
+ /vmb Use a best-case representation method for member pointers
+ /vmg Use a most-general representation for member pointers
+ /vmm Set the default most-general representation to multiple inheritance
+ /vms Set the default most-general representation to single inheritance
+ /vmv Set the default most-general representation to virtual inheritance
+ /W0 Disable all warnings
+ /W1 Enable -Wall
+ /W2 Enable -Wall
+ /W3 Enable -Wall
+ /W4 Enable -Wall
+ /Wall Enable -Wall
+ /WX- Do not treat warnings as errors
+ /WX Treat warnings as errors
+ /w Disable all warnings
+ /Zi Enable debug information
+ /Zs Syntax-check only
+
+ OPTIONS:
+ -### Print (but do not run) the commands to run for this compilation
+ -fms-compatibility-version=<value>
+ Dot-separated value representing the Microsoft compiler version
+ number to report in _MSC_VER (0 = don't define it (default))
+ -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't
+ define it (default))
+ -fsanitize-blacklist=<value>
+ Path to blacklist file for sanitizers
+ -fsanitize=<check> Enable runtime instrumentation for bug detection: address (memory
+ errors) | thread (race detection) | undefined (miscellaneous
+ undefined behavior)
+ -mllvm <value> Additional arguments to forward to LLVM's option processing
+ -Qunused-arguments Don't emit warning for unused driver arguments
+ --target=<value> Generate code for the given target
+ -v Show commands to run and use verbose output
+ -W<warning> Enable the specified warning
+ -Xclang <arg> Pass <arg> to the clang compiler
+
+The /fallback Option
+^^^^^^^^^^^^^^^^^^^^
+
+When clang-cl is run with the ``/fallback`` option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.
+
+This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AddressSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AddressSanitizer.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AddressSanitizer.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AttributeReference.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AttributeReference.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AttributeReference.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AutomaticReferenceCounting.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AutomaticReferenceCounting.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/AutomaticReferenceCounting.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Block-ABI-Apple.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Block-ABI-Apple.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Block-ABI-Apple.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/BlockLanguageSpec.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/BlockLanguageSpec.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/BlockLanguageSpec.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangCheck.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangCheck.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangCheck.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormat.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormat.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormat.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormatStyleOptions.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormatStyleOptions.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangFormatStyleOptions.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangPlugins.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangPlugins.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangPlugins.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangTools.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangTools.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ClangTools.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/CrossCompilation.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/CrossCompilation.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/CrossCompilation.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizer.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizer.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizerDesign.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizerDesign.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DataFlowSanitizerDesign.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DriverInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DriverInternals.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/DriverInternals.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ExternalClangExamples.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ExternalClangExamples.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ExternalClangExamples.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/FAQ.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/FAQ.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/FAQ.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/HowToSetupToolingForLLVM.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/HowToSetupToolingForLLVM.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/HowToSetupToolingForLLVM.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/InternalsManual.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/InternalsManual.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/InternalsManual.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/IntroductionToTheClangAST.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/IntroductionToTheClangAST.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/IntroductionToTheClangAST.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/JSONCompilationDatabase.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/JSONCompilationDatabase.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/JSONCompilationDatabase.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LanguageExtensions.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LanguageExtensions.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LanguageExtensions.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LeakSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LeakSanitizer.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LeakSanitizer.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchers.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchers.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchers.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchersTutorial.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchersTutorial.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibASTMatchersTutorial.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibFormat.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibFormat.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibFormat.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibTooling.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibTooling.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/LibTooling.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MSVCCompatibility.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MSVCCompatibility.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MSVCCompatibility.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MemorySanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MemorySanitizer.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/MemorySanitizer.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Modules.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Modules.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Modules.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ObjectiveCLiterals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ObjectiveCLiterals.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ObjectiveCLiterals.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PCHInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PCHInternals.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PCHInternals.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PTHInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PTHInternals.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/PTHInternals.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/RAVFrontendAction.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/RAVFrontendAction.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/RAVFrontendAction.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ReleaseNotes.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ReleaseNotes.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ReleaseNotes.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/SanitizerSpecialCaseList.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/SanitizerSpecialCaseList.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/SanitizerSpecialCaseList.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSafetyAnalysis.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSafetyAnalysis.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSafetyAnalysis.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSanitizer.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/ThreadSanitizer.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Tooling.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Tooling.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/Tooling.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/UsersManual.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/UsersManual.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/UsersManual.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/environment.pickle
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/environment.pickle?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/environment.pickle
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/index.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/index.doctree?rev=225843&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.5.1/tools/clang/docs/_build/doctrees/index.doctree
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/.buildinfo
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/.buildinfo?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/.buildinfo (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/.buildinfo Tue Jan 13 16:55:20 2015
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e9f0b394d7750c784acf90ac53b5a1c3
+tags: fbb0d17656682115ca4d033fb2f83ba1
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AddressSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AddressSanitizer.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AddressSanitizer.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AddressSanitizer.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,282 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>AddressSanitizer — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="next" title="ThreadSanitizer" href="ThreadSanitizer.html" />
+ <link rel="prev" title="Thread Safety Analysis" href="ThreadSafetyAnalysis.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>AddressSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThreadSanitizer.html">ThreadSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="addresssanitizer">
+<h1>AddressSanitizer<a class="headerlink" href="#addresssanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#has-feature-address-sanitizer" id="id4"><tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-address" id="id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt></a></li>
+<li><a class="reference internal" href="#initialization-order-checking" id="id6">Initialization order checking</a></li>
+<li><a class="reference internal" href="#blacklist" id="id7">Blacklist</a></li>
+<li><a class="reference internal" href="#memory-leak-detection" id="id8">Memory leak detection</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id9">Supported Platforms</a></li>
+<li><a class="reference internal" href="#limitations" id="id10">Limitations</a></li>
+<li><a class="reference internal" href="#current-status" id="id11">Current Status</a></li>
+<li><a class="reference internal" href="#more-information" id="id12">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is a fast memory error detector. It consists of a compiler
+instrumentation module and a run-time library. The tool can detect the
+following types of bugs:</p>
+<ul class="simple">
+<li>Out-of-bounds accesses to heap, stack and globals</li>
+<li>Use-after-free</li>
+<li>Use-after-return (to some extent)</li>
+<li>Double-free, invalid free</li>
+<li>Memory leaks (experimental)</li>
+</ul>
+<p>Typical slowdown introduced by AddressSanitizer is <strong>2x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Follow the <a class="reference external" href="../get_started.html">clang build instructions</a>. CMake build is
+supported.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt> flag. The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use <tt class="docutils literal"><span class="pre">clang</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) for the final link step. When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+<tt class="docutils literal"><span class="pre">-Wl,-z,defs</span></tt> may cause link errors (don’t use it with AddressSanitizer). To
+get a reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher. To get nicer stack traces
+in error messages add <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt>. To get perfect stack traces
+you may need to disable inlining (just use <tt class="docutils literal"><span class="pre">-O1</span></tt>) and tail call elimination
+(<tt class="docutils literal"><span class="pre">-fno-optimize-sibling-calls</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat example_UseAfterFree.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go"> int *array = new int[100];</span>
+<span class="go"> delete [] array;</span>
+<span class="go"> return array[argc]; // BOOM</span>
+<span class="go">}</span>
+
+<span class="gp">#</span> Compile and link
+<span class="gp">%</span> clang -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer example_UseAfterFree.cc
+</pre></div>
+</div>
+<p>or:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Compile
+<span class="gp">%</span> clang -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+<span class="gp">#</span> Link
+<span class="gp">%</span> clang -g -fsanitize<span class="o">=</span>address example_UseAfterFree.o
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. To make AddressSanitizer symbolize its output
+you need to set the <tt class="docutils literal"><span class="pre">ASAN_SYMBOLIZER_PATH</span></tt> environment variable to point to
+the <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary (or make sure <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> is in your
+<tt class="docutils literal"><span class="pre">$PATH</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_SYMBOLIZER_PATH</span><span class="o">=</span>/usr/local/bin/llvm-symbolizer ./a.out
+<span class="go">==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8</span>
+<span class="go">READ of size 4 at 0x7f7ddab8c084 thread T0</span>
+<span class="go"> #0 0x403c8c in main example_UseAfterFree.cc:4</span>
+<span class="go"> #1 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)</span>
+<span class="go">freed by thread T0 here:</span>
+<span class="go"> #0 0x404704 in operator delete[](void*) ??:0</span>
+<span class="go"> #1 0x403c53 in main example_UseAfterFree.cc:4</span>
+<span class="go"> #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">previously allocated by thread T0 here:</span>
+<span class="go"> #0 0x404544 in operator new[](unsigned long) ??:0</span>
+<span class="go"> #1 0x403c43 in main example_UseAfterFree.cc:2</span>
+<span class="go"> #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">==9442== ABORTING</span>
+</pre></div>
+</div>
+<p>If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=symbolize=0</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">symbolize</span><span class="o">=</span>0 ./a.out 2> log
+<span class="gp">%</span> projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+<span class="go">==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8</span>
+<span class="go">READ of size 4 at 0x7f7ddab8c084 thread T0</span>
+<span class="go"> #0 0x403c8c in main example_UseAfterFree.cc:4</span>
+<span class="go"> #1 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">...</span>
+</pre></div>
+</div>
+<p>Note that on OS X you may need to run <tt class="docutils literal"><span class="pre">dsymutil</span></tt> on your binary to have the
+file:line info in the AddressSanitizer reports.</p>
+<p>AddressSanitizer exits on the first detected error. This is by design.
+One reason: it makes the generated code smaller and faster (both by
+~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
+it is often the case that users treat Valgrind warnings as false
+positives (which they are not) and don’t fix them.</p>
+<div class="section" id="has-feature-address-sanitizer">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a><a class="headerlink" href="#has-feature-address-sanitizer" title="Permalink to this headline">¶</a></h3>
+<p>In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp"># if __has_feature(address_sanitizer)</span>
+<span class="c1">// code that builds only under AddressSanitizer</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-address">
+<h3><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-address" title="Permalink to this headline">¶</a></h3>
+<p>Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute
+<a class="reference internal" href="AttributeReference.html#langext-address-sanitizer"><em>no_sanitize_address</em></a>
+(or a deprecated synonym <cite>no_address_safety_analysis</cite>)
+to disable instrumentation of a particular function. This attribute may not be
+supported by other compilers, so we suggest to use it together with
+<tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="initialization-order-checking">
+<h3><a class="toc-backref" href="#id6">Initialization order checking</a><a class="headerlink" href="#initialization-order-checking" title="Permalink to this headline">¶</a></h3>
+<p>AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+<tt class="docutils literal"><span class="pre">ASAN_OPTIONS=check_initialization_order=1</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h3><a class="toc-backref" href="#id7">Blacklist</a><a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h3>
+<p>AddressSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces <tt class="docutils literal"><span class="pre">global</span></tt> and <tt class="docutils literal"><span class="pre">type</span></tt> entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).</p>
+<p>You may use an <tt class="docutils literal"><span class="pre">init</span></tt> category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Suppress error reports for code in a file or in a function:</span>
+src:bad_file.cpp
+<span class="c"># Ignore all functions with names containing MyFooBar:</span>
+fun:*MyFooBar*
+<span class="c"># Disable out-of-bound checks for global:</span>
+global:bad_array
+<span class="c"># Disable out-of-bound checks for global instances of a given class ...</span>
+<span class="nb">type</span>:class.Namespace::BadClassName
+<span class="c"># ... or a given struct. Use wildcard to deal with anonymous namespace.</span>
+<span class="nb">type</span>:struct.Namespace2::*::BadStructName
+<span class="c"># Disable initialization-order checks for globals:</span>
+global:bad_init_global<span class="o">=</span>init
+<span class="nb">type</span>:*BadInitClassSubstring*<span class="o">=</span>init
+src:bad/init/files/*<span class="o">=</span>init
+</pre></div>
+</div>
+</div>
+<div class="section" id="memory-leak-detection">
+<h3><a class="toc-backref" href="#id8">Memory leak detection</a><a class="headerlink" href="#memory-leak-detection" title="Permalink to this headline">¶</a></h3>
+<p>For the experimental memory leak detector in AddressSanitizer, see
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>.</p>
+</div>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id9">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is supported on</p>
+<ul class="simple">
+<li>Linux i386/x86_64 (tested on Ubuntu 12.04);</li>
+<li>MacOS 10.6 - 10.9 (i386/x86_64).</li>
+<li>Android ARM</li>
+</ul>
+<p>Ports to various other platforms are in progress.</p>
+</div>
+<div class="section" id="limitations">
+<h2><a class="toc-backref" href="#id10">Limitations</a><a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>AddressSanitizer uses more real memory than a native run. Exact overhead
+depends on the allocations sizes. The smaller the allocations you make the
+bigger the overhead is.</li>
+<li>AddressSanitizer uses more stack memory. We have seen up to 3x increase.</li>
+<li>On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+virtual address space. This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as
+usually expected.</li>
+<li>Static linking is not supported.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id11">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>AddressSanitizer is fully functional on supported platforms starting from LLVM
+3.1. The test suite is integrated into CMake build and can be run with <tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">check-asan</span></tt> command.</p>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id12">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThreadSanitizer.html">ThreadSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AttributeReference.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AttributeReference.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AttributeReference.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AttributeReference.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,1759 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Attributes in Clang — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="next" title="Cross-compilation using Clang" href="CrossCompilation.html" />
+ <link rel="prev" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>Attributes in Clang</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CrossCompilation.html">Cross-compilation using Clang</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="attributes-in-clang">
+<h1>Attributes in Clang<a class="headerlink" href="#attributes-in-clang" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#function-attributes" id="id3">Function Attributes</a><ul>
+<li><a class="reference internal" href="#interrupt" id="id4">interrupt</a></li>
+<li><a class="reference internal" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" id="id5">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a></li>
+<li><a class="reference internal" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" id="id6">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a></li>
+<li><a class="reference internal" href="#availability" id="id7">availability</a></li>
+<li><a class="reference internal" href="#noreturn" id="id8">_Noreturn</a></li>
+<li><a class="reference internal" href="#id1" id="id9">noreturn</a></li>
+<li><a class="reference internal" href="#carries-dependency" id="id10">carries_dependency</a></li>
+<li><a class="reference internal" href="#enable-if" id="id11">enable_if</a></li>
+<li><a class="reference internal" href="#flatten-gnu-flatten" id="id12">flatten (gnu::flatten)</a></li>
+<li><a class="reference internal" href="#format-gnu-format" id="id13">format (gnu::format)</a></li>
+<li><a class="reference internal" href="#noduplicate-clang-noduplicate" id="id14">noduplicate (clang::noduplicate)</a></li>
+<li><a class="reference internal" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" id="id15">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a></li>
+<li><a class="reference internal" href="#no-sanitize-memory" id="id16">no_sanitize_memory</a></li>
+<li><a class="reference internal" href="#no-sanitize-thread" id="id17">no_sanitize_thread</a></li>
+<li><a class="reference internal" href="#no-split-stack-gnu-no-split-stack" id="id18">no_split_stack (gnu::no_split_stack)</a></li>
+<li><a class="reference internal" href="#objc-method-family" id="id19">objc_method_family</a></li>
+<li><a class="reference internal" href="#objc-requires-super" id="id20">objc_requires_super</a></li>
+<li><a class="reference internal" href="#optnone-clang-optnone" id="id21">optnone (clang::optnone)</a></li>
+<li><a class="reference internal" href="#overloadable" id="id22">overloadable</a></li>
+<li><a class="reference internal" href="#pcs-gnu-pcs" id="id23">pcs (gnu::pcs)</a></li>
+<li><a class="reference internal" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" id="id24">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a></li>
+<li><a class="reference internal" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" id="id25">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#variable-attributes" id="id26">Variable Attributes</a><ul>
+<li><a class="reference internal" href="#section-gnu-section-declspec-allocate" id="id27">section (gnu::section, __declspec(allocate))</a></li>
+<li><a class="reference internal" href="#tls-model-gnu-tls-model" id="id28">tls_model (gnu::tls_model)</a></li>
+<li><a class="reference internal" href="#thread" id="id29">thread</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-attributes" id="id30">Type Attributes</a><ul>
+<li><a class="reference internal" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" id="id31">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#statement-attributes" id="id32">Statement Attributes</a><ul>
+<li><a class="reference internal" href="#fallthrough-clang-fallthrough" id="id33">fallthrough (clang::fallthrough)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#consumed-annotation-checking" id="id34">Consumed Annotation Checking</a><ul>
+<li><a class="reference internal" href="#callable-when" id="id35">callable_when</a></li>
+<li><a class="reference internal" href="#consumable" id="id36">consumable</a></li>
+<li><a class="reference internal" href="#param-typestate" id="id37">param_typestate</a></li>
+<li><a class="reference internal" href="#return-typestate" id="id38">return_typestate</a></li>
+<li><a class="reference internal" href="#set-typestate" id="id39">set_typestate</a></li>
+<li><a class="reference internal" href="#test-typestate" id="id40">test_typestate</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-safety-checking" id="id41">Type Safety Checking</a><ul>
+<li><a class="reference internal" href="#argument-with-type-tag" id="id42">argument_with_type_tag</a></li>
+<li><a class="reference internal" href="#pointer-with-type-tag" id="id43">pointer_with_type_tag</a></li>
+<li><a class="reference internal" href="#type-tag-for-datatype" id="id44">type_tag_for_datatype</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This page lists the attributes currently supported by Clang.</p>
+</div>
+<div class="section" id="function-attributes">
+<h2><a class="toc-backref" href="#id3">Function Attributes</a><a class="headerlink" href="#function-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="interrupt">
+<h3><a class="toc-backref" href="#id4">interrupt</a><a class="headerlink" href="#interrupt" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt("TYPE")))</span></tt> attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.</p>
+<p>The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: “IRQ”,
+“FIQ”, “SWI”, “ABORT”, “UNDEF”.</p>
+<p>The semantics are as follows:</p>
+<ul>
+<li><p class="first">If the function is AAPCS, Clang instructs the backend to realign the stack to
+8 bytes on entry. This is a general requirement of the AAPCS at public
+interfaces, but may not hold when an exception is taken. Doing this allows
+other AAPCS functions to be called.</p>
+</li>
+<li><p class="first">If the CPU is M-class this is all that needs to be done since the architecture
+itself is designed in such a way that functions obeying the normal AAPCS ABI
+constraints are valid exception handlers.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the prologue and epilogue are modified to save all
+non-banked registers that are used, so that upon return the user-mode state
+will not be corrupted. Note that to avoid unnecessary overhead, only
+general-purpose (integer) registers are saved in this way. If VFP operations
+are needed, that state must be saved manually.</p>
+<p>Specifically, interrupt kinds other than “FIQ” will save all core registers
+except “lr” and “sp”. “FIQ” interrupts will save r0-r7.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the return instruction is changed to one of the
+canonical sequences permitted by the architecture for exception return. Where
+possible the function itself will make the necessary “lr” adjustments so that
+the “preferred return address” is selected.</p>
+<p>Unfortunately the compiler is unable to make this guarantee for an “UNDEF”
+handler, where the offset from “lr” to the preferred return address depends on
+the execution state of the code which generated the exception. In this case
+a sequence equivalent to “movs pc, lr” will be used.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id5">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a><a class="headerlink" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as acquiring a capability.</p>
+</div>
+<div class="section" id="assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability">
+<h3><a class="toc-backref" href="#id6">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a><a class="headerlink" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.</p>
+</div>
+<div class="section" id="availability">
+<h3><a class="toc-backref" href="#id7">availability</a><a class="headerlink" href="#availability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">availability</span></tt> attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function <tt class="docutils literal"><span class="pre">f</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">,</span><span class="n">deprecated</span><span class="o">=</span><span class="mf">10.6</span><span class="p">,</span><span class="n">obsoleted</span><span class="o">=</span><span class="mf">10.7</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>The availability attribute states that <tt class="docutils literal"><span class="pre">f</span></tt> was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
+is used by Clang to determine when it is safe to use <tt class="docutils literal"><span class="pre">f</span></tt>: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to <tt class="docutils literal"><span class="pre">f()</span></tt>
+succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because <tt class="docutils literal"><span class="pre">f()</span></tt> is no longer available.</p>
+<p>The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration’s lifetime (in any order) along with additional information. Those
+clauses can be:</p>
+<dl class="docutils">
+<dt>introduced=<em>version</em></dt>
+<dd>The first version in which this declaration was introduced.</dd>
+<dt>deprecated=<em>version</em></dt>
+<dd>The first version in which this declaration was deprecated, meaning that
+users should migrate away from this API.</dd>
+<dt>obsoleted=<em>version</em></dt>
+<dd>The first version in which this declaration was obsoleted, meaning that it
+was removed completely and can no longer be used.</dd>
+<dt>unavailable</dt>
+<dd>This declaration is never available on this platform.</dd>
+<dt>message=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will provide when emitting a warning or
+error about use of a deprecated or obsoleted declaration. Useful to direct
+users to replacement APIs.</dd>
+</dl>
+<p>Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored. If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored. Supported platforms
+are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ios</span></tt></dt>
+<dd>Apple’s iOS operating system. The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mios-version-min=*version*</span></tt> or <tt class="docutils literal"><span class="pre">-miphoneos-version-min=*version*</span></tt>
+command-line arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">macosx</span></tt></dt>
+<dd>Apple’s Mac OS X operating system. The minimum deployment target is
+specified by the <tt class="docutils literal"><span class="pre">-mmacosx-version-min=*version*</span></tt> command-line argument.</dd>
+</dl>
+<p>A declaration can be used even when deploying back to a platform version prior
+to when the declaration was introduced. When this happens, the declaration is
+<a class="reference external" href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly linked</a>,
+as if the <tt class="docutils literal"><span class="pre">weak_import</span></tt> attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.</p>
+<p>If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span> <span class="c1">// okay, matches</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">ios</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">4.0</span><span class="p">)));</span> <span class="c1">// okay, adds a new platform</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> <span class="c1">// okay, inherits both macosx and ios availability from above.</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: mismatch</span>
+</pre></div>
+</div>
+<p>When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">A</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method2</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">@end</span>
+
+<span class="k">@interface</span> <span class="nc">B</span> : <span class="nc">A</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.3</span><span class="p">)));</span> <span class="c1">// okay: method moved into base class later</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macosx</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: this method was available via the base class in 10.4</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="noreturn">
+<h3><a class="toc-backref" href="#id8">_Noreturn</a><a class="headerlink" href="#noreturn" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id9">noreturn</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="carries-dependency">
+<h3><a class="toc-backref" href="#id10">carries_dependency</a><a class="headerlink" href="#carries-dependency" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">carries_dependency</span></tt> attribute specifies dependency propagation into and
+out of functions.</p>
+<p>When specified on a function or Objective-C method, the <tt class="docutils literal"><span class="pre">carries_dependency</span></tt>
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.</p>
+<p>Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.</p>
+</div>
+<div class="section" id="enable-if">
+<h3><a class="toc-backref" href="#id11">enable_if</a><a class="headerlink" href="#enable-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some features of this attribute are experimental. The meaning of
+multiple enable_if attributes on a single declaration is subject to change in
+a future version of clang. Also, the ABI is not standardized and the name
+mangling may change in future versions. To avoid that, use asm labels.</p>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">enable_if</span></tt> attribute can be placed on function declarations to control
+which overload is selected based on the values of the function’s arguments.
+When combined with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, this feature is also
+available in C.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">c</span> <span class="o"><=</span> <span class="o">-</span><span class="mi">1</span> <span class="o">||</span> <span class="n">c</span> <span class="o">></span> <span class="mi">255</span><span class="p">,</span> <span class="s">"chosen when 'c' is out of range"</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">unavailable</span><span class="p">(</span><span class="s">"'c' must have the value of an unsigned char or EOF"</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">char</span> <span class="n">c</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
+ <span class="n">isdigit</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">);</span> <span class="c1">// results in a compile-time error.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.</p>
+<p>The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the callsite. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.</p>
+<p>Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">always_inline</span><span class="p">))</span>
+<span class="k">static</span> <span class="kr">inline</span> <span class="kt">size_t</span> <span class="n">strnlen</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">maxlen</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span>
+ <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="o">-</span><span class="mi">1</span><span class="p">))),</span>
+ <span class="s">"chosen when the buffer size is known but 'maxlen' is not"</span><span class="p">)))</span>
+<span class="p">{</span>
+ <span class="k">return</span> <span class="n">strnlen_chk</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">,</span> <span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #2</span>
+
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span> <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">j</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">)));</span> <span class="c1">// #2</span>
+</pre></div>
+</div>
+<p>In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(enable_if)</span></tt>.</p>
+</div>
+<div class="section" id="flatten-gnu-flatten">
+<h3><a class="toc-backref" href="#id12">flatten (gnu::flatten)</a><a class="headerlink" href="#flatten-gnu-flatten" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">flatten</span></tt> attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the <tt class="docutils literal"><span class="pre">noinline</span></tt> attribute.</p>
+</div>
+<div class="section" id="format-gnu-format">
+<h3><a class="toc-backref" href="#id13">format (gnu::format)</a><a class="headerlink" href="#format-gnu-format" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">format</span></tt> attribute, which indicates that the function
+accepts a <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">scanf</span></tt>-like format string and corresponding
+arguments or a <tt class="docutils literal"><span class="pre">va_list</span></tt> that contains these arguments.</p>
+<p>Please see <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC documentation about format attribute</a> to find details
+about attribute syntax.</p>
+<p>Clang implements two kinds of checks with this attribute.</p>
+<ol class="arabic">
+<li><p class="first">Clang checks that the function with the <tt class="docutils literal"><span class="pre">format</span></tt> attribute is called with
+a format string that uses format specifiers that are allowed, and that
+arguments match the format string. This is the <tt class="docutils literal"><span class="pre">-Wformat</span></tt> warning, it is
+on by default.</p>
+</li>
+<li><p class="first">Clang checks that the format string argument is a literal string. This is
+the <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning, it is off by default.</p>
+<p>Clang implements this mostly the same way as GCC, but there is a difference
+for functions that accept a <tt class="docutils literal"><span class="pre">va_list</span></tt> argument (for example, <tt class="docutils literal"><span class="pre">vprintf</span></tt>).
+GCC does not emit <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning for calls to such
+fuctions. Clang does not warn if the format string comes from a function
+parameter, where the function is annotated with a compatible attribute,
+otherwise it warns. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__scanf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+ <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+ <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+ <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning: format string is not a string literal</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case we warn because <tt class="docutils literal"><span class="pre">s</span></tt> contains a format string for a
+<tt class="docutils literal"><span class="pre">scanf</span></tt>-like function, but it is passed to a <tt class="docutils literal"><span class="pre">printf</span></tt>-like function.</p>
+<p>If the attribute is removed, clang still warns, because the format string is
+not a string literal.</p>
+<p>Another example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__printf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+ <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+ <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+ <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case Clang does not warn because the format string <tt class="docutils literal"><span class="pre">s</span></tt> and
+the corresponding arguments are annotated. If the arguments are
+incorrect, the caller of <tt class="docutils literal"><span class="pre">foo</span></tt> will receive a warning.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="noduplicate-clang-noduplicate">
+<h3><a class="toc-backref" href="#id14">noduplicate (clang::noduplicate)</a><a class="headerlink" href="#noduplicate-clang-noduplicate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">noduplicate</span></tt> attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL “barrier” function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+“nodupfunc” in the code below avoids that:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">nodupfunc</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">noduplicate</span><span class="p">));</span>
+<span class="c1">// Setting it as a C++11 attribute is also valid</span>
+<span class="c1">// void nodupfunc() [[clang::noduplicate]];</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+<span class="kt">void</span> <span class="nf">bar</span><span class="p">();</span>
+
+<span class="n">nodupfunc</span><span class="p">();</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>gets possibly modified by some optimizations into code similar to this:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">nodupfunc</span><span class="p">();</span>
+ <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">nodupfunc</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>where the call to “nodupfunc” is duplicated and sunk into the two branches
+of the condition.</p>
+</div>
+<div class="section" id="no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address">
+<h3><a class="toc-backref" href="#id15">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a><a class="headerlink" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-address-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt> on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.</p>
+</div>
+<div class="section" id="no-sanitize-memory">
+<h3><a class="toc-backref" href="#id16">no_sanitize_memory</a><a class="headerlink" href="#no-sanitize-memory" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-memory-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_memory))</span></tt> on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.</p>
+</div>
+<div class="section" id="no-sanitize-thread">
+<h3><a class="toc-backref" href="#id17">no_sanitize_thread</a><a class="headerlink" href="#no-sanitize-thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-thread-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_thread))</span></tt> on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.</p>
+</div>
+<div class="section" id="no-split-stack-gnu-no-split-stack">
+<h3><a class="toc-backref" href="#id18">no_split_stack (gnu::no_split_stack)</a><a class="headerlink" href="#no-split-stack-gnu-no-split-stack" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">no_split_stack</span></tt> attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if <tt class="docutils literal"><span class="pre">-fsplit-stack</span></tt>
+is not specified.</p>
+</div>
+<div class="section" id="objc-method-family">
+<h3><a class="toc-backref" href="#id19">objc_method_family</a><a class="headerlink" href="#objc-method-family" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the “method family”
+that a method belongs to.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(X)))</span></tt>, where <tt class="docutils literal"><span class="pre">X</span></tt> is one of
+<tt class="docutils literal"><span class="pre">none</span></tt>, <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>. This
+attribute can only be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">initMyStringValue</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_method_family</span><span class="p">(</span><span class="n">none</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>,
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>, etc).</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+</div>
+<div class="section" id="objc-requires-super">
+<h3><a class="toc-backref" href="#id20">objc_requires_super</a><a class="headerlink" href="#objc-requires-super" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a “call to <tt class="docutils literal"><span class="pre">super</span></tt>” in the overriding
+method in the subclass.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_requires_super))</span></tt>. This attribute can only
+be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_requires_super</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+<tt class="docutils literal"><span class="pre">-dealloc</span></tt> where the call must appear at the end). It checks only that it
+exists.</p>
+<p>Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro <tt class="docutils literal"><span class="pre">NS_REQUIRES_SUPER</span></tt> that provides syntactic sugar for this
+attribute:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">NS_REQUIRES_SUPER</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This macro is conditionally defined depending on the compiler’s support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.</p>
+<p>Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="nl">warning:</span> <span class="n">method</span> <span class="n">possibly</span> <span class="n">missing</span> <span class="n">a</span> <span class="p">[</span><span class="n">super</span> <span class="n">AnnotMeth</span><span class="p">]</span> <span class="n">call</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">AnnotMeth</span><span class="p">{};</span>
+ <span class="o">^</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="optnone-clang-optnone">
+<h3><a class="toc-backref" href="#id21">optnone (clang::optnone)</a><a class="headerlink" href="#optnone-clang-optnone" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">optnone</span></tt> attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole. This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization. Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.</p>
+<p>This attribute is incompatible with the <tt class="docutils literal"><span class="pre">always_inline</span></tt> attribute.</p>
+</div>
+<div class="section" id="overloadable">
+<h3><a class="toc-backref" href="#id22">overloadable</a><a class="headerlink" href="#overloadable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. For example, one
+might provide several overloaded versions of a <tt class="docutils literal"><span class="pre">tgsin</span></tt> function that invokes
+the appropriate standard function computing the sine of a value with <tt class="docutils literal"><span class="pre">float</span></tt>,
+<tt class="docutils literal"><span class="pre">double</span></tt>, or <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> precision:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="kt">float</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinf</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">long</span> <span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">long</span> <span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinl</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Given these declarations, one can call <tt class="docutils literal"><span class="pre">tgsin</span></tt> with a <tt class="docutils literal"><span class="pre">float</span></tt> value to
+receive a <tt class="docutils literal"><span class="pre">float</span></tt> result, with a <tt class="docutils literal"><span class="pre">double</span></tt> to receive a <tt class="docutils literal"><span class="pre">double</span></tt> result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:</p>
+<ul class="simple">
+<li>Conversion from <tt class="docutils literal"><span class="pre">float</span></tt> or <tt class="docutils literal"><span class="pre">double</span></tt> to <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> is ranked as a
+floating-point promotion (per C99) rather than as a floating-point conversion
+(as in C++).</li>
+<li>A conversion from a pointer of type <tt class="docutils literal"><span class="pre">T*</span></tt> to a pointer of type <tt class="docutils literal"><span class="pre">U*</span></tt> is
+considered a pointer conversion (with conversion rank) if <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> are
+compatible types.</li>
+<li>A conversion from type <tt class="docutils literal"><span class="pre">T</span></tt> to a value of type <tt class="docutils literal"><span class="pre">U</span></tt> is permitted if <tt class="docutils literal"><span class="pre">T</span></tt>
+and <tt class="docutils literal"><span class="pre">U</span></tt> are compatible types. This conversion is given “conversion” rank.</li>
+</ul>
+<p>The declaration of <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions is restricted to function
+declarations and definitions. Most importantly, if any function with a given
+name is given the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+<tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. This rule even applies to redeclarations of
+functions whose original declaration had the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, e.g.,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">float</span> <span class="nf">f</span><span class="p">(</span><span class="kt">float</span><span class="p">);</span> <span class="c1">// error: declaration of "f" must have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="c1">// error: redeclaration of "g" must also have the "overloadable" attribute</span>
+</pre></div>
+</div>
+<p>Functions marked <tt class="docutils literal"><span class="pre">overloadable</span></tt> must have prototypes. Therefore, the
+following code is ill-formed:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">h</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: h does not have a prototype</span>
+</pre></div>
+</div>
+<p>However, <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the <tt class="docutils literal"><span class="pre">unavailable</span></tt> attribute:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">honeypot</span><span class="p">(...)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">,</span> <span class="n">unavailable</span><span class="p">));</span> <span class="c1">// calling me is an error</span>
+</pre></div>
+</div>
+<p>Functions declared with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+<tt class="docutils literal"><span class="pre">tgsin</span></tt> functions in our motivating example get the mangled names
+<tt class="docutils literal"><span class="pre">_Z5tgsinf</span></tt>, <tt class="docutils literal"><span class="pre">_Z5tgsind</span></tt>, and <tt class="docutils literal"><span class="pre">_Z5tgsine</span></tt>, respectively. There are two
+caveats to this use of name mangling:</p>
+<ul class="simple">
+<li>Future versions of Clang may change the name mangling of functions overloaded
+in C, so you should not depend on an specific mangling. To be completely
+safe, we strongly urge the use of <tt class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></tt> with <tt class="docutils literal"><span class="pre">overloadable</span></tt>
+functions.</li>
+<li>The <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute has almost no meaning when used in C++,
+because names will already be mangled and functions are already overloadable.
+However, when an <tt class="docutils literal"><span class="pre">overloadable</span></tt> function occurs within an <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt>
+linkage specification, it’s name <em>will</em> be mangled in the same way as it
+would in C.</li>
+</ul>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_extension(attribute_overloadable)</span></tt>.</p>
+</div>
+<div class="section" id="pcs-gnu-pcs">
+<h3><a class="toc-backref" href="#id23">pcs (gnu::pcs)</a><a class="headerlink" href="#pcs-gnu-pcs" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On ARM targets, this can attribute can be used to select calling conventions,
+similar to <tt class="docutils literal"><span class="pre">stdcall</span></tt> on x86. Valid parameter values are “aapcs” and
+“aapcs-vfp”.</p>
+</div>
+<div class="section" id="release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability">
+<h3><a class="toc-backref" href="#id24">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a><a class="headerlink" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as releasing a capability.</p>
+</div>
+<div class="section" id="try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id25">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a><a class="headerlink" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).</p>
+</div>
+</div>
+<div class="section" id="variable-attributes">
+<h2><a class="toc-backref" href="#id26">Variable Attributes</a><a class="headerlink" href="#variable-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="section-gnu-section-declspec-allocate">
+<h3><a class="toc-backref" href="#id27">section (gnu::section, __declspec(allocate))</a><a class="headerlink" href="#section-gnu-section-declspec-allocate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">section</span></tt> attribute allows you to specify a specific section a
+global variable or function should be in after translation.</p>
+</div>
+<div class="section" id="tls-model-gnu-tls-model">
+<h3><a class="toc-backref" href="#id28">tls_model (gnu::tls_model)</a><a class="headerlink" href="#tls-model-gnu-tls-model" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:</p>
+<ul class="simple">
+<li>global-dynamic</li>
+<li>local-dynamic</li>
+<li>initial-exec</li>
+<li>local-exec</li>
+</ul>
+<p>TLS models are mutually exclusive.</p>
+</div>
+<div class="section" id="thread">
+<h3><a class="toc-backref" href="#id29">thread</a><a class="headerlink" href="#thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> attribute declares a variable with thread local
+storage. It is available under the <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> flag for MSVC
+compatibility. Documentation for the Visual C++ attribute is available on <a class="reference external" href="http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx">MSDN</a>.</p>
+<p>In Clang, <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> is generally equivalent in functionality to the
+GNU <tt class="docutils literal"><span class="pre">__thread</span></tt> keyword. The variable must not have a destructor and must have
+a constant initializer, if any. The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.</p>
+</div>
+</div>
+<div class="section" id="type-attributes">
+<h2><a class="toc-backref" href="#id30">Type Attributes</a><a class="headerlink" href="#type-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="single-inhertiance-multiple-inheritance-virtual-inheritance">
+<h3><a class="toc-backref" href="#id31">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a><a class="headerlink" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>This collection of keywords is enabled under <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> and controls
+the pointer-to-member representation used on <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets.</p>
+<p>The <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.</p>
+<p>However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.</p>
+<p>These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.</p>
+<p>This family of keywords belong between the <tt class="docutils literal"><span class="pre">class-key</span></tt> and <tt class="docutils literal"><span class="pre">class-name</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">S</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+<p>This keyword can be applied to class templates but only has an effect when used
+on full specializations:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="p">,</span> <span class="k">typename</span> <span class="n">U</span><span class="o">></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on primary template</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="o">></span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on partial specialization</span>
+<span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">float</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Note that choosing an inheritance model less general than strictly necessary is
+an error:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">S</span><span class="p">;</span> <span class="c1">// error: inheritance model does not match definition</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="statement-attributes">
+<h2><a class="toc-backref" href="#id32">Statement Attributes</a><a class="headerlink" href="#statement-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="fallthrough-clang-fallthrough">
+<h3><a class="toc-backref" href="#id33">fallthrough (clang::fallthrough)</a><a class="headerlink" href="#fallthrough-clang-fallthrough" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">clang::fallthrough</span></tt> attribute is used along with the
+<tt class="docutils literal"><span class="pre">-Wimplicit-fallthrough</span></tt> argument to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn’t change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like <tt class="docutils literal"><span class="pre">break;</span></tt>, so it can be placed in most places
+where <tt class="docutils literal"><span class="pre">break;</span></tt> can, but only if there are no statements on the execution path
+between it and the next switch label.</p>
+<p>Here is an example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// compile with -Wimplicit-fallthrough</span>
+<span class="k">switch</span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="mi">22</span>:
+<span class="k">case</span> <span class="mi">33</span>: <span class="c1">// no warning: no statements between case labels</span>
+ <span class="n">f</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">44</span>: <span class="c1">// warning: unannotated fall-through</span>
+ <span class="n">g</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+<span class="k">case</span> <span class="mi">55</span>: <span class="c1">// no warning</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">h</span><span class="p">();</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="n">i</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+ <span class="p">}</span>
+<span class="k">case</span> <span class="mi">66</span>: <span class="c1">// no warning</span>
+ <span class="n">p</span><span class="p">();</span>
+ <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span> <span class="c1">// warning: fallthrough annotation does not</span>
+ <span class="c1">// directly precede case label</span>
+ <span class="n">q</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">77</span>: <span class="c1">// warning: unannotated fall-through</span>
+ <span class="n">r</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="consumed-annotation-checking">
+<h2><a class="toc-backref" href="#id34">Consumed Annotation Checking</a><a class="headerlink" href="#consumed-annotation-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although <strong>the implementation
+for these annotations is currently in development and are subject to change.</strong></p>
+<div class="section" id="callable-when">
+<h3><a class="toc-backref" href="#id35">callable_when</a><a class="headerlink" href="#callable-when" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((callable_when(...)))</span></tt> to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:</p>
+<p><tt class="docutils literal"><span class="pre">__attribute__((callable_when("unconsumed",</span> <span class="pre">"unknown")))</span></tt></p>
+</div>
+<div class="section" id="consumable">
+<h3><a class="toc-backref" href="#id36">consumable</a><a class="headerlink" href="#consumable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Each <tt class="docutils literal"><span class="pre">class</span></tt> that uses any of the typestate annotations must first be marked
+using the <tt class="docutils literal"><span class="pre">consumable</span></tt> attribute. Failure to do so will result in a warning.</p>
+<p>This attribute accepts a single parameter that must be one of the following:
+<tt class="docutils literal"><span class="pre">unknown</span></tt>, <tt class="docutils literal"><span class="pre">consumed</span></tt>, or <tt class="docutils literal"><span class="pre">unconsumed</span></tt>.</p>
+</div>
+<div class="section" id="param-typestate">
+<h3><a class="toc-backref" href="#id37">param_typestate</a><a class="headerlink" href="#param-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn’t in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function’s body.</p>
+</div>
+<div class="section" id="return-typestate">
+<h3><a class="toc-backref" href="#id38">return_typestate</a><a class="headerlink" href="#return-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">return_typestate</span></tt> attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function’s body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.</p>
+<p>When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function’s body is checked to ensure that
+the parameter is in the expected state before returning.</p>
+</div>
+<div class="section" id="set-typestate">
+<h3><a class="toc-backref" href="#id39">set_typestate</a><a class="headerlink" href="#set-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Annotate methods that transition an object into a new state with
+<tt class="docutils literal"><span class="pre">__attribute__((set_typestate(new_state)))</span></tt>. The new new state must be
+unconsumed, consumed, or unknown.</p>
+</div>
+<div class="section" id="test-typestate">
+<h3><a class="toc-backref" href="#id40">test_typestate</a><a class="headerlink" href="#test-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((test_typestate(tested_state)))</span></tt> to indicate that a method
+returns true if the object is in the specified state..</p>
+</div>
+</div>
+<div class="section" id="type-safety-checking">
+<h2><a class="toc-backref" href="#id41">Type Safety Checking</a><a class="headerlink" href="#type-safety-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes to enable checking type safety properties
+that can’t be enforced by the C type system. Use cases include:</p>
+<ul class="simple">
+<li>MPI library implementations, where these attributes enable checking that
+the buffer type matches the passed <tt class="docutils literal"><span class="pre">MPI_Datatype</span></tt>;</li>
+<li>for HDF5 library there is a similar use case to MPI;</li>
+<li>checking types of variadic functions’ arguments for functions like
+<tt class="docutils literal"><span class="pre">fcntl()</span></tt> and <tt class="docutils literal"><span class="pre">ioctl()</span></tt>.</li>
+</ul>
+<p>You can detect support for these attributes with <tt class="docutils literal"><span class="pre">__has_attribute()</span></tt>. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(__has_attribute)</span>
+<span class="cp"># if __has_attribute(argument_with_type_tag) && \</span>
+<span class="cp"> __has_attribute(pointer_with_type_tag) && \</span>
+<span class="cp"> __has_attribute(type_tag_for_datatype)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))</span>
+<span class="cm">/* ... other macros ... */</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if !defined(ATTR_MPI_PWT)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx)</span>
+<span class="cp">#endif</span>
+
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+ <span class="n">ATTR_MPI_PWT</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="section" id="argument-with-type-tag">
+<h3><a class="toc-backref" href="#id42">argument_with_type_tag</a><a class="headerlink" href="#argument-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((argument_with_type_tag(arg_kind,</span> <span class="pre">arg_idx,</span>
+<span class="pre">type_tag_idx)))</span></tt> on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+<tt class="docutils literal"><span class="pre">arg_kind</span></tt> is an identifier that should be used when annotating all
+applicable type tags.</p>
+<p>This attribute is primarily useful for checking arguments of variadic functions
+(<tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt> can be used in most non-variadic cases).</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">fcntl</span><span class="p">(</span><span class="kt">int</span> <span class="n">fd</span><span class="p">,</span> <span class="kt">int</span> <span class="n">cmd</span><span class="p">,</span> <span class="p">...)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">argument_with_type_tag</span><span class="p">(</span><span class="n">fcntl</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="p">));</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-with-type-tag">
+<h3><a class="toc-backref" href="#id43">pointer_with_type_tag</a><a class="headerlink" href="#pointer-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((pointer_with_type_tag(ptr_kind,</span> <span class="pre">ptr_idx,</span> <span class="pre">type_tag_idx)))</span></tt>
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="type-tag-for-datatype">
+<h3><a class="toc-backref" href="#id44">type_tag_for_datatype</a><a class="headerlink" href="#type-tag-for-datatype" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports annotating type tags of two forms.</p>
+<ul>
+<li><p class="first"><strong>Type tag that is an expression containing a reference to some declared
+identifier.</strong> Use <tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> on a
+declaration with that identifier:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_int</span>
+ <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">));</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><strong>Type tag that is an integral literal.</strong> Introduce a <tt class="docutils literal"><span class="pre">static</span> <span class="pre">const</span></tt>
+variable with a corresponding initializer value and attach
+<tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> on that declaration,
+for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define MPI_INT ((MPI_Datatype) 42)</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MPI_Datatype</span> <span class="n">mpi_datatype_int</span>
+ <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">))</span> <span class="o">=</span> <span class="mi">42</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<p>The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag. There are two supported flags:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">layout_compatible</span></tt> will cause types to be compared according to
+layout-compatibility rules (C++11 [class.mem] p 17, 18). This is
+implemented to support annotating types like <tt class="docutils literal"><span class="pre">MPI_DOUBLE_INT</span></tt>.</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">struct</span> <span class="n">internal_mpi_double_int</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">d</span><span class="p">;</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_double_int</span>
+ <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span> <span class="k">struct</span> <span class="n">internal_mpi_double_int</span><span class="p">,</span> <span class="n">layout_compatible</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// no warning</span>
+
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">}</span>
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="o">*</span><span class="n">buffer2</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// warning: actual buffer element</span>
+ <span class="c1">// type 'struct my_int_pair'</span>
+ <span class="c1">// doesn't match specified MPI_Datatype</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">must_be_null</span></tt> specifies that the expression should be a null pointer
+constant, for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_null</span>
+ <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span> <span class="kt">void</span><span class="p">,</span> <span class="n">must_be_null</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)</span>
+
+<span class="cm">/* In user code */</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DATATYPE_NULL</span> <span class="cm">/*, ... */</span><span class="p">);</span> <span class="c1">// warning: MPI_DATATYPE_NULL</span>
+ <span class="c1">// was specified but buffer</span>
+ <span class="c1">// is not a null pointer</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CrossCompilation.html">Cross-compilation using Clang</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AutomaticReferenceCounting.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AutomaticReferenceCounting.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AutomaticReferenceCounting.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/AutomaticReferenceCounting.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,2083 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Objective-C Automatic Reference Counting (ARC) — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="next" title="Attributes in Clang" href="AttributeReference.html" />
+ <link rel="prev" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>Objective-C Automatic Reference Counting (ARC)</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AttributeReference.html">Attributes in Clang</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <style>
+ .arc-term { font-style: italic; font-weight: bold; }
+ .revision { font-style: italic; }
+ .when-revised { font-weight: bold; font-style: normal; }
+
+ /*
+ * Automatic numbering is described in this article:
+ * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+ */
+ /*
+ * Automatic numbering for the TOC.
+ * This is wrong from the semantics point of view, since it is an ordered
+ * list, but uses "ul" tag.
+ */
+ div#contents.contents.local ul {
+ counter-reset: toc-section;
+ list-style-type: none;
+ }
+ div#contents.contents.local ul li {
+ counter-increment: toc-section;
+ background: none; // Remove bullets
+ }
+ div#contents.contents.local ul li a.reference:before {
+ content: counters(toc-section, ".") " ";
+ }
+
+ /* Automatic numbering for the body. */
+ body {
+ counter-reset: section subsection subsubsection;
+ }
+ .section h2 {
+ counter-reset: subsection subsubsection;
+ counter-increment: section;
+ }
+ .section h2 a.toc-backref:before {
+ content: counter(section) " ";
+ }
+ .section h3 {
+ counter-reset: subsubsection;
+ counter-increment: subsection;
+ }
+ .section h3 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) " ";
+ }
+ .section h4 {
+ counter-increment: subsubsection;
+ }
+ .section h4 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+ }
+</style><div class="section" id="objective-c-automatic-reference-counting-arc">
+<h1>Objective-C Automatic Reference Counting (ARC)<a class="headerlink" href="#objective-c-automatic-reference-counting-arc" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#about-this-document" id="id4">About this document</a><ul>
+<li><a class="reference internal" href="#purpose" id="id5">Purpose</a></li>
+<li><a class="reference internal" href="#background" id="id6">Background</a></li>
+<li><a class="reference internal" href="#evolution" id="id7">Evolution</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#general" id="id8">General</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers" id="id9">Retainable object pointers</a><ul>
+<li><a class="reference internal" href="#retain-count-semantics" id="id10">Retain count semantics</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers-as-operands-and-arguments" id="id11">Retainable object pointers as operands and arguments</a><ul>
+<li><a class="reference internal" href="#consumed-parameters" id="id12">Consumed parameters</a></li>
+<li><a class="reference internal" href="#retained-return-values" id="id13">Retained return values</a></li>
+<li><a class="reference internal" href="#unretained-return-values" id="id14">Unretained return values</a></li>
+<li><a class="reference internal" href="#bridged-casts" id="id15">Bridged casts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#restrictions" id="id16">Restrictions</a><ul>
+<li><a class="reference internal" href="#conversion-of-retainable-object-pointers" id="id17">Conversion of retainable object pointers</a></li>
+<li><a class="reference internal" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" id="id18">Conversion to retainable object pointer type of expressions with known semantics</a></li>
+<li><a class="reference internal" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" id="id19">Conversion from retainable object pointer type in certain contexts</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-qualification" id="id20">Ownership qualification</a><ul>
+<li><a class="reference internal" href="#spelling" id="id21">Spelling</a><ul>
+<li><a class="reference internal" href="#property-declarations" id="id22">Property declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#semantics" id="id23">Semantics</a></li>
+<li><a class="reference internal" href="#arc-ownership-restrictions" id="id24">Restrictions</a><ul>
+<li><a class="reference internal" href="#weak-unavailable-types" id="id25">Weak-unavailable types</a></li>
+<li><a class="reference internal" href="#storage-duration-of-autoreleasing-objects" id="id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a></li>
+<li><a class="reference internal" href="#conversion-of-pointers-to-ownership-qualified-types" id="id27">Conversion of pointers to ownership-qualified types</a></li>
+<li><a class="reference internal" href="#passing-to-an-out-parameter-by-writeback" id="id28">Passing to an out parameter by writeback</a></li>
+<li><a class="reference internal" href="#ownership-qualified-fields-of-structs-and-unions" id="id29">Ownership-qualified fields of structs and unions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-inference" id="id30">Ownership inference</a><ul>
+<li><a class="reference internal" href="#objects" id="id31">Objects</a></li>
+<li><a class="reference internal" href="#indirect-parameters" id="id32">Indirect parameters</a></li>
+<li><a class="reference internal" href="#template-arguments" id="id33">Template arguments</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#method-families" id="id34">Method families</a><ul>
+<li><a class="reference internal" href="#explicit-method-family-control" id="id35">Explicit method family control</a></li>
+<li><a class="reference internal" href="#semantics-of-method-families" id="id36">Semantics of method families</a><ul>
+<li><a class="reference internal" href="#semantics-of-init" id="id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a></li>
+<li><a class="reference internal" href="#related-result-types" id="id38">Related result types</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimization" id="id39">Optimization</a><ul>
+<li><a class="reference internal" href="#object-liveness" id="id40">Object liveness</a></li>
+<li><a class="reference internal" href="#no-object-lifetime-extension" id="id41">No object lifetime extension</a></li>
+<li><a class="reference internal" href="#precise-lifetime-semantics" id="id42">Precise lifetime semantics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#miscellaneous" id="id43">Miscellaneous</a><ul>
+<li><a class="reference internal" href="#special-methods" id="id44">Special methods</a><ul>
+<li><a class="reference internal" href="#memory-management-methods" id="id45">Memory management methods</a></li>
+<li><a class="reference internal" href="#dealloc" id="id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#autoreleasepool" id="id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a></li>
+<li><a class="reference internal" href="#self" id="id48"><tt class="docutils literal"><span class="pre">self</span></tt></a></li>
+<li><a class="reference internal" href="#fast-enumeration-iteration-variables" id="id49">Fast enumeration iteration variables</a></li>
+<li><a class="reference internal" href="#blocks" id="id50">Blocks</a></li>
+<li><a class="reference internal" href="#exceptions" id="id51">Exceptions</a></li>
+<li><a class="reference internal" href="#interior-pointers" id="id52">Interior pointers</a></li>
+<li><a class="reference internal" href="#c-retainable-pointer-types" id="id53">C retainable pointer types</a><ul>
+<li><a class="reference internal" href="#auditing-of-c-retainable-pointer-interfaces" id="id54">Auditing of C retainable pointer interfaces</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-support" id="id55">Runtime support</a><ul>
+<li><a class="reference internal" href="#arc-runtime-objc-autorelease" id="id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpop-void-pool" id="id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpush-void" id="id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue" id="id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-copyweak-id-dest-id-src" id="id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-destroyweak-id-object" id="id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-initweak" id="id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweak" id="id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweakretained" id="id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-moveweak-id-dest-id-src" id="id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-release-id-value" id="id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retain" id="id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautorelease" id="id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasereturnvalue" id="id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue" id="id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainblock" id="id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storestrong" id="id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storeweak" id="id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="about-this-document">
+<span id="arc-meta"></span><h2><a class="toc-backref" href="#id4">About this document</a><a class="headerlink" href="#about-this-document" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="purpose">
+<span id="arc-meta-purpose"></span><h3><a class="toc-backref" href="#id5">Purpose</a><a class="headerlink" href="#purpose" title="Permalink to this headline">¶</a></h3>
+<p>The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting. Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.</p>
+<p>The secondary purpose is to act as a rationale for why ARC was designed in this
+way. This should remain tightly focused on the technical design and should not
+stray into marketing speculation.</p>
+</div>
+<div class="section" id="background">
+<span id="arc-meta-background"></span><h3><a class="toc-backref" href="#id6">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3>
+<p>This document assumes a basic familiarity with C.</p>
+<p><span class="arc-term">Blocks</span> are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using <span class="arc-term">block
+pointers</span>, which are represented like a normal pointer. A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated. The initial allocation is done on the stack, but the runtime
+provides a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1. The paired function is
+<tt class="docutils literal"><span class="pre">Block_release</span></tt>, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.</p>
+<p>Objective-C is a set of language extensions, significant enough to be
+considered a different language. It is a strict superset of C. The extensions
+can also be imposed on C++, producing a language called Objective-C++. The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.</p>
+<p>Objective-C defines a new type kind, collectively called the <span class="arc-term">object
+pointer types</span>. This kind has two notable builtin members, <tt class="docutils literal"><span class="pre">id</span></tt> and
+<tt class="docutils literal"><span class="pre">Class</span></tt>; <tt class="docutils literal"><span class="pre">id</span></tt> is the final supertype of all object pointers. The validity
+of conversions between object pointer types is not checked at runtime. Users
+may define <span class="arc-term">classes</span>; each class is a type, and the pointer to that
+type is an object pointer type. A class may have a superclass; its pointer
+type is a subtype of its superclass’s pointer type. A class has a set of
+<span class="arc-term">ivars</span>, fields which appear on all instances of that class. For
+every class <em>T</em> there’s an associated metaclass; it has no fields, its
+superclass is the metaclass of <em>T</em>‘s superclass, and its metaclass is a global
+class. Every class has a global object whose class is the class’s metaclass;
+metaclasses have no associated type, so pointers to this object have type
+<tt class="docutils literal"><span class="pre">Class</span></tt>.</p>
+<p>A class declaration (<tt class="docutils literal"><span class="pre">@interface</span></tt>) declares a set of <span class="arc-term">methods</span>. A
+method has a return type, a list of argument types, and a <span class="arc-term">selector</span>:
+a name like <tt class="docutils literal"><span class="pre">foo:bar:baz:</span></tt>, where the number of colons corresponds to the
+number of formal arguments. A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass. A method may be invoked by
+providing an object (called the <span class="arc-term">receiver</span>) and a list of formal
+arguments interspersed with the selector, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">receiver</span> <span class="n">foo</span><span class="o">:</span> <span class="n">fooArg</span> <span class="n">bar</span><span class="o">:</span> <span class="n">barArg</span> <span class="n">baz</span><span class="o">:</span> <span class="n">bazArg</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>This looks in the dynamic class of the receiver for a method with this name,
+then in that class’s superclass, etc., until it finds something it can execute.
+The receiver “expression” may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be <tt class="docutils literal"><span class="pre">super</span></tt>, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class. The actual methods
+dynamically found in a class are not those declared in the <tt class="docutils literal"><span class="pre">@interface</span></tt>, but
+those defined in a separate <tt class="docutils literal"><span class="pre">@implementation</span></tt> declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>.</p>
+<p>Method declarations may also be grouped into <span class="arc-term">protocols</span>, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.</p>
+<p><span class="arc-term">Class extensions</span> are collections of ivars and methods, designed to
+allow a class’s <tt class="docutils literal"><span class="pre">@interface</span></tt> to be split across multiple files; however,
+there is still a primary implementation file which must see the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>s of all class extensions. <span class="arc-term">Categories</span> allow
+methods (but not ivars) to be declared <em>post hoc</em> on an arbitrary class; the
+methods in the category’s <tt class="docutils literal"><span class="pre">@implementation</span></tt> will be dynamically added to that
+class’s method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.</p>
+<p>In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count. This is done using two
+instance methods which all classes are expected to implement: <tt class="docutils literal"><span class="pre">retain</span></tt>
+increases the object’s reference count by 1, whereas <tt class="docutils literal"><span class="pre">release</span></tt> decreases it
+by 1 and calls the instance method <tt class="docutils literal"><span class="pre">dealloc</span></tt> if the count reaches 0. To
+simplify certain operations, there is also an <span class="arc-term">autorelease pool</span>, a
+thread-local list of objects to call <tt class="docutils literal"><span class="pre">release</span></tt> on later; an object can be
+added to this pool by calling <tt class="docutils literal"><span class="pre">autorelease</span></tt> on it.</p>
+<p>Block pointers may be converted to type <tt class="docutils literal"><span class="pre">id</span></tt>; block objects are laid out in a
+way that makes them compatible with Objective-C objects. There is a builtin
+class that all block objects are considered to be objects of; this class
+implements <tt class="docutils literal"><span class="pre">retain</span></tt> by adjusting the reference count, not by calling
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>.</p>
+</div>
+<div class="section" id="evolution">
+<span id="arc-meta-evolution"></span><h3><a class="toc-backref" href="#id7">Evolution</a><a class="headerlink" href="#evolution" title="Permalink to this headline">¶</a></h3>
+<p>ARC is under continual evolution, and this document must be updated as the
+language progresses.</p>
+<p>If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:</p>
+<blockquote>
+<div>ARC applies to Objective-C pointer types, block pointer types, and
+<span class="when-revised">[beginning Apple 8.0, LLVM 3.8]</span> <span class="revision">BPTRs declared
+within</span> <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"BCPL"</span></tt> blocks.</div></blockquote>
+<p>For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang. “LLVM X.Y” refers to an
+open-source release of clang from the LLVM project. “Apple X.Y” refers to an
+Apple-provided release of the Apple LLVM Compiler. Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.</p>
+<p>If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions. Such
+changes are generally to be avoided.</p>
+</div>
+</div>
+<div class="section" id="general">
+<span id="arc-general"></span><h2><a class="toc-backref" href="#id8">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
+<p>Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases. It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.</p>
+<p>ARC may be explicitly enabled with the compiler flag <tt class="docutils literal"><span class="pre">-fobjc-arc</span></tt>. It may
+also be explicitly disabled with the compiler flag <tt class="docutils literal"><span class="pre">-fno-objc-arc</span></tt>. The last
+of these two flags appearing on the compile line “wins”.</p>
+<p>If ARC is enabled, <tt class="docutils literal"><span class="pre">__has_feature(objc_arc)</span></tt> will expand to 1 in the
+preprocessor. For more information about <tt class="docutils literal"><span class="pre">__has_feature</span></tt>, see the
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>language extensions</em></a> document.</p>
+</div>
+<div class="section" id="retainable-object-pointers">
+<span id="arc-objects"></span><h2><a class="toc-backref" href="#id9">Retainable object pointers</a><a class="headerlink" href="#retainable-object-pointers" title="Permalink to this headline">¶</a></h2>
+<p>This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC. Note in particular that it
+covers the rules for pointer <em>values</em> (patterns of bits indicating the location
+of a pointed-to object), not pointer <em>objects</em> (locations in memory which store
+pointer values). The rules for objects are covered in the next section.</p>
+<p>A <span class="arc-term">retainable object pointer</span> (or “retainable pointer”) is a value of
+a <span class="arc-term">retainable object pointer type</span> (“retainable type”). There are
+three kinds of retainable object pointer types:</p>
+<ul class="simple">
+<li>block pointers (formed by applying the caret (<tt class="docutils literal"><span class="pre">^</span></tt>) declarator sigil to a
+function type)</li>
+<li>Objective-C object pointers (<tt class="docutils literal"><span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">Class</span></tt>, <tt class="docutils literal"><span class="pre">NSFoo*</span></tt>, etc.)</li>
+<li>typedefs marked with <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt></li>
+</ul>
+<p>Other pointer types, such as <tt class="docutils literal"><span class="pre">int*</span></tt> and <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, are not subject to
+ARC’s semantics and restrictions.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>We are not at liberty to require all code to be recompiled with ARC;
+therefore, ARC must interoperate with Objective-C code which manages retains
+and releases manually. In general, there are three requirements in order for
+a compiler-supported reference-count system to provide reliable
+interoperation:</p>
+<ul class="last simple">
+<li>The type system must reliably identify which objects are to be managed. An
+<tt class="docutils literal"><span class="pre">int*</span></tt> might be a pointer to a <tt class="docutils literal"><span class="pre">malloc</span></tt>‘ed array, or it might be an
+interior pointer to such an array, or it might point to some field or local
+variable. In contrast, values of the retainable object pointer types are
+never interior.</li>
+<li>The type system must reliably indicate how to manage objects of a type.
+This usually means that the type must imply a procedure for incrementing
+and decrementing retain counts. Supporting single-ownership objects
+requires a lot more explicit mediation in the language.</li>
+<li>There must be reliable conventions for whether and when “ownership” is
+passed between caller and callee, for both arguments and return values.
+Objective-C methods follow such a convention very reliably, at least for
+system libraries on Mac OS X, and functions always pass objects at +0. The
+C-based APIs for Core Foundation objects, on the other hand, have much more
+varied transfer semantics.</li>
+</ul>
+</div>
+<p>The use of <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> typedefs is not recommended. If it’s
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+<tt class="docutils literal"><span class="pre">__typeof</span></tt> and C++ template argument substitution.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Any compiler operation which incidentally strips type “sugar” from a type
+will yield a type without the attribute, which may result in unexpected
+behavior.</p>
+</div>
+<div class="section" id="retain-count-semantics">
+<span id="arc-objects-retains"></span><h3><a class="toc-backref" href="#id10">Retain count semantics</a><a class="headerlink" href="#retain-count-semantics" title="Permalink to this headline">¶</a></h3>
+<p>A retainable object pointer is either a <span class="arc-term">null pointer</span> or a pointer
+to a valid object. Furthermore, if it has block pointer type and is not
+<tt class="docutils literal"><span class="pre">null</span></tt> then it must actually be a pointer to a block object, and if it has
+<tt class="docutils literal"><span class="pre">Class</span></tt> type (possibly protocol-qualified) then it must actually be a pointer
+to a class object. Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.</p>
+<p>For ARC’s purposes, a valid object is one with “well-behaved” retaining
+operations. Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">retain</span></tt>, taking no arguments and returning a pointer to the object.</li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt>, taking no arguments and returning <tt class="docutils literal"><span class="pre">void</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt>, taking no arguments and returning a pointer to the object.</li>
+</ul>
+<p>The behavior of these methods is constrained in the following ways. The term
+<span class="arc-term">high-level semantics</span> is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements. For example, if the user puts logging statements
+in <tt class="docutils literal"><span class="pre">retain</span></tt>, they should not be surprised if those statements are executed
+more or less often depending on optimization settings. These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.</p>
+<p>It is undefined behavior if a computation history featuring a send of
+<tt class="docutils literal"><span class="pre">retain</span></tt> followed by a send of <tt class="docutils literal"><span class="pre">release</span></tt> to the same object, with no
+intervening <tt class="docutils literal"><span class="pre">release</span></tt> on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed. Note that
+this implies that these methods may not raise exceptions.</p>
+<p>It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of <tt class="docutils literal"><span class="pre">release</span></tt> that is not
+preceded by a send of <tt class="docutils literal"><span class="pre">retain</span></tt> to the same object.</p>
+<p>The behavior of <tt class="docutils literal"><span class="pre">autorelease</span></tt> must be equivalent to sending <tt class="docutils literal"><span class="pre">release</span></tt> when
+one of the autorelease pools currently in scope is popped. It may not throw an
+exception.</p>
+<p>When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is <tt class="docutils literal"><span class="pre">null</span></tt> then the effect is a no-op.</p>
+<p>All of the semantics described in this document are subject to additional
+<a class="reference internal" href="#arc-optimization"><em>optimization rules</em></a> which permit the removal or
+optimization of operations based on local knowledge of data flow. The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.</p>
+</div>
+<div class="section" id="retainable-object-pointers-as-operands-and-arguments">
+<span id="arc-objects-operands"></span><h3><a class="toc-backref" href="#id11">Retainable object pointers as operands and arguments</a><a class="headerlink" href="#retainable-object-pointers-as-operands-and-arguments" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression. This includes:</p>
+<ul class="simple">
+<li>loading a retainable pointer from an object with non-weak <a class="reference internal" href="#arc-ownership"><em>ownership</em></a>,</li>
+<li>passing a retainable pointer as an argument to a function or method, and</li>
+<li>receiving a retainable pointer as the result of a function or method call.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While this might seem uncontroversial, it is actually unsafe when multiple
+expressions are evaluated in “parallel”, as with binary operators and calls,
+because (for example) one expression might load from an object while another
+writes to it. However, C and C++ already call this undefined behavior
+because the evaluations are unsequenced, and ARC simply exploits that here to
+avoid needing to retain arguments across a large number of calls.</p>
+</div>
+<p>The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.</p>
+<div class="section" id="consumed-parameters">
+<span id="arc-objects-operands-consumed"></span><h4><a class="toc-backref" href="#id12">Consumed parameters</a><a class="headerlink" href="#consumed-parameters" title="Permalink to this headline">¶</a></h4>
+<p>A function or method parameter of retainable object pointer type may be marked
+as <span class="arc-term">consumed</span>, signifying that the callee expects to take ownership
+of a +1 retain count. This is done by adding the <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> attribute to
+the parameter declaration, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="kt">id</span> <span class="n">x</span><span class="p">);</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">foo:</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method, not the type of
+the parameter. It controls only how the argument is passed and received.</p>
+<p>When passing such an argument, ARC retains the argument prior to making the
+call.</p>
+<p>When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a caller to a callee. The
+most common scenario here is passing the <tt class="docutils literal"><span class="pre">self</span></tt> parameter to <tt class="docutils literal"><span class="pre">init</span></tt>, but
+it is useful to generalize. Typically, local optimization will remove any
+extra retains and releases: on the caller side the retain will be merged with
+a +1 source, and on the callee side the release will be rolled into the
+initialization of the parameter.</p>
+</div>
+<p>The implicit <tt class="docutils literal"><span class="pre">self</span></tt> parameter of a method may be marked as consumed by adding
+<tt class="docutils literal"><span class="pre">__attribute__((ns_consumes_self))</span></tt> to the method declaration. Methods in
+the <tt class="docutils literal"><span class="pre">init</span></tt> <a class="reference internal" href="#arc-method-families"><em>family</em></a> are treated as if they were
+implicitly marked with this attribute.</p>
+<p>It is undefined behavior if an Objective-C message send to a method with
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters (other than self) is made with a null receiver. It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters than
+the method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with a different set of
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters than the implementation of the called block or
+function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters with null receiver are a guaranteed leak. Mismatches
+with consumed parameters will cause over-retains or over-releases, depending
+on the direction. The rule about function calls is really just an
+application of the existing C/C++ rule about calling functions through an
+incompatible function type, but it’s useful to state it explicitly.</p>
+</div>
+</div>
+<div class="section" id="retained-return-values">
+<span id="arc-object-operands-retained-return-values"></span><h4><a class="toc-backref" href="#id13">Retained return values</a><a class="headerlink" href="#retained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count. This is done by adding the
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute to the function or method declaration, like
+so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nf">foo</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.</p>
+<p>When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a callee to a caller. The
+most common scenario this models is the retained return from <tt class="docutils literal"><span class="pre">init</span></tt>,
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">new</span></tt>, and <tt class="docutils literal"><span class="pre">copy</span></tt> methods, but there are other cases in the
+frameworks. After optimization there are typically no extra retains and
+releases required.</p>
+</div>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt>
+<a class="reference internal" href="#arc-method-families"><em>families</em></a> are implicitly marked
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_retained))</span></tt>. This may be suppressed by explicitly
+marking the method <tt class="docutils literal"><span class="pre">__attribute__((ns_returns_not_retained))</span></tt>.</p>
+<p>It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Mismatches with returned results will cause over-retains or over-releases,
+depending on the direction. Again, the rule about function calls is really
+just an application of the existing C/C++ rule about calling functions
+through an incompatible function type.</p>
+</div>
+</div>
+<div class="section" id="unretained-return-values">
+<span id="arc-objects-operands-unretained-returns"></span><h4><a class="toc-backref" href="#id14">Unretained return values</a><a class="headerlink" href="#unretained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary. In the worst case, this may involve an <tt class="docutils literal"><span class="pre">autorelease</span></tt>, but
+callers must not assume that the value is actually in the autorelease pool.</p>
+<p>ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">It is common in non-ARC code to not return an autoreleased value; therefore
+the convention does not force either path. It is convenient to not be
+required to do unnecessary retains and autoreleases; this permits
+optimizations such as eliding retain/autoreleases when it can be shown that
+the original pointer will still be valid at the point of return.</p>
+</div>
+<p>A method or function may be marked with
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_autoreleased))</span></tt> to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool. There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.</p>
+</div>
+<div class="section" id="bridged-casts">
+<span id="arc-objects-operands-casts"></span><h4><a class="toc-backref" href="#id15">Bridged casts</a><a class="headerlink" href="#bridged-casts" title="Permalink to this headline">¶</a></h4>
+<p>A <span class="arc-term">bridged cast</span> is a C-style cast annotated with one of three
+keywords:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">(__bridge</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand to the destination type <tt class="docutils literal"><span class="pre">T</span></tt>. If
+<tt class="docutils literal"><span class="pre">T</span></tt> is a retainable object pointer type, then <tt class="docutils literal"><span class="pre">op</span></tt> must have a
+non-retainable pointer type. If <tt class="docutils literal"><span class="pre">T</span></tt> is a non-retainable pointer type,
+then <tt class="docutils literal"><span class="pre">op</span></tt> must have a retainable object pointer type. Otherwise the cast
+is ill-formed. There is no transfer of ownership, and ARC inserts no retain
+operations.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_retained</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand, which must have retainable
+object pointer type, to the destination type, which must be a non-retainable
+pointer type. ARC retains the value, subject to the usual optimizations on
+local values, and the recipient is responsible for balancing that +1.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_transfer</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand, which must have
+non-retainable pointer type, to the destination type, which must be a
+retainable object pointer type. ARC will release the value at the end of
+the enclosing full-expression, subject to the usual optimizations on local
+values.</li>
+</ul>
+<p>These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on <a class="reference internal" href="#arc-objects-restrictions-conversion"><em>conversion of retainable
+object pointers</em></a>.</p>
+<p>Using a <tt class="docutils literal"><span class="pre">__bridge_retained</span></tt> or <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.</p>
+</div>
+</div>
+<div class="section" id="restrictions">
+<span id="arc-objects-restrictions"></span><h3><a class="toc-backref" href="#id16">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="conversion-of-retainable-object-pointers">
+<span id="arc-objects-restrictions-conversion"></span><h4><a class="toc-backref" href="#id17">Conversion of retainable object pointers</a><a class="headerlink" href="#conversion-of-retainable-object-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed. For example, an Objective-C object pointer shall
+not be converted to <tt class="docutils literal"><span class="pre">void*</span></tt>. As an exception, cast to <tt class="docutils literal"><span class="pre">intptr_t</span></tt> is
+allowed because such casts are not transferring ownership. The <a class="reference internal" href="#arc-objects-operands-casts"><em>bridged
+casts</em></a> may be used to perform these conversions
+where necessary.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">We cannot ensure the correct management of the lifetime of objects if they
+may be freely passed around as unmanaged types. The bridged casts are
+provided so that the programmer may explicitly describe whether the cast
+transfers control into or out of ARC.</p>
+</div>
+<p>However, the following exceptions apply.</p>
+</div>
+<div class="section" id="conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics">
+<span id="arc-objects-restrictions-conversion-with-known-semantics"></span><h4><a class="toc-backref" href="#id18">Conversion to retainable object pointer type of expressions with known semantics</a><a class="headerlink" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span>
+<span class="revision">These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.</span></p>
+<p>An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.</p>
+<p>An expression is <span class="arc-term">known retain-agnostic</span> if it is:</p>
+<ul class="simple">
+<li>an Objective-C string literal,</li>
+<li>a load from a <tt class="docutils literal"><span class="pre">const</span></tt> system global variable of <a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer
+type</em></a>, or</li>
+<li>a null pointer constant.</li>
+</ul>
+<p>An expression is <span class="arc-term">known unretained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a direct call to a function, and either that function has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it is an <a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function that does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute and does not follow the create/copy naming
+convention,</li>
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it has neither the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute nor a <a class="reference internal" href="#arc-method-families"><em>selector family</em></a> that implies a retained result.</li>
+</ul>
+<p>An expression is <span class="arc-term">known retained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute, or it does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute but it does have a <a class="reference internal" href="#arc-method-families"><em>selector
+family</em></a> that implies a retained result.</li>
+</ul>
+<p>Furthermore:</p>
+<ul class="simple">
+<li>a comma expression is classified according to its right-hand side,</li>
+<li>a statement expression is classified according to its result expression, if
+it has one,</li>
+<li>an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+classified according to the underlying message send, and</li>
+<li>a conditional operator is classified according to its second and third
+operands, if they agree in classification, or else the other if one is known
+retain-agnostic.</li>
+</ul>
+<p>If the cast operand is known retained, the conversion is treated as a
+<tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast. If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a <tt class="docutils literal"><span class="pre">__bridge</span></tt> cast.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Bridging casts are annoying. Absent the ability to completely automate the
+management of CF objects, however, we are left with relatively poor attempts
+to reduce the need for a glut of explicit bridges. Hence these rules.</p>
+<p class="last">We’ve so far consciously refrained from implicitly turning retained CF
+results from function calls into <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> casts. The worry is
+that some code patterns — for example, creating a CF value, assigning it
+to an ObjC-typed local, and then calling <tt class="docutils literal"><span class="pre">CFRelease</span></tt> when done — are a
+bit too likely to be accidentally accepted, leading to mysterious behavior.</p>
+</div>
+</div>
+<div class="section" id="conversion-from-retainable-object-pointer-type-in-certain-contexts">
+<span id="arc-objects-restrictions-conversion-exception-contextual"></span><h4><a class="toc-backref" href="#id19">Conversion from retainable object pointer type in certain contexts</a><a class="headerlink" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>If an expression of retainable object pointer type is explicitly cast to a
+<a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer type</em></a>, the program is
+ill-formed as discussed above unless the result is immediately used:</p>
+<ul class="simple">
+<li>to initialize a parameter in an Objective-C message send where the parameter
+is not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, or</li>
+<li>to initialize a parameter in a direct call to an
+<a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function where the parameter is
+not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters are left out because ARC would naturally balance them
+with a retain, which was judged too treacherous. This is in part because
+several of the most common consuming functions are in the <tt class="docutils literal"><span class="pre">Release</span></tt> family,
+and it would be quite unfortunate for explicit releases to be silently
+balanced out in this way.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-qualification">
+<span id="arc-ownership"></span><h2><a class="toc-backref" href="#id20">Ownership qualification</a><a class="headerlink" href="#ownership-qualification" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the behavior of <em>objects</em> of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.</p>
+<p>A type is a <span class="arc-term">retainable object owner type</span> if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.</p>
+<p>An <span class="arc-term">ownership qualifier</span> is a type qualifier which applies only to
+retainable object owner types. An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.</p>
+<p>A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.</p>
+<p>When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.</p>
+<p>Except as described under the <a class="reference internal" href="#arc-ownership-inference"><em>inference rules</em></a>,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules, together with the inference rules, ensure that all objects and
+lvalues of retainable object pointer type have an ownership qualifier. The
+ability to override an ownership qualifier during template substitution is
+required to counteract the <a class="reference internal" href="#arc-ownership-inference-template-arguments"><em>inference of __strong for template type
+arguments</em></a>. Ownership qualifiers
+on return types are dropped because they serve no purpose there except to
+cause spurious problems with overloading and templates.</p>
+</div>
+<p>There are four ownership qualifiers:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__strong</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__weak</span></tt></li>
+</ul>
+<p>A type is <span class="arc-term">nontrivially ownership-qualified</span> if it is qualified with
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, <tt class="docutils literal"><span class="pre">__strong</span></tt>, or <tt class="docutils literal"><span class="pre">__weak</span></tt>.</p>
+<div class="section" id="spelling">
+<span id="arc-ownership-spelling"></span><h3><a class="toc-backref" href="#id21">Spelling</a><a class="headerlink" href="#spelling" title="Permalink to this headline">¶</a></h3>
+<p>The names of the ownership qualifiers are reserved for the implementation. A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.</p>
+<p>An ownership qualifier may be written anywhere that any other type qualifier
+may be written.</p>
+<p>If an ownership qualifier appears in the <em>declaration-specifiers</em>, the
+following rules apply:</p>
+<ul class="simple">
+<li>if the type specifier is a retainable object owner type, the qualifier
+initially applies to that type;</li>
+<li>otherwise, if the outermost non-array declarator is a pointer
+or block pointer declarator, the qualifier initially applies to
+that type;</li>
+<li>otherwise the program is ill-formed.</li>
+<li>If the qualifier is so applied at a position in the declaration
+where the next-innermost declarator is a function declarator, and
+there is an block declarator within that function declarator, then
+the qualifier applies instead to that block declarator and this rule
+is considered afresh beginning from the new position.</li>
+</ul>
+<p>If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.</p>
+<p>If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Ownership qualifiers are like <tt class="docutils literal"><span class="pre">const</span></tt> and <tt class="docutils literal"><span class="pre">volatile</span></tt> in the sense
+that they may sensibly apply at multiple distinct positions within a
+declarator. However, unlike those qualifiers, there are many
+situations where they are not meaningful, and so we make an effort
+to “move” the qualifier to a place where it will be meaningful. The
+general goal is to allow the programmer to write, say, <tt class="docutils literal"><span class="pre">__strong</span></tt>
+before the entire declaration and have it apply in the leftmost
+sensible place.</p>
+</div>
+<div class="section" id="property-declarations">
+<span id="arc-ownership-spelling-property"></span><h4><a class="toc-backref" href="#id22">Property declarations</a><a class="headerlink" href="#property-declarations" title="Permalink to this headline">¶</a></h4>
+<p>A property of retainable object pointer type may have ownership. If the
+property’s type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership. A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> ownership.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">assign</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">copy</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership, as well as the usual behavior of
+copy semantics on the setter.</li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">strong</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">unsafe_unretained</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">weak</span></tt> implies <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership.</li>
+</ul>
+<p>With the exception of <tt class="docutils literal"><span class="pre">weak</span></tt>, these modifiers are available in non-ARC
+modes.</p>
+<p>A property’s specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized. If a
+property is synthesized, then the <span class="arc-term">associated instance variable</span> is
+the instance variable which is named, possibly implicitly, by the
+<tt class="docutils literal"><span class="pre">@synthesize</span></tt> declaration. If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.</p>
+<p>A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, <span class="when-revised">[beginning Apple 3.1, LLVM 3.1]</span>
+<span class="revision">its ownership is implicitly</span> <tt class="docutils literal"><span class="pre">strong</span></tt>. Prior to this revision, it
+was ill-formed to synthesize such a property.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Using <tt class="docutils literal"><span class="pre">strong</span></tt> by default is safe and consistent with the generic ARC rule
+about <a class="reference internal" href="#arc-ownership-inference-variables"><em>inferring ownership</em></a>. It is,
+unfortunately, inconsistent with the non-ARC rule which states that such
+properties are implicitly <tt class="docutils literal"><span class="pre">assign</span></tt>. However, that rule is clearly
+untenable in ARC, since it leads to default-unsafe code. The main merit to
+banning the properties is to avoid confusion with non-ARC practice, which did
+not ultimately strike us as sufficient to justify requiring extra syntax and
+(more importantly) forcing novices to understand ownership rules just to
+declare a property when the default is so reasonable. Changing the rule away
+from non-ARC practice was acceptable because we had conservatively banned the
+synthesis in order to give ourselves exactly this leeway.</p>
+</div>
+<p>Applying <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than <tt class="docutils literal"><span class="pre">assign</span></tt>. These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.</p>
+</div>
+</div>
+<div class="section" id="semantics">
+<span id="arc-ownership-semantics"></span><h3><a class="toc-backref" href="#id23">Semantics</a><a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h3>
+<p>There are five <span class="arc-term">managed operations</span> which may be performed on an
+object of retainable object pointer type. Each qualifier specifies different
+semantics for each of these operations. It is still undefined behavior to
+access an object outside of its lifetime.</p>
+<p>A load or store with “primitive semantics” has the same semantics as the
+respective operation would have on an <tt class="docutils literal"><span class="pre">void*</span></tt> lvalue with the same alignment
+and non-ownership qualification.</p>
+<p><span class="arc-term">Reading</span> occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> objects, the current pointee is retained and then released at
+the end of the current full-expression. This must execute atomically with
+respect to assignments and to the final release of the pointee.</li>
+<li>For all other objects, the lvalue is loaded with primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Assignment</span> occurs when evaluating an assignment operator. The
+semantics vary based on the qualification:</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__strong</span></tt> objects, the new pointee is first retained; second, the
+lvalue is loaded with primitive semantics; third, the new pointee is stored
+into the lvalue with primitive semantics; and finally, the old pointee is
+released. This is not performed atomically; external synchronization must be
+used to make this safe in the face of concurrent loads and stores.</li>
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> objects, the lvalue is updated to point to the new pointee,
+unless the new pointee is an object currently undergoing deallocation, in
+which case the lvalue is updated to a null pointer. This must execute
+atomically with respect to other assignments to the object, to reads from the
+object, and to the final release of the new pointee.</li>
+<li>For <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> objects, the new pointee is stored into the
+lvalue using primitive semantics.</li>
+<li>For <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects, the new pointee is retained, autoreleased,
+and stored into the lvalue using primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Initialization</span> occurs when an object’s lifetime begins, which
+depends on its storage duration. Initialization proceeds in two stages:</p>
+<ol class="arabic simple">
+<li>First, a null pointer is stored into the lvalue using primitive semantics.
+This step is skipped if the object is <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>.</li>
+<li>Second, if the object has an initializer, that expression is evaluated and
+then assigned into the object using the usual assignment semantics.</li>
+</ol>
+<p><span class="arc-term">Destruction</span> occurs when an object’s lifetime ends. In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object’s
+lifetime ends.</p>
+<p><span class="arc-term">Moving</span> occurs in specific situations where an lvalue is “moved
+from”, meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state. This arises with <tt class="docutils literal"><span class="pre">__block</span></tt> variables
+and rvalue references in C++. For <tt class="docutils literal"><span class="pre">__strong</span></tt> lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression. For all other lvalues, moving is equivalent to
+reading the object.</p>
+</div>
+<div class="section" id="arc-ownership-restrictions">
+<span id="id1"></span><h3><a class="toc-backref" href="#id24">Restrictions</a><a class="headerlink" href="#arc-ownership-restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="weak-unavailable-types">
+<span id="arc-ownership-restrictions-weak"></span><h4><a class="toc-backref" href="#id25">Weak-unavailable types</a><a class="headerlink" href="#weak-unavailable-types" title="Permalink to this headline">¶</a></h4>
+<p>It is explicitly permitted for Objective-C classes to not support <tt class="docutils literal"><span class="pre">__weak</span></tt>
+references. It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support <tt class="docutils literal"><span class="pre">__weak</span></tt> references.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Historically, it has been possible for a class to provide its own
+reference-count implementation by overriding <tt class="docutils literal"><span class="pre">retain</span></tt>, <tt class="docutils literal"><span class="pre">release</span></tt>, etc.
+However, weak references to an object require coordination with its class’s
+reference-count implementation because, among other things, weak loads and
+stores must be atomic with respect to the final release. Therefore, existing
+custom reference-count implementations will generally not support weak
+references without additional effort. This is unavoidable without breaking
+binary compatibility.</p>
+</div>
+<p>A class may indicate that it does not support weak references by providing the
+<tt class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></tt> attribute on the class’s interface declaration. A
+retainable object pointer type is <strong>weak-unavailable</strong> if
+is a pointer to an (optionally protocol-qualified) Objective-C class <tt class="docutils literal"><span class="pre">T</span></tt> where
+<tt class="docutils literal"><span class="pre">T</span></tt> or one of its superclasses has the <tt class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></tt>
+attribute. A program is ill-formed if it applies the <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.</p>
+</div>
+<div class="section" id="storage-duration-of-autoreleasing-objects">
+<span id="arc-ownership-restrictions-autoreleasing"></span><h4><a class="toc-backref" href="#id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a><a class="headerlink" href="#storage-duration-of-autoreleasing-objects" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares an <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object of
+non-automatic storage duration. A program is ill-formed if it captures an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object in a block or, unless by reference, in a C++11
+lambda.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are tied to the current thread and scope by their nature.
+While it is possible to have temporary objects whose instance variables are
+filled with autoreleased objects, there is no way that ARC can provide any
+sort of safety guarantee there.</p>
+</div>
+<p>It is undefined behavior if a non-null pointer is assigned to an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object while an autorelease pool is in scope and then that
+object is read after the autorelease pool’s scope is left.</p>
+</div>
+<div class="section" id="conversion-of-pointers-to-ownership-qualified-types">
+<span id="arc-ownership-restrictions-conversion-indirect"></span><h4><a class="toc-backref" href="#id27">Conversion of pointers to ownership-qualified types</a><a class="headerlink" href="#conversion-of-pointers-to-ownership-qualified-types" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if an expression of type <tt class="docutils literal"><span class="pre">T*</span></tt> is converted,
+explicitly or implicitly, to the type <tt class="docutils literal"><span class="pre">U*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> have
+different ownership qualification, unless:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">T</span></tt> is qualified with <tt class="docutils literal"><span class="pre">__strong</span></tt>, <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, or
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>, and <tt class="docutils literal"><span class="pre">U</span></tt> is qualified with both <tt class="docutils literal"><span class="pre">const</span></tt> and
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>; or</li>
+<li>either <tt class="docutils literal"><span class="pre">T</span></tt> or <tt class="docutils literal"><span class="pre">U</span></tt> is <tt class="docutils literal"><span class="pre">cv</span> <span class="pre">void</span></tt>, where <tt class="docutils literal"><span class="pre">cv</span></tt> is an optional sequence
+of non-ownership qualifiers; or</li>
+<li>the conversion is requested with a <tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> in Objective-C++; or</li>
+<li>the conversion is a well-formed <a class="reference internal" href="#arc-ownership-restrictions-pass-by-writeback"><em>pass-by-writeback</em></a>.</li>
+</ul>
+<p>The analogous rule applies to <tt class="docutils literal"><span class="pre">T&</span></tt> and <tt class="docutils literal"><span class="pre">U&</span></tt> in Objective-C++.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules provide a reasonable level of type-safety for indirect pointers,
+as long as the underlying memory is not deallocated. The conversion to
+<tt class="docutils literal"><span class="pre">const</span> <span class="pre">__unsafe_unretained</span></tt> is permitted because the semantics of reads are
+equivalent across all these ownership semantics, and that’s a very useful and
+common pattern. The interconversion with <tt class="docutils literal"><span class="pre">void*</span></tt> is useful for allocating
+memory or otherwise escaping the type system, but use it carefully.
+<tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> is considered to be an obvious enough sign of taking
+responsibility for any problems.</p>
+</div>
+<p>It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-<tt class="docutils literal"><span class="pre">__weak</span></tt> object
+may be read through an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> lvalue.</p>
+<p>It is undefined behavior if a managed operation is performed on a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+or <tt class="docutils literal"><span class="pre">__weak</span></tt> object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC cannot differentiate between an assignment operator which is intended to
+“initialize” dynamic memory and one which is intended to potentially replace
+a value. Therefore the object’s pointer must be valid before letting ARC at
+it. Similarly, C and Objective-C do not provide any language hooks for
+destroying objects held in dynamic memory, so it is the programmer’s
+responsibility to avoid leaks (<tt class="docutils literal"><span class="pre">__strong</span></tt> objects) and consistency errors
+(<tt class="docutils literal"><span class="pre">__weak</span></tt> objects).</p>
+</div>
+<p>These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with <tt class="docutils literal"><span class="pre">new</span></tt> or <tt class="docutils literal"><span class="pre">new[]</span></tt> and destroying
+them with <tt class="docutils literal"><span class="pre">delete</span></tt>, <tt class="docutils literal"><span class="pre">delete[]</span></tt>, or a pseudo-destructor expression. Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+<tt class="docutils literal"><span class="pre">new[]</span></tt>‘d in ARC translation units cannot be <tt class="docutils literal"><span class="pre">delete[]</span></tt>‘d in non-ARC
+translation units and vice-versa.</p>
+</div>
+<div class="section" id="passing-to-an-out-parameter-by-writeback">
+<span id="arc-ownership-restrictions-pass-by-writeback"></span><h4><a class="toc-backref" href="#id28">Passing to an out parameter by writeback</a><a class="headerlink" href="#passing-to-an-out-parameter-by-writeback" title="Permalink to this headline">¶</a></h4>
+<p>If the argument passed to a parameter of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span> <span class="pre">*</span></tt> has type
+<tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>, where <tt class="docutils literal"><span class="pre">oq</span></tt> is an ownership qualifier, then the argument is a
+candidate for <span class="arc-term">pass-by-writeback`</span> if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">oq</span></tt> is <tt class="docutils literal"><span class="pre">__strong</span></tt> or <tt class="docutils literal"><span class="pre">__weak</span></tt>, and</li>
+<li>it would be legal to initialize a <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__strong</span> <span class="pre">*</span></tt> with a <tt class="docutils literal"><span class="pre">U</span> <span class="pre">__strong</span> <span class="pre">*</span></tt>.</li>
+</ul>
+<p>For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.</p>
+<p>The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">&var</span></tt>, where <tt class="docutils literal"><span class="pre">var</span></tt> is a scalar variable of automatic storage duration
+with retainable object pointer type</li>
+<li>a conditional expression where the second and third operands are both legal
+forms</li>
+<li>a cast whose operand is a legal form</li>
+<li>a null pointer constant</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The restriction in the form of the argument serves two purposes. First, it
+makes it impossible to pass the address of an array to the argument, which
+serves to protect against an otherwise serious risk of mis-inferring an
+“array” argument as an out-parameter. Second, it makes it much less likely
+that the user will see confusing aliasing problems due to the implementation,
+below, where their store to the writeback temporary is not immediately seen
+in the original argument variable.</p>
+</div>
+<p>A pass-by-writeback is evaluated as follows:</p>
+<ol class="arabic simple">
+<li>The argument is evaluated to yield a pointer <tt class="docutils literal"><span class="pre">p</span></tt> of type <tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>.</li>
+<li>If <tt class="docutils literal"><span class="pre">p</span></tt> is a null pointer, then a null pointer is passed as the argument,
+and no further work is required for the pass-by-writeback.</li>
+<li>Otherwise, a temporary of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span></tt> is created and
+initialized to a null pointer.</li>
+<li>If the parameter is not an Objective-C method parameter marked <tt class="docutils literal"><span class="pre">out</span></tt>,
+then <tt class="docutils literal"><span class="pre">*p</span></tt> is read, and the result is written into the temporary with
+primitive semantics.</li>
+<li>The address of the temporary is passed as the argument to the actual call.</li>
+<li>After the call completes, the temporary is loaded with primitive
+semantics, and that value is assigned into <tt class="docutils literal"><span class="pre">*p</span></tt>.</li>
+</ol>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is all admittedly convoluted. In an ideal world, we would see that a
+local variable is being passed to an out-parameter and retroactively modify
+its type to be <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> rather than <tt class="docutils literal"><span class="pre">__strong</span></tt>. This would be
+remarkably difficult and not always well-founded under the C type system.
+However, it was judged unacceptably invasive to require programmers to write
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> on all the variables they intend to use for
+out-parameters. This was the least bad solution.</p>
+</div>
+</div>
+<div class="section" id="ownership-qualified-fields-of-structs-and-unions">
+<span id="arc-ownership-restrictions-records"></span><h4><a class="toc-backref" href="#id29">Ownership-qualified fields of structs and unions</a><a class="headerlink" href="#ownership-qualified-fields-of-structs-and-unions" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The resulting type would be non-POD in the C++ sense, but C does not give us
+very good language tools for managing the lifetime of aggregates, so it is
+more convenient to simply forbid them. It is still possible to manage this
+with a <tt class="docutils literal"><span class="pre">void*</span></tt> or an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> object.</p>
+</div>
+<p>This restriction does not apply in Objective-C++. However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible. It is a violation of C++’s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Unlike in C, we can express all the necessary ARC semantics for
+ownership-qualified subobjects as suboperations of the (default) special
+member functions for the class. These functions then become non-trivial.
+This has the non-obvious result that the class will have a non-trivial copy
+constructor and non-trivial destructor; if this would not normally be true
+outside of ARC, objects of the type will be passed and returned in an
+ABI-incompatible manner.</p>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-inference">
+<span id="arc-ownership-inference"></span><h3><a class="toc-backref" href="#id30">Ownership inference</a><a class="headerlink" href="#ownership-inference" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="objects">
+<span id="arc-ownership-inference-variables"></span><h4><a class="toc-backref" href="#id31">Objects</a><a class="headerlink" href="#objects" title="Permalink to this headline">¶</a></h4>
+<p>If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+<tt class="docutils literal"><span class="pre">__strong</span></tt> qualification.</p>
+<p>As a special case, if the object’s base type is <tt class="docutils literal"><span class="pre">Class</span></tt> (possibly
+protocol-qualified), the type is adjusted to have <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>
+qualification instead.</p>
+</div>
+<div class="section" id="indirect-parameters">
+<span id="arc-ownership-inference-indirect-parameters"></span><h4><a class="toc-backref" href="#id32">Indirect parameters</a><a class="headerlink" href="#indirect-parameters" title="Permalink to this headline">¶</a></h4>
+<p>If a function or method parameter has type <tt class="docutils literal"><span class="pre">T*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> is an
+ownership-unqualified retainable object pointer type, then:</p>
+<ul class="simple">
+<li>if <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">const</span></tt>-qualified or <tt class="docutils literal"><span class="pre">Class</span></tt>, then it is implicitly
+qualified with <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>;</li>
+<li>otherwise, it is implicitly qualified with <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> exists mostly for this case, the Cocoa convention for
+out-parameters. Since a pointer to <tt class="docutils literal"><span class="pre">const</span></tt> is obviously not an
+out-parameter, we instead use a type more useful for passing arrays. If the
+user instead intends to pass in a <em>mutable</em> array, inferring
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> is the wrong thing to do; this directs some of the
+caution in the following rules about writeback.</p>
+</div>
+<p>Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.</p>
+<p>This rule does not apply in Objective-C++ if a parameter’s type is dependent in
+a template pattern and is only <em>instantiated</em> to a type which would be a
+pointer to an unqualified retainable object pointer type. Such code is still
+ill-formed.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The convention is very unlikely to be intentional in template code.</p>
+</div>
+</div>
+<div class="section" id="template-arguments">
+<span id="arc-ownership-inference-template-arguments"></span><h4><a class="toc-backref" href="#id33">Template arguments</a><a class="headerlink" href="#template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have <tt class="docutils literal"><span class="pre">__strong</span></tt> qualification. This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__strong</span></tt> is a useful default for containers (e.g., <tt class="docutils literal"><span class="pre">std::vector<id></span></tt>),
+which would otherwise require explicit qualification. Moreover, unqualified
+retainable object pointer types are unlikely to be useful within templates,
+since they generally need to have a qualifier applied to the before being
+used.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="method-families">
+<span id="arc-method-families"></span><h2><a class="toc-backref" href="#id34">Method families</a><a class="headerlink" href="#method-families" title="Permalink to this headline">¶</a></h2>
+<p>An Objective-C method may fall into a <span class="arc-term">method family</span>, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.</p>
+<p>A method is in a certain method family if:</p>
+<ul class="simple">
+<li>it has a <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in that family; or if
+not that,</li>
+<li>it does not have an <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in a
+different or no family, and</li>
+<li>its selector falls into the corresponding selector family, and</li>
+<li>its signature obeys the added restrictions of the method family.</li>
+</ul>
+<p>A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter. For example, <tt class="docutils literal"><span class="pre">_perform:with:</span></tt> and
+<tt class="docutils literal"><span class="pre">performWith:</span></tt> would fall into the <tt class="docutils literal"><span class="pre">perform</span></tt> family (if we recognized one),
+but <tt class="docutils literal"><span class="pre">performing:with</span></tt> would not.</p>
+<p>The families and their added restrictions are:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">alloc</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">copy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">mutableCopy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">new</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">init</span></tt> methods must be instance methods and must return an Objective-C
+pointer type. Additionally, a program is ill-formed if it declares or
+contains a call to an <tt class="docutils literal"><span class="pre">init</span></tt> method whose return type is neither <tt class="docutils literal"><span class="pre">id</span></tt> nor
+a pointer to a super-class or sub-class of the declaring class (if the method
+was declared on a class) or the static receiver type of the call (if it was
+declared on a protocol).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>There are a fair number of existing methods with <tt class="docutils literal"><span class="pre">init</span></tt>-like selectors
+which nonetheless don’t follow the <tt class="docutils literal"><span class="pre">init</span></tt> conventions. Typically these
+are either accidental naming collisions or helper methods called during
+initialization. Because of the peculiar retain/release behavior of
+<tt class="docutils literal"><span class="pre">init</span></tt> methods, it’s very important not to treat these methods as
+<tt class="docutils literal"><span class="pre">init</span></tt> methods if they aren’t meant to be. It was felt that implicitly
+defining these methods out of the family based on the exact relationship
+between the return type and the declaring class would be much too subtle
+and fragile. Therefore we identify a small number of legitimate-seeming
+return types and call everything else an error. This serves the secondary
+purpose of encouraging programmers not to accidentally give methods names
+in the <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+<p class="last">Note that a method with an <tt class="docutils literal"><span class="pre">init</span></tt>-family selector which returns a
+non-Objective-C type (e.g. <tt class="docutils literal"><span class="pre">void</span></tt>) is perfectly well-formed; it simply
+isn’t in the <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+</div>
+</li>
+</ul>
+<p>A program is ill-formed if a method’s declarations, implementations, and
+overrides do not all have the same method family.</p>
+<div class="section" id="explicit-method-family-control">
+<span id="arc-family-attribute"></span><h3><a class="toc-backref" href="#id35">Explicit method family control</a><a class="headerlink" href="#explicit-method-family-control" title="Permalink to this headline">¶</a></h3>
+<p>A method may be annotated with the <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute to
+precisely control which method family it belongs to. If a method in an
+<tt class="docutils literal"><span class="pre">@implementation</span></tt> does not have this attribute, but there is a method
+declared in the corresponding <tt class="docutils literal"><span class="pre">@interface</span></tt> that does, then the attribute is
+copied to the declaration in the <tt class="docutils literal"><span class="pre">@implementation</span></tt>. The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+<tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+<p>The attribute is spelled
+<tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(</span></tt> <em>family</em> <tt class="docutils literal"><span class="pre">)))</span></tt>. If <em>family</em> is
+<tt class="docutils literal"><span class="pre">none</span></tt>, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type. Otherwise, <em>family</em> must be one of
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector. It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The rules codified in this document describe the standard conventions of
+Objective-C. However, as these conventions have not heretofore been enforced
+by an unforgiving mechanical system, they are only imperfectly kept,
+especially as they haven’t always even been precisely defined. While it is
+possible to define low-level ownership semantics with attributes like
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>, this attribute allows the user to communicate
+semantic intent, which is of use both to ARC (which, e.g., treats calls to
+<tt class="docutils literal"><span class="pre">init</span></tt> specially) and the static analyzer.</p>
+</div>
+</div>
+<div class="section" id="semantics-of-method-families">
+<span id="arc-family-semantics"></span><h3><a class="toc-backref" href="#id36">Semantics of method families</a><a class="headerlink" href="#semantics-of-method-families" title="Permalink to this headline">¶</a></h3>
+<p>A method’s membership in a method family may imply non-standard semantics for
+its parameters and return type.</p>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families —
+that is, methods in all the currently-defined families except <tt class="docutils literal"><span class="pre">init</span></tt> —
+implicitly <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a retained object</em></a> as if they were annotated with
+the <tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute. This can be overridden by annotating
+the method with either of the <tt class="docutils literal"><span class="pre">ns_returns_autoreleased</span></tt> or
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt> attributes.</p>
+<p>Properties also follow same naming rules as methods. This means that those in
+the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families provide access
+to <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>retained objects</em></a>. This
+can be overridden by annotating the property with <tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>
+attribute.</p>
+<div class="section" id="semantics-of-init">
+<span id="arc-family-semantics-init"></span><h4><a class="toc-backref" href="#id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a><a class="headerlink" href="#semantics-of-init" title="Permalink to this headline">¶</a></h4>
+<p>Methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family implicitly <a class="reference internal" href="#arc-objects-operands-consumed"><em>consume</em></a> their <tt class="docutils literal"><span class="pre">self</span></tt> parameter and <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a
+retained object</em></a>. Neither of
+these properties can be altered through attributes.</p>
+<p>A call to an <tt class="docutils literal"><span class="pre">init</span></tt> method with a receiver that is either <tt class="docutils literal"><span class="pre">self</span></tt> (possibly
+parenthesized or casted) or <tt class="docutils literal"><span class="pre">super</span></tt> is called a <span class="arc-term">delegate init
+call</span>. It is an error for a delegate init call to be made except from an
+<tt class="docutils literal"><span class="pre">init</span></tt> method, and excluding blocks within such methods.</p>
+<p>As an exception to the <a class="reference internal" href="#arc-misc-self"><em>usual rule</em></a>, the variable <tt class="docutils literal"><span class="pre">self</span></tt>
+is mutable in an <tt class="docutils literal"><span class="pre">init</span></tt> method and has the usual semantics for a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+variable. However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an <tt class="docutils literal"><span class="pre">init</span></tt> method attempts to use the previous value
+of <tt class="docutils literal"><span class="pre">self</span></tt> after the completion of a delegate init call. It is conventional,
+but not required, for an <tt class="docutils literal"><span class="pre">init</span></tt> method to return <tt class="docutils literal"><span class="pre">self</span></tt>.</p>
+<p>It is undefined behavior for a program to cause two or more calls to <tt class="docutils literal"><span class="pre">init</span></tt>
+methods on the same object, except that each <tt class="docutils literal"><span class="pre">init</span></tt> method invocation may
+perform at most one delegate init call.</p>
+</div>
+<div class="section" id="related-result-types">
+<span id="arc-family-semantics-result-type"></span><h4><a class="toc-backref" href="#id38">Related result types</a><a class="headerlink" href="#related-result-types" title="Permalink to this headline">¶</a></h4>
+<p>Certain methods are candidates to have <span class="arc-term">related result types</span>:</p>
+<ul class="simple">
+<li>class methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt> and <tt class="docutils literal"><span class="pre">new</span></tt> method families</li>
+<li>instance methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family</li>
+<li>the instance method <tt class="docutils literal"><span class="pre">self</span></tt></li>
+<li>outside of ARC, the instance methods <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+</ul>
+<p>If the formal result type of such a method is <tt class="docutils literal"><span class="pre">id</span></tt> or protocol-qualified
+<tt class="docutils literal"><span class="pre">id</span></tt>, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type. In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:</p>
+<ul class="simple">
+<li>if it is a class method, and the receiver is a class name <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T*</span></tt>; otherwise</li>
+<li>if it is an instance method, and the receiver has type <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T</span></tt>; otherwise</li>
+<li>the message send expression has the normal result type of the method.</li>
+</ul>
+<p>This is a new rule of the Objective-C language and applies outside of ARC.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC’s automatic code emission is more prone than most code to signature
+errors, i.e. errors where a call was emitted against one method signature,
+but the implementing method has an incompatible signature. Having more
+precise type information helps drastically lower this risk, as well as
+catching a number of latent bugs.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="optimization">
+<span id="arc-optimization"></span><h2><a class="toc-backref" href="#id39">Optimization</a><a class="headerlink" href="#optimization" title="Permalink to this headline">¶</a></h2>
+<p>Within this section, the word <span class="arc-term">function</span> will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.</p>
+<p>This specification describes ARC as performing specific <tt class="docutils literal"><span class="pre">retain</span></tt> and
+<tt class="docutils literal"><span class="pre">release</span></tt> operations on retainable object pointers at specific
+points during the execution of a program. These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the <span class="arc-term">formal local retain history</span> of the
+object pointer. The corresponding actual sequence executed is the
+<cite>dynamic local retain history</cite>.</p>
+<p>However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general “as if”
+rule of C/C++ and the <a class="reference internal" href="#arc-objects-retains"><em>restrictions</em></a> on
+the implementation of <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">release</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Specifically, ARC is sometimes permitted to optimize <tt class="docutils literal"><span class="pre">release</span></tt>
+operations in ways which might cause an object to be deallocated
+before it would otherwise be. Without this, it would be almost
+impossible to eliminate any <tt class="docutils literal"><span class="pre">retain</span></tt>/<tt class="docutils literal"><span class="pre">release</span></tt> pairs. For
+example, consider the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">x</span> <span class="o">=</span> <span class="n">_ivar</span><span class="p">;</span>
+<span class="p">[</span><span class="n">x</span> <span class="n">foo</span><span class="p">];</span>
+</pre></div>
+</div>
+<p class="last">If we were not permitted in any event to shorten the lifetime of the
+object in <tt class="docutils literal"><span class="pre">x</span></tt>, then we would not be able to eliminate this retain
+and release unless we could prove that the message send could not
+modify <tt class="docutils literal"><span class="pre">_ivar</span></tt> (or deallocate <tt class="docutils literal"><span class="pre">self</span></tt>). Since message sends are
+opaque to the optimizer, this is not possible, and so ARC’s hands
+would be almost completely tied.</p>
+</div>
+<p>ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior. In particular, ARC makes no
+guarantees in the presence of race conditions.</p>
+<p>ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There is very little point in trying to guarantee correctness in the
+presence of race conditions. ARC does not have a stack-scanning
+garbage collector, and guaranteeing the atomicity of every load and
+store operation would be prohibitive and preclude a vast amount of
+optimization.</p>
+</div>
+<p>ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by <tt class="docutils literal"><span class="pre">__strong</span></tt> object invariants or +1 transfer
+conventions. For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a “balancing” retain.</p>
+<div class="section" id="object-liveness">
+<span id="arc-optimization-liveness"></span><h3><a class="toc-backref" href="#id40">Object liveness</a><a class="headerlink" href="#object-liveness" title="Permalink to this headline">¶</a></h3>
+<p>ARC may not allow a retainable object <tt class="docutils literal"><span class="pre">X</span></tt> to be deallocated at a
+time <tt class="docutils literal"><span class="pre">T</span></tt> in a computation history if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+<a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+imprecise lifetime semantics and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but
+before the next store to <tt class="docutils literal"><span class="pre">S</span></tt>, the computation history features a
+load from <tt class="docutils literal"><span class="pre">S</span></tt> and in some way depends on the value loaded, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is a value described as being released at the end of the
+current full-expression and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but before
+the end of the full-expression, the computation history depends
+on that value.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The intent of the second rule is to say that objects held in normal
+<tt class="docutils literal"><span class="pre">__strong</span></tt> local variables may be released as soon as the value in
+the variable is no longer being used: either the variable stops
+being used completely or a new value is stored in the variable.</p>
+<p class="last">The intent of the third rule is to say that return values may be
+released after they’ve been used.</p>
+</div>
+<p>A computation history depends on a pointer value <tt class="docutils literal"><span class="pre">P</span></tt> if it:</p>
+<ul class="simple">
+<li>performs a pointer comparison with <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>loads from <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>stores to <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> derived via pointer arithmetic
+from <tt class="docutils literal"><span class="pre">P</span></tt> (including an instance-variable or field access), or</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> loaded from <tt class="docutils literal"><span class="pre">P</span></tt>.</li>
+</ul>
+<p>Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases <tt class="docutils literal"><span class="pre">P</span></tt>. Furthermore, this
+dependency is not carried by values that are stored to objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The restrictions on dependency are intended to make this analysis
+feasible by an optimizer with only incomplete information about a
+program. Essentially, dependence is carried to “obvious” uses of a
+pointer. Merely passing a pointer argument to a function does not
+itself cause dependence, but since generally the optimizer will not
+be able to prove that the function doesn’t depend on that parameter,
+it will be forced to conservatively assume it does.</p>
+<p>Dependency propagates to values loaded from a pointer because those
+values might be invalidated by deallocating the object. For
+example, given the code <tt class="docutils literal"><span class="pre">__strong</span> <span class="pre">id</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">p->ivar;</span></tt>, ARC must not
+move the release of <tt class="docutils literal"><span class="pre">p</span></tt> to between the load of <tt class="docutils literal"><span class="pre">p->ivar</span></tt> and the
+retain of that value for storing into <tt class="docutils literal"><span class="pre">x</span></tt>.</p>
+<p>Dependency does not propagate through stores of dependent pointer
+values because doing so would allow dependency to outlive the
+full-expression which produced the original value. For example, the
+address of an instance variable could be written to some global
+location and then freely accessed during the lifetime of the local,
+or a function could return an inner pointer of an object and store
+it to a local. These cases would be potentially impossible to
+reason about and so would basically prevent any optimizations based
+on imprecise lifetime. There are also uncommon enough to make it
+reasonable to require the precise-lifetime annotation if someone
+really wants to rely on them.</p>
+<p class="last">Dependency does propagate through return values of pointer type.
+The compelling source of need for this rule is a property accessor
+which returns an un-autoreleased result; the calling function must
+have the chance to operate on the value, e.g. to retain it, before
+ARC releases the original pointer. Note again, however, that
+dependence does not survive a store, so ARC does not guarantee the
+continued validity of the return value past the end of the
+full-expression.</p>
+</div>
+</div>
+<div class="section" id="no-object-lifetime-extension">
+<span id="arc-optimization-object-lifetime"></span><h3><a class="toc-backref" href="#id41">No object lifetime extension</a><a class="headerlink" href="#no-object-lifetime-extension" title="Permalink to this headline">¶</a></h3>
+<p>If, in the formal computation history of the program, an object <tt class="docutils literal"><span class="pre">X</span></tt>
+has been deallocated by the time of an observable side-effect, then
+ARC must cause <tt class="docutils literal"><span class="pre">X</span></tt> to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>This rule is intended to prohibit ARC from observably extending the
+lifetime of a retainable object, other than as specified in this
+document. Together with the rule limiting the transformation of
+releases, this rule requires ARC to eliminate retains and release
+only in pairs.</p>
+<p class="last">ARC’s power to reorder the destruction of objects is critical to its
+ability to do any optimization, for essentially the same reason that
+it must retain the power to decrease the lifetime of an object.
+Unfortunately, while it’s generally poor style for the destruction
+of objects to have arbitrary side-effects, it’s certainly possible.
+Hence the caveat.</p>
+</div>
+</div>
+<div class="section" id="precise-lifetime-semantics">
+<span id="arc-optimization-precise"></span><h3><a class="toc-backref" href="#id42">Precise lifetime semantics</a><a class="headerlink" href="#precise-lifetime-semantics" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC maintains an invariant that a retainable object pointer held in
+a <tt class="docutils literal"><span class="pre">__strong</span></tt> object will be retained for the full formal lifetime of the
+object. Objects subject to this invariant have <span class="arc-term">precise lifetime
+semantics</span>.</p>
+<p>By default, local variables of automatic storage duration do not have precise
+lifetime semantics. Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Applying these precise-lifetime semantics strictly would be prohibitive.
+Many useful optimizations that might theoretically decrease the lifetime of
+an object would be rendered impossible. Essentially, it promises too much.</p>
+</div>
+<p>A local variable of retainable object owner type and automatic storage duration
+may be annotated with the <tt class="docutils literal"><span class="pre">objc_precise_lifetime</span></tt> attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Nonetheless, it is sometimes useful to be able to force an object to be
+released at a precise time, even if that object does not appear to be used.
+This is likely to be uncommon enough that the syntactic weight of explicitly
+requesting these semantics will not be burdensome, and may even make the code
+clearer.</p>
+</div>
+</div>
+</div>
+<div class="section" id="miscellaneous">
+<span id="arc-misc"></span><h2><a class="toc-backref" href="#id43">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="special-methods">
+<span id="arc-misc-special-methods"></span><h3><a class="toc-backref" href="#id44">Special methods</a><a class="headerlink" href="#special-methods" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="memory-management-methods">
+<span id="arc-misc-special-methods-retain"></span><h4><a class="toc-backref" href="#id45">Memory management methods</a><a class="headerlink" href="#memory-management-methods" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a method definition, message send, or
+<tt class="docutils literal"><span class="pre">@selector</span></tt> expression for any of the following selectors:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retainCount</span></tt></li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p><tt class="docutils literal"><span class="pre">retainCount</span></tt> is banned because ARC robs it of consistent semantics. The
+others were banned after weighing three options for how to deal with message
+sends:</p>
+<p><strong>Honoring</strong> them would work out very poorly if a programmer naively or
+accidentally tried to incorporate code written for manual retain/release code
+into an ARC program. At best, such code would do twice as much work as
+necessary; quite frequently, however, ARC and the explicit code would both
+try to balance the same retain, leading to crashes. The cost is losing the
+ability to perform “unrooted” retains, i.e. retains not logically
+corresponding to a strong reference in the object graph.</p>
+<p><strong>Ignoring</strong> them would badly violate user expectations about their code.
+While it <em>would</em> make it easier to develop code simultaneously for ARC and
+non-ARC, there is very little reason to do so except for certain library
+developers. ARC and non-ARC translation units share an execution model and
+can seamlessly interoperate. Within a translation unit, a developer who
+faithfully maintains their code in non-ARC mode is suffering all the
+restrictions of ARC for zero benefit, while a developer who isn’t testing the
+non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+it.</p>
+<p><strong>Banning</strong> them has the disadvantage of making it very awkward to migrate
+existing code to ARC. The best answer to that, given a number of other
+changes and restrictions in ARC, is to provide a specialized tool to assist
+users in that migration.</p>
+<p class="last">Implementing these methods was banned because they are too integral to the
+semantics of ARC; many tricks which worked tolerably under manual reference
+counting will misbehave if ARC performs an ephemeral extra retain or two. If
+absolutely required, it is still possible to implement them in non-ARC code,
+for example in a category; the implementations must obey the <a class="reference internal" href="#arc-objects-retains"><em>semantics</em></a> laid out elsewhere in this document.</p>
+</div>
+</div>
+<div class="section" id="dealloc">
+<span id="arc-misc-special-methods-dealloc"></span><h4><a class="toc-backref" href="#id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a><a class="headerlink" href="#dealloc" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a message send or <tt class="docutils literal"><span class="pre">@selector</span></tt>
+expression for the selector <tt class="docutils literal"><span class="pre">dealloc</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There are no legitimate reasons to call <tt class="docutils literal"><span class="pre">dealloc</span></tt> directly.</p>
+</div>
+<p>A class may provide a method definition for an instance method named
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>. This method will be called after the final <tt class="docutils literal"><span class="pre">release</span></tt> of the
+object but before it is deallocated or any of its instance variables are
+destroyed. The superclass’s implementation of <tt class="docutils literal"><span class="pre">dealloc</span></tt> will be called
+automatically when the method returns.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Even though ARC destroys instance variables automatically, there are still
+legitimate reasons to write a <tt class="docutils literal"><span class="pre">dealloc</span></tt> method, such as freeing
+non-retainable resources. Failing to call <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt> in such a
+method is nearly always a bug. Sometimes, the object is simply trying to
+prevent itself from being destroyed, but <tt class="docutils literal"><span class="pre">dealloc</span></tt> is really far too late
+for the object to be raising such objections. Somewhat more legitimately, an
+object may have been pool-allocated and should not be deallocated with
+<tt class="docutils literal"><span class="pre">free</span></tt>; for now, this can only be supported with a <tt class="docutils literal"><span class="pre">dealloc</span></tt>
+implementation outside of ARC. Such an implementation must be very careful
+to do all the other work that <tt class="docutils literal"><span class="pre">NSObject</span></tt>‘s <tt class="docutils literal"><span class="pre">dealloc</span></tt> would, which is
+outside the scope of this document to describe.</p>
+</div>
+<p>The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the <tt class="docutils literal"><span class="pre">dealloc</span></tt> method for the root class of the
+class. The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The traditional, non-ARC pattern for destroying instance variables is to
+destroy them immediately before calling <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt>. Unfortunately,
+message sends from the superclass are quite capable of reaching methods in
+the subclass, and those methods may well read or write to those instance
+variables. Making such message sends from dealloc is generally discouraged,
+since the subclass may well rely on other invariants that were broken during
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>, but it’s not so inescapably dangerous that we felt comfortable
+calling it undefined behavior. Therefore we chose to delay destroying the
+instance variables to a point at which message sends are clearly disallowed:
+the point at which the root class’s deallocation routines take over.</p>
+<p class="last">In most code, the difference is not observable. It can, however, be observed
+if an instance variable holds a strong reference to an object whose
+deallocation will trigger a side-effect which must be carefully ordered with
+respect to the destruction of the super class. Such code violates the design
+principle that semantically important behavior should be explicit. A simple
+fix is to clear the instance variable manually during <tt class="docutils literal"><span class="pre">dealloc</span></tt>; a more
+holistic solution is to move semantically important side-effects out of
+<tt class="docutils literal"><span class="pre">dealloc</span></tt> and into a separate teardown phase which can rely on working with
+well-formed objects.</p>
+</div>
+</div>
+</div>
+<div class="section" id="autoreleasepool">
+<span id="arc-misc-autoreleasepool"></span><h3><a class="toc-backref" href="#id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a><a class="headerlink" href="#autoreleasepool" title="Permalink to this headline">¶</a></h3>
+<p>To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C. It is
+written <tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> followed by a <em>compound-statement</em>, i.e. by a new
+scope delimited by curly braces. Upon entry to this block, the current state
+of the autorelease pool is captured. When the block is exited normally,
+whether by fallthrough or directed control flow (such as <tt class="docutils literal"><span class="pre">return</span></tt> or
+<tt class="docutils literal"><span class="pre">break</span></tt>), the autorelease pool is restored to the saved state, releasing all
+the objects in it. When the block is exited with an exception, the pool is not
+drained.</p>
+<p><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> may be used in non-ARC translation units, with equivalent
+semantics.</p>
+<p>A program is ill-formed if it refers to the <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> class.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are clearly important for the compiler to reason about, but
+it is far too much to expect the compiler to accurately reason about control
+dependencies between two calls. It is also very easy to accidentally forget
+to drain an autorelease pool when using the manual API, and this can
+significantly inflate the process’s high-water-mark. The introduction of a
+new scope is unfortunate but basically required for sane interaction with the
+rest of the language. Not draining the pool during an unwind is apparently
+required by the Objective-C exceptions implementation.</p>
+</div>
+</div>
+<div class="section" id="self">
+<span id="arc-misc-self"></span><h3><a class="toc-backref" href="#id48"><tt class="docutils literal"><span class="pre">self</span></tt></a><a class="headerlink" href="#self" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">self</span></tt> parameter variable of an Objective-C method is never actually
+retained by the implementation. It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.</p>
+<p>To make this safe, for Objective-C instance methods <tt class="docutils literal"><span class="pre">self</span></tt> is implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> unless the method is in the <a class="reference internal" href="#arc-family-semantics-init"><em>init family</em></a>. Further, <tt class="docutils literal"><span class="pre">self</span></tt> is <strong>always</strong> implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> within a class method.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The cost of retaining <tt class="docutils literal"><span class="pre">self</span></tt> in all methods was found to be prohibitive, as
+it tends to be live across calls, preventing the optimizer from proving that
+the retain and release are unnecessary — for good reason, as it’s quite
+possible in theory to cause an object to be deallocated during its execution
+without this retain and release. Since it’s extremely uncommon to actually
+do so, even unintentionally, and since there’s no natural way for the
+programmer to remove this retain/release pair otherwise (as there is for
+other parameters by, say, making the variable <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>), we
+chose to make this optimizing assumption and shift some amount of risk to the
+user.</p>
+</div>
+</div>
+<div class="section" id="fast-enumeration-iteration-variables">
+<span id="arc-misc-enumeration"></span><h3><a class="toc-backref" href="#id49">Fast enumeration iteration variables</a><a class="headerlink" href="#fast-enumeration-iteration-variables" title="Permalink to this headline">¶</a></h3>
+<p>If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+qualified with <tt class="docutils literal"><span class="pre">const</span> <span class="pre">__strong</span></tt> and objects encountered during the
+enumeration are not actually retained.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is an optimization made possible because fast enumeration loops promise
+to keep the objects retained during enumeration, and the collection itself
+cannot be synchronously modified. It can be overridden by explicitly
+qualifying the variable with <tt class="docutils literal"><span class="pre">__strong</span></tt>, which will make the variable
+mutable again and cause the loop to retain the objects it encounters.</p>
+</div>
+</div>
+<div class="section" id="blocks">
+<span id="arc-misc-blocks"></span><h3><a class="toc-backref" href="#id50">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">¶</a></h3>
+<p>The implicit <tt class="docutils literal"><span class="pre">const</span></tt> capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture. The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.</p>
+<p>The <a class="reference internal" href="#arc-ownership-inference"><em>inference</em></a> rules apply equally to
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables, which is a shift in semantics from non-ARC, where
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables did not implicitly retain during capture.</p>
+<p><tt class="docutils literal"><span class="pre">__block</span></tt> variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.</p>
+<p>With the exception of retains done as part of initializing a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+parameter variable or reading a <tt class="docutils literal"><span class="pre">__weak</span></tt> variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>. The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.</p>
+</div>
+<div class="section" id="exceptions">
+<span id="arc-misc-exceptions"></span><h3><a class="toc-backref" href="#id51">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
+<p>By default in Objective C, ARC is not exception-safe for normal releases:</p>
+<ul class="simple">
+<li>It does not end the lifetime of <tt class="docutils literal"><span class="pre">__strong</span></tt> variables when their scopes are
+abnormally terminated by an exception.</li>
+<li>It does not perform releases which would occur at the end of a
+full-expression if that full-expression throws an exception.</li>
+</ul>
+<p>A program may be compiled with the option <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> in order to
+enable these, or with the option <tt class="docutils literal"><span class="pre">-fno-objc-arc-exceptions</span></tt> to explicitly
+disable them, with the last such argument “winning”.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The standard Cocoa convention is that exceptions signal programmer error and
+are not intended to be recovered from. Making code exceptions-safe by
+default would impose severe runtime and code size penalties on code that
+typically does not actually care about exceptions safety. Therefore,
+ARC-generated code leaks by default on exceptions, which is just fine if the
+process is going to be immediately terminated anyway. Programs which do care
+about recovering from exceptions should enable the option.</p>
+</div>
+<p>In Objective-C++, <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> is enabled by default.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+introduces. C++ programmers who have not already disabled exceptions are
+much more likely to actual require exception-safety.</p>
+</div>
+<p>ARC does end the lifetimes of <tt class="docutils literal"><span class="pre">__weak</span></tt> objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The consequence of a local <tt class="docutils literal"><span class="pre">__weak</span></tt> object not being destroyed is very
+likely to be corruption of the Objective-C runtime, so we want to be safer
+here. Of course, potentially massive leaks are about as likely to take down
+the process as this corruption is if the program does try to recover from
+exceptions.</p>
+</div>
+</div>
+<div class="section" id="interior-pointers">
+<span id="arc-misc-interior"></span><h3><a class="toc-backref" href="#id52">Interior pointers</a><a class="headerlink" href="#interior-pointers" title="Permalink to this headline">¶</a></h3>
+<p>An Objective-C method returning a non-retainable pointer may be annotated with
+the <tt class="docutils literal"><span class="pre">objc_returns_inner_pointer</span></tt> attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed. When such a message is sent to an
+object, the object’s lifetime will be extended until at least the earliest of:</p>
+<ul class="simple">
+<li>the last use of the returned pointer, or any pointer derived from it, in the
+calling function or</li>
+<li>the autorelease pool is restored to a previous state.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Rationale: not all memory and resources are managed with reference counts; it
+is common for objects to manage private resources in their own, private way.
+Typically these resources are completely encapsulated within the object, but
+some classes offer their users direct access for efficiency. If ARC is not
+aware of methods that return such “interior” pointers, its optimizations can
+cause the owning object to be reclaimed too soon. This attribute informs ARC
+that it must tread lightly.</p>
+<p class="last">The extension rules are somewhat intentionally vague. The autorelease pool
+limit is there to permit a simple implementation to simply retain and
+autorelease the receiver. The other limit permits some amount of
+optimization. The phrase “derived from” is intended to encompass the results
+both of pointer transformations, such as casts and arithmetic, and of loading
+from such derived pointers; furthermore, it applies whether or not such
+derivations are applied directly in the calling code or by other utility code
+(for example, the C library routine <tt class="docutils literal"><span class="pre">strchr</span></tt>). However, the implementation
+never need account for uses after a return from the code which calls the
+method returning an interior pointer.</p>
+</div>
+<p>As an exception, no extension is required if the receiver is loaded directly
+from a <tt class="docutils literal"><span class="pre">__strong</span></tt> object with <a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Implicit autoreleases carry the risk of significantly inflating memory use,
+so it’s important to provide users a way of avoiding these autoreleases.
+Tying this to precise lifetime semantics is ideal, as for local variables
+this requires a very explicit annotation, which allows ARC to trust the user
+with good cheer.</p>
+</div>
+</div>
+<div class="section" id="c-retainable-pointer-types">
+<span id="arc-misc-c-retainable"></span><h3><a class="toc-backref" href="#id53">C retainable pointer types</a><a class="headerlink" href="#c-retainable-pointer-types" title="Permalink to this headline">¶</a></h3>
+<p>A type is a <span class="arc-term">C retainable pointer type</span> if it is a pointer to
+(possibly qualified) <tt class="docutils literal"><span class="pre">void</span></tt> or a pointer to a (possibly qualifier) <tt class="docutils literal"><span class="pre">struct</span></tt>
+or <tt class="docutils literal"><span class="pre">class</span></tt> type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC does not manage pointers of CoreFoundation type (or any of the related
+families of retainable C pointers which interoperate with Objective-C for
+retain/release operation). In fact, ARC does not even know how to
+distinguish these types from arbitrary C pointer types. The intent of this
+concept is to filter out some obviously non-object types while leaving a hook
+for later tightening if a means of exhaustively marking CF types is made
+available.</p>
+</div>
+<div class="section" id="auditing-of-c-retainable-pointer-interfaces">
+<span id="arc-misc-c-retainable-audit"></span><h4><a class="toc-backref" href="#id54">Auditing of C retainable pointer interfaces</a><a class="headerlink" href="#auditing-of-c-retainable-pointer-interfaces" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>A C function may be marked with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:</p>
+<ul class="simple">
+<li>A parameter of C retainable pointer type is assumed to not be consumed
+unless it is marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, and</li>
+<li>A result of C retainable pointer type is assumed to not be returned retained
+unless the function is either marked <tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> or it follows
+the create/copy naming convention and is not marked
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt>.</li>
+</ul>
+<p>A function obeys the <span class="arc-term">create/copy</span> naming convention if its name
+contains as a substring:</p>
+<ul class="simple">
+<li>either “Create” or “Copy” not followed by a lowercase letter, or</li>
+<li>either “create” or “copy” not followed by a lowercase letter and
+not preceded by any letter, whether uppercase or lowercase.</li>
+</ul>
+<p>A second attribute, <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>, signifies that a function’s
+transfer semantics cannot be accurately captured using any of these
+annotations. A program is ill-formed if it annotates the same function with
+both <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> and <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>.</p>
+<p>A pragma is provided to facilitate the mass annotation of interfaces:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#pragma clang arc_cf_code_audited begin</span>
+<span class="p">...</span>
+<span class="cp">#pragma clang arc_cf_code_audited end</span>
+</pre></div>
+</div>
+<p>All C functions declared within the extent of this pragma are treated as if
+annotated with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> attribute unless they otherwise have
+the <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt> attribute. The pragma is accepted in all language
+modes. A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.</p>
+<p>It is possible to test for all the features in this section with
+<tt class="docutils literal"><span class="pre">__has_feature(arc_cf_code_audited)</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">A significant inconvenience in ARC programming is the necessity of
+interacting with APIs based around C retainable pointers. These features are
+designed to make it relatively easy for API authors to quickly review and
+annotate their interfaces, in turn improving the fidelity of tools such as
+the static analyzer and ARC. The single-file restriction on the pragma is
+designed to eliminate the risk of accidentally annotating some other header’s
+interfaces.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="runtime-support">
+<span id="arc-runtime"></span><h2><a class="toc-backref" href="#id55">Runtime support</a><a class="headerlink" href="#runtime-support" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler. This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the “Itanium” generic ABI for C++.</p>
+<p>Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a <tt class="docutils literal"><span class="pre">__weak</span></tt> object is inadequately
+aligned for an object of type <tt class="docutils literal"><span class="pre">id</span></tt>. The other qualifiers may be used on
+explicitly under-aligned memory.</p>
+<p>The runtime tracks <tt class="docutils literal"><span class="pre">__weak</span></tt> objects which holds non-null values. It is
+undefined behavior to direct modify a <tt class="docutils literal"><span class="pre">__weak</span></tt> object which is being tracked
+by the runtime except through an
+<a class="reference internal" href="#arc-runtime-objc-storeweak"><em>objc_storeWeak</em></a>,
+<a class="reference internal" href="#arc-runtime-objc-destroyweak"><em>objc_destroyWeak</em></a>, or
+<a class="reference internal" href="#arc-runtime-objc-moveweak"><em>objc_moveWeak</em></a> call.</p>
+<p>The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Several of these functions are semantically equivalent to a message send; we
+emit calls to C functions instead because:</p>
+<ul class="simple">
+<li>the machine code to do so is significantly smaller,</li>
+<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
+<li>a sufficient sophisticated runtime may be able to avoid the message send in
+common cases.</li>
+</ul>
+<p class="last">Several other of these functions are “fused” operations which can be
+described entirely in terms of other operations. We use the fused operations
+primarily as a code-size optimization, although in some cases there is also a
+real potential for avoiding redundant operations in the runtime.</p>
+</div>
+<div class="section" id="arc-runtime-objc-autorelease">
+<span id="id-objc-autorelease-id-value"></span><h3><a class="toc-backref" href="#id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+<tt class="docutils literal"><span class="pre">autorelease</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpop-void-pool">
+<span id="arc-runtime-objc-autoreleasepoolpop"></span><h3><a class="toc-backref" href="#id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpop-void-pool" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">pool</span></tt> is the result of a previous call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasepoolpush"><em>objc_autoreleasePoolPush</em></a> on the
+current thread, where neither <tt class="docutils literal"><span class="pre">pool</span></tt> nor any enclosing pool have previously
+been popped.</p>
+<p>Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing <tt class="docutils literal"><span class="pre">pool</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpush-void">
+<span id="arc-runtime-objc-autoreleasepoolpush"></span><h3><a class="toc-backref" href="#id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpush-void" title="Permalink to this headline">¶</a></h3>
+<p>Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque “handle” to it.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While the interface is described as an explicit hierarchy of pools, the rules
+allow the implementation to just keep a stack of objects, using the stack
+depth as the opaque pool handle.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-autoreleasereturnvalue">
+<span id="id-objc-autoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+<a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue"><em>objc_retainAutoreleasedReturnValue</em></a> for the same object in an
+enclosing call frame. If this is not possible, the object is autoreleased as
+above.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-copyweak-id-dest-id-src">
+<span id="arc-runtime-objc-copyweak"></span><h3><a class="toc-backref" href="#id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-copyweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object. <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime. Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_copyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="kt">id</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">objc_release</span><span class="p">(</span><span class="n">objc_initWeak</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">src</span><span class="p">)));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-destroyweak-id-object">
+<span id="arc-runtime-objc-destroyweak"></span><h3><a class="toc-backref" href="#id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#void-objc-destroyweak-id-object" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">object</span></tt> is unregistered as a weak object, if it ever was. The current value
+of <tt class="docutils literal"><span class="pre">object</span></tt> is left unspecified; otherwise, equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_destroyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-initweak">
+<span id="id-objc-initweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-initweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which has not been registered as
+a <tt class="docutils literal"><span class="pre">__weak</span></tt> object. <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is zero-initialized. Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is
+registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object pointing to <tt class="docutils literal"><span class="pre">value</span></tt>. Equivalent to the
+following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_initWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="nb">nil</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-loadweak">
+<span id="id-objc-loadweak-id-object"></span><h3><a class="toc-backref" href="#id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it. Otherwise returns null. Equivalent to
+the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_loadWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">object</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Loading weak references would be inherently prone to race conditions without
+the retain.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-loadweakretained">
+<span id="id-objc-loadweakretained-id-object"></span><h3><a class="toc-backref" href="#id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweakretained" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains
+that value and returns it. Otherwise returns null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-moveweak-id-dest-id-src">
+<span id="arc-runtime-objc-moveweak"></span><h3><a class="toc-backref" href="#id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-moveweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object. <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime. <tt class="docutils literal"><span class="pre">src</span></tt> may then be left in its original state, in which
+case this call is equivalent to <a class="reference internal" href="#arc-runtime-objc-copyweak"><em>objc_copyWeak</em></a>, or it may be left as null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-release-id-value">
+<span id="arc-runtime-objc-release"></span><h3><a class="toc-backref" href="#id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#void-objc-release-id-value" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it performs a
+release operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">release</span></tt>
+message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retain">
+<span id="id-objc-retain-id-value"></span><h3><a class="toc-backref" href="#id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retain" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it performs a retain
+operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautorelease">
+<span id="id-objc-retainautorelease-id-value"></span><h3><a class="toc-backref" href="#id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it performs a retain
+operation followed by an autorelease operation. Equivalent to the following
+code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutorelease</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasereturnvalue">
+<span id="id-objc-retainautoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it performs a retain
+operation followed by the operation described in
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a>.
+Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutoreleaseReturnValue</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">objc_autoreleaseReturnValue</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasedreturnvalue">
+<span id="id-objc-retainautoreleasedreturnvalue-id-value"></span><h3><a class="toc-backref" href="#id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasedreturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a> on
+<tt class="docutils literal"><span class="pre">value</span></tt> in a recently-called function or something it calls. If that fails,
+it performs a retain operation exactly like <a class="reference internal" href="#arc-runtime-objc-retain"><em>objc_retain</em></a>.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainblock">
+<span id="id-objc-retainblock-id-value"></span><h3><a class="toc-backref" href="#id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainblock" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid block object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect. Otherwise, if the block pointed
+to by <tt class="docutils literal"><span class="pre">value</span></tt> is still on the stack, it is copied to the heap and the address
+of the copy is returned. Otherwise a retain operation is performed on the
+block exactly as if it had been sent the <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-storestrong">
+<span id="id-objc-storestrong-id-object-id-value"></span><h3><a class="toc-backref" href="#id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storestrong" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object which is
+adequately aligned for a pointer. <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid
+object.</p>
+<p>Performs the complete sequence for assigning to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of
+non-block type <a class="footnote-reference" href="#id3" id="id2">[*]</a>. Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_storeStrong</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">value</span> <span class="n">retain</span><span class="p">];</span>
+ <span class="kt">id</span> <span class="n">oldValue</span> <span class="o">=</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
+ <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="n">value</span><span class="p">;</span>
+ <span class="p">[</span><span class="n">oldValue</span> <span class="n">release</span><span class="p">];</span>
+ <span class="k">return</span> <span class="n">value</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[*]</a></td><td>This does not imply that a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of block type is an
+invalid argument to this function. Rather it implies that an <tt class="docutils literal"><span class="pre">objc_retain</span></tt>
+and not an <tt class="docutils literal"><span class="pre">objc_retainBlock</span></tt> operation will be emitted if the argument is
+a block.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="arc-runtime-objc-storeweak">
+<span id="id-objc-storeweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storeweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object. <tt class="docutils literal"><span class="pre">value</span></tt> is null or a
+pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is assigned null and unregistered as a <tt class="docutils literal"><span class="pre">__weak</span></tt>
+object. Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object or has its
+registration updated to point to <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AttributeReference.html">Attributes in Clang</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,913 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Block Implementation Specification — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="next" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" />
+ <link rel="prev" title="Language Specification for Blocks" href="BlockLanguageSpec.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>Block Implementation Specification</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="block-implementation-specification">
+<h1>Block Implementation Specification<a class="headerlink" href="#block-implementation-specification" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#history" id="id1">History</a></li>
+<li><a class="reference internal" href="#high-level" id="id2">High Level</a></li>
+<li><a class="reference internal" href="#imported-variables" id="id3">Imported Variables</a><ul>
+<li><a class="reference internal" href="#imported-const-copy-variables" id="id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a></li>
+<li><a class="reference internal" href="#imported-const-copy-of-block-reference" id="id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><ul>
+<li><a class="reference internal" href="#importing-attribute-nsobject-variables" id="id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#imported-block-marked-variables" id="id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><ul>
+<li><a class="reference internal" href="#layout-of-block-marked-variables" id="id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a></li>
+<li><a class="reference internal" href="#access-to-block-variables-from-within-its-lexical-scope" id="id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a></li>
+<li><a class="reference internal" href="#importing-block-variables-into-blocks" id="id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a></li>
+<li><a class="reference internal" href="#importing-attribute-nsobject-block-variables" id="id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a></li>
+<li><a class="reference internal" href="#block-escapes" id="id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a></li>
+<li><a class="reference internal" href="#nesting" id="id13">Nesting</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-extensions-to-blocks" id="id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><ul>
+<li><a class="reference internal" href="#importing-objects" id="id15">Importing Objects</a></li>
+<li><a class="reference internal" href="#blocks-as-objects" id="id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a></li>
+<li><a class="reference internal" href="#weak-block-support" id="id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-support" id="id18">C++ Support</a></li>
+<li><a class="reference internal" href="#runtime-helper-functions" id="id19">Runtime Helper Functions</a></li>
+<li><a class="reference internal" href="#copyright" id="id20">Copyright</a></li>
+</ul>
+</div>
+<div class="section" id="history">
+<h2><a class="toc-backref" href="#id1">History</a><a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/7/14 - created.</li>
+<li>2008/8/21 - revised, C++.</li>
+<li>2008/9/24 - add <tt class="docutils literal"><span class="pre">NULL</span></tt> <tt class="docutils literal"><span class="pre">isa</span></tt> field to <tt class="docutils literal"><span class="pre">__block</span></tt> storage.</li>
+<li>2008/10/1 - revise block layout to use a <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure.</li>
+<li>2008/10/6 - revise block layout to use an unsigned long int flags.</li>
+<li>2008/10/28 - specify use of <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> for all “Object” types in helper functions.</li>
+<li>2008/10/30 - revise new layout to have invoke function in same place.</li>
+<li>2008/10/30 - add <tt class="docutils literal"><span class="pre">__weak</span></tt> support.</li>
+<li>2010/3/16 - rev for stret return, signature field.</li>
+<li>2010/4/6 - improved wording.</li>
+<li>2013/1/6 - improved wording and converted to rst.</li>
+</ul>
+<p>This document describes the Apple ABI implementation specification of Blocks.</p>
+<p>The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.</p>
+<p>Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.</p>
+</div>
+<div class="section" id="high-level">
+<h2><a class="toc-backref" href="#id2">High Level</a><a class="headerlink" href="#high-level" title="Permalink to this headline">¶</a></h2>
+<p>The ABI of <tt class="docutils literal"><span class="pre">Blocks</span></tt> consist of their layout and the runtime functions required
+by the compiler. A <tt class="docutils literal"><span class="pre">Block</span></tt> consists of a structure of the following form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Block_literal_1</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="p">...);</span>
+ <span class="k">struct</span> <span class="n">Block_descriptor_1</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span> <span class="c1">// NULL</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">size</span><span class="p">;</span> <span class="c1">// sizeof(struct Block_literal_1)</span>
+ <span class="c1">// optional helper functions</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span> <span class="c1">// IFF (1<<25)</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span> <span class="c1">// IFF (1<<25)</span>
+ <span class="c1">// required ABI.2010.3.16</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">signature</span><span class="p">;</span> <span class="c1">// IFF (1<<30)</span>
+ <span class="p">}</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+ <span class="c1">// imported variables</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The following flags bits are in use thusly for a possible ABI.2010.3.16:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">BLOCK_HAS_COPY_DISPOSE</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">25</span><span class="p">),</span>
+ <span class="n">BLOCK_HAS_CTOR</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">26</span><span class="p">),</span> <span class="c1">// helpers have C++ code</span>
+ <span class="n">BLOCK_IS_GLOBAL</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">28</span><span class="p">),</span>
+ <span class="n">BLOCK_HAS_STRET</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">29</span><span class="p">),</span> <span class="c1">// IFF BLOCK_HAS_SIGNATURE</span>
+ <span class="n">BLOCK_HAS_SIGNATURE</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">30</span><span class="p">),</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">flags</span> <span class="o">&</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+ <span class="k">case</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+ <span class="k">case</span> <span class="p">(</span><span class="mi">2</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">regular</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span>
+ <span class="k">case</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">stret</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span><span class="p">,</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The signature field is not always populated.</p>
+<p>The following discussions are presented as 10.6.ABI otherwise.</p>
+<p><tt class="docutils literal"><span class="pre">Block</span></tt> literals may occur within functions where the structure is created in
+stack local memory. They may also appear as initialization expressions for
+<tt class="docutils literal"><span class="pre">Block</span></tt> variables of global or <tt class="docutils literal"><span class="pre">static</span></tt> local variables.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is evaluated the stack based structure is
+initialized as follows:</p>
+<ol class="arabic simple">
+<li>A <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure is declared and initialized as follows:</li>
+</ol>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">invoke</span></tt> function pointer is set to a function that takes the
+<tt class="docutils literal"><span class="pre">Block</span></tt> structure as its first argument and the rest of the arguments (if
+any) to the <tt class="docutils literal"><span class="pre">Block</span></tt> and executes the <tt class="docutils literal"><span class="pre">Block</span></tt> compound statement.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is set to the size of the following <tt class="docutils literal"><span class="pre">Block</span></tt> literal
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function pointers are set to
+respective helper functions if they are required by the <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+</div></blockquote>
+<ol class="arabic" start="2">
+<li><p class="first">A stack (or global) <tt class="docutils literal"><span class="pre">Block</span></tt> literal data structure is created and
+initialized as follows:</p>
+<p>a. The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to the address of the external
+<tt class="docutils literal"><span class="pre">_NSConcreteStackBlock</span></tt>, which is a block of uninitialized memory supplied
+in <tt class="docutils literal"><span class="pre">libSystem</span></tt>, or <tt class="docutils literal"><span class="pre">_NSConcreteGlobalBlock</span></tt> if this is a static or file
+level <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to zero unless there are variables imported
+into the <tt class="docutils literal"><span class="pre">Block</span></tt> that need helper functions for program level
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> operations, in which case the
+(1<<25) flags bit is set.</p>
+</li>
+</ol>
+<p>As an example, the <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>would cause the following to be created on a 32-bit system:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_1</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_1</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span><span class="p">),</span> <span class="n">__block_invoke_1</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and where the <tt class="docutils literal"><span class="pre">Block</span></tt> literal itself appears:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_1</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> imports other <tt class="docutils literal"><span class="pre">Block</span></tt> references, <tt class="docutils literal"><span class="pre">const</span></tt> copies of other
+variables, and variables marked <tt class="docutils literal"><span class="pre">__block</span></tt>. In Objective-C, variables may
+additionally be objects.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is used as the initial value of a global
+or <tt class="docutils literal"><span class="pre">static</span></tt> local variable, it is initialized as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">__block_literal_1</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteGlobalBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">28</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_1</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the <tt class="docutils literal"><span class="pre">flags</span></tt> field, and otherwise it is the same as for
+stack based <tt class="docutils literal"><span class="pre">Block</span></tt> literals. This is an optimization that can be used for
+any <tt class="docutils literal"><span class="pre">Block</span></tt> literal that imports no <tt class="docutils literal"><span class="pre">const</span></tt> or <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+variables.</p>
+</div>
+<div class="section" id="imported-variables">
+<h2><a class="toc-backref" href="#id3">Imported Variables</a><a class="headerlink" href="#imported-variables" title="Permalink to this headline">¶</a></h2>
+<p>Variables of <tt class="docutils literal"><span class="pre">auto</span></tt> storage class are imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies. Variables
+of <tt class="docutils literal"><span class="pre">__block</span></tt> storage class are imported as a pointer to an enclosing data
+structure. Global variables are simply referenced and not considered as
+imported.</p>
+<div class="section" id="imported-const-copy-variables">
+<h3><a class="toc-backref" href="#id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a><a class="headerlink" href="#imported-const-copy-variables" title="Permalink to this headline">¶</a></h3>
+<p>Automatic storage variables not marked with <tt class="docutils literal"><span class="pre">__block</span></tt> are imported as
+<tt class="docutils literal"><span class="pre">const</span></tt> copies.</p>
+<p>The simplest example is that of importing a variable of type <tt class="docutils literal"><span class="pre">int</span></tt>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="n">x</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+<span class="n">vv</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>which would be compiled to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+ <span class="k">const</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_2</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_2</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span><span class="p">)</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="n">__block_literal_2</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_2</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_2</span><span class="p">,</span>
+ <span class="n">x</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>In summary, scalars, structures, unions, and function pointers are generally
+imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies with no need for helper functions.</p>
+</div>
+<div class="section" id="imported-const-copy-of-block-reference">
+<h3><a class="toc-backref" href="#id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><a class="headerlink" href="#imported-const-copy-of-block-reference" title="Permalink to this headline">¶</a></h3>
+<p>The first case where copy and dispose helper functions are required is for the
+case of when a <tt class="docutils literal"><span class="pre">Block</span></tt> itself is imported. In this case both a
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> function and a <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function are needed. The
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the <tt class="docutils literal"><span class="pre">Block</span></tt>. The
+runtime functions are all described in <a class="reference internal" href="#runtimehelperfunctions"><em>Runtime Helper Functions</em></a>.</p>
+<p>A quick example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">existingBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">existingBlock</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">vv</span><span class="p">();</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="p">{</span>
+ <span class="p">...;</span> <span class="c1">// existing block</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="o">*</span><span class="k">const</span> <span class="n">existingBlock</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// was _Block_destroy</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_4</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_4</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="mi">0</span><span class="p">,</span>
+ <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span><span class="p">),</span>
+ <span class="n">__block_copy_4</span><span class="p">,</span>
+ <span class="n">__block_dispose_4</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and where said <tt class="docutils literal"><span class="pre">Block</span></tt> is used:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span>
+ <span class="n">__block_invoke_4</span><span class="p">,</span>
+ <span class="o">&</span> <span class="n">__block_descriptor_4</span>
+ <span class="n">existingBlock</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="importing-attribute-nsobject-variables">
+<h4><a class="toc-backref" href="#id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-variables" title="Permalink to this headline">¶</a></h4>
+<p>GCC introduces <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> on structure pointers to mean “this
+is an object”. This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, <tt class="docutils literal"><span class="pre">CFArrayRef</span></tt>,
+etc. When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated. The copy helper functions generated by the compiler should use the
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> runtime helper function and in the dispose helper the
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> runtime helper function should be called.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">Block</span></tt> foo in the following:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Opaque</span> <span class="o">*</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">NSObject</span><span class="p">))</span> <span class="n">objectPointer</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="p">...</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">foo</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">CFPrint</span><span class="p">(</span><span class="n">objectPointer</span><span class="p">);</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>would have the following helper functions generated:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">__block_copy_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="imported-block-marked-variables">
+<h3><a class="toc-backref" href="#id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#imported-block-marked-variables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="layout-of-block-marked-variables">
+<h4><a class="toc-backref" href="#id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#layout-of-block-marked-variables" title="Permalink to this headline">¶</a></h4>
+<p>The compiler must embed variables that are marked <tt class="docutils literal"><span class="pre">__block</span></tt> in a specialized
+structure of the form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">Block_byref</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Variables of certain types require helper functions for when <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> are performed upon a referencing <tt class="docutils literal"><span class="pre">Block</span></tt>. At the “C”
+level only variables that are of type <tt class="docutils literal"><span class="pre">Block</span></tt> or ones that have
+<tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> marked require helper functions. In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="c1">// helper functions called via Block_copy() and Block_release()</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
+ <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The structure is initialized such that:</p>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer is set to the beginning of its enclosing
+structure.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is initialized to the total size of the enclosing
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to either 0 if no helper functions are needed
+or (1<<25) if they are.</p>
+<ol class="loweralpha simple" start="4">
+<li>The helper functions are initialized (if present).</li>
+<li>The variable itself is set to its initial value.</li>
+<li>The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to <tt class="docutils literal"><span class="pre">NULL</span></tt>.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="access-to-block-variables-from-within-its-lexical-scope">
+<h4><a class="toc-backref" href="#id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a><a class="headerlink" href="#access-to-block-variables-from-within-its-lexical-scope" title="Permalink to this headline">¶</a></h4>
+<p>In order to “move” the variable to the heap upon a <tt class="docutils literal"><span class="pre">copy_helper</span></tt> operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="n">i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would be rewritten to be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="mi">10</span> <span class="p">};</span>
+
+<span class="n">i</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the case of a <tt class="docutils literal"><span class="pre">Block</span></tt> reference variable being marked <tt class="docutils literal"><span class="pre">__block</span></tt> the
+helper code generated must use the <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> routines supplied by the runtime to make the
+copies. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="kt">void</span> <span class="p">(</span><span class="n">voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">blockA</span><span class="p">;</span>
+<span class="n">voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would translate into:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">captured_voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_keep_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_dispose_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_destroy(param->captured_voidBlock, 0);</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">)}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="n">voidBlock</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">voidBlock</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">),</span>
+ <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_keep_helper</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_dispose_helper</span><span class="p">,</span>
+ <span class="p">.</span><span class="n">captured_voidBlock</span><span class="o">=</span><span class="n">blockA</span> <span class="p">)};</span>
+
+<span class="n">voidBlock</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-block-variables-into-blocks">
+<h4><a class="toc-backref" href="#id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#importing-block-variables-into-blocks" title="Permalink to this headline">¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> that uses a <tt class="docutils literal"><span class="pre">__block</span></tt> variable in its compound statement body must
+import the variable and emit <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> helper
+functions that, in turn, call back into the runtime to actually copy or release
+the <tt class="docutils literal"><span class="pre">byref</span></tt> data block using the functions <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+<p>For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// set to NULL</span>
+ <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+ <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">};</span>
+
+
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">i_holder</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">_block</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_byref_assign_copy(&dst->captured_i, src->captured_i);</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_byref_release(src->captured_i);</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">)</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">i</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">)</span> <span class="p">)};</span>
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_5</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+ <span class="mi">2</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-attribute-nsobject-block-variables">
+<h4><a class="toc-backref" href="#id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-block-variables" title="Permalink to this headline">¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">__block</span></tt> variable that is also marked <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> should
+have <tt class="docutils literal"><span class="pre">byref_keep</span></tt> and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt> helper functions that use
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and <tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+</div>
+<div class="section" id="block-escapes">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a><a class="headerlink" href="#block-escapes" title="Permalink to this headline">¶</a></h4>
+<p>Because <tt class="docutils literal"><span class="pre">Blocks</span></tt> referencing <tt class="docutils literal"><span class="pre">__block</span></tt> variables may have <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+performed upon them the underlying storage for the variables may move to the
+heap. In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required. Otherwise
+the compiler must issue a call to potentially release any heap storage for
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables at all escapes or terminations of their scope. The call
+should be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">&</span><span class="n">_block_byref_foo</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nesting">
+<h4><a class="toc-backref" href="#id13">Nesting</a><a class="headerlink" href="#nesting" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">Blocks</span></tt> may contain <tt class="docutils literal"><span class="pre">Block</span></tt> literal expressions. Any variables used within
+inner blocks are imported into all enclosing <tt class="docutils literal"><span class="pre">Block</span></tt> scopes even if the
+variables are not used. This includes <tt class="docutils literal"><span class="pre">const</span></tt> imports as well as <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables.</p>
+</div>
+</div>
+</div>
+<div class="section" id="objective-c-extensions-to-blocks">
+<h2><a class="toc-backref" href="#id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#objective-c-extensions-to-blocks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="importing-objects">
+<h3><a class="toc-backref" href="#id15">Importing Objects</a><a class="headerlink" href="#importing-objects" title="Permalink to this headline">¶</a></h3>
+<p>Objects should be treated as <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables; all
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt>, <tt class="docutils literal"><span class="pre">dispose_helper</span></tt>, <tt class="docutils literal"><span class="pre">byref_keep</span></tt>, and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt>
+helper functions should use <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>. There should be no code generated that uses
+<tt class="docutils literal"><span class="pre">*-retain</span></tt> or <tt class="docutils literal"><span class="pre">*-release</span></tt> methods.</p>
+</div>
+<div class="section" id="blocks-as-objects">
+<h3><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a><a class="headerlink" href="#blocks-as-objects" title="Permalink to this headline">¶</a></h3>
+<p>The compiler will treat <tt class="docutils literal"><span class="pre">Blocks</span></tt> as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.</p>
+</div>
+<div class="section" id="weak-block-support">
+<h3><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a><a class="headerlink" href="#weak-block-support" title="Permalink to this headline">¶</a></h3>
+<p>Objective-C (and Objective-C++) support the <tt class="docutils literal"><span class="pre">__weak</span></tt> attribute on <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables. Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions <tt class="docutils literal"><span class="pre">objc_assign_weak</span></tt> and <tt class="docutils literal"><span class="pre">objc_read_weak</span></tt>. Both
+should continue to be used for all reads and writes of <tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt>
+variables:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">block</span><span class="o">-></span><span class="n">byref_i</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is stored in a <tt class="docutils literal"><span class="pre">_block_byref_foo</span></tt> structure and the
+<tt class="docutils literal"><span class="pre">Block</span></tt> has copy and dispose helpers for this structure that call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In turn, the <tt class="docutils literal"><span class="pre">block_byref</span></tt> copy support helpers distinguish between whether
+the <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a <tt class="docutils literal"><span class="pre">Block</span></tt> or not and should either call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as an object or:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as a <tt class="docutils literal"><span class="pre">Block</span></tt>.</p>
+<p>A full example follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="n">__weak</span> <span class="n">id</span> <span class="n">obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">obj</span> <span class="n">somemessage</span><span class="p">];</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// uninitialized</span>
+ <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span> <span class="c1">//refcount;</span>
+ <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+ <span class="n">id</span> <span class="n">captured_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_destroy(param->captured_obj, 0);</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>for the block <tt class="docutils literal"><span class="pre">byref</span></tt> part and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">byref_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">[</span><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">_block</span><span class="o">-></span><span class="n">byref_obj</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">)</span> <span class="n">somemessage</span><span class="p">];</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);</span>
+ <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">//_Block_byref_release(src->byref_obj);</span>
+ <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">),</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and within the compound statement:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">truct</span> <span class="n">_block_byref_obj</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">obj</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_obj</span><span class="p">),</span>
+ <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_obj_keep</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_obj_dispose</span><span class="p">,</span>
+ <span class="p">.</span><span class="n">captured_obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span> <span class="p">)};</span>
+
+<span class="n">truct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_5</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">obj</span><span class="p">,</span> <span class="c1">// a reference to the on-stack structure containing "captured_obj"</span>
+<span class="p">};</span>
+
+
+<span class="n">functioncall</span><span class="p">(</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="c-support">
+<h2><a class="toc-backref" href="#id18">C++ Support</a><a class="headerlink" href="#c-support" title="Permalink to this headline">¶</a></h2>
+<p>Within a block stack based C++ objects are copied into <tt class="docutils literal"><span class="pre">const</span></tt> copies using
+the copy constructor. It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor. In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit. The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all <tt class="docutils literal"><span class="pre">const</span></tt> constructed copies, and similarly
+should call the destructor in the destroy routine.</p>
+<p>As an example, suppose a C++ class <tt class="docutils literal"><span class="pre">FOO</span></tt> existed with a copy constructor.
+Within a code block a stack version of a <tt class="docutils literal"><span class="pre">FOO</span></tt> object is declared and used
+within a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+ <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">block</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span> <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The compiler would synthesize:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+ <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+ <span class="k">const</span> <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_literal_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_10</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span><span class="p">),</span> <span class="n">__block_copy_10</span><span class="p">,</span> <span class="n">__block_dispose_10</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and the code would be:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+ <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+ <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// default constructor</span>
+ <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+ <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">26</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+ <span class="n">__block_invoke_10</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">__block_descriptor_10</span><span class="p">,</span>
+ <span class="p">};</span>
+ <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// const copy into stack version</span>
+ <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">&</span><span class="n">block</span> <span class="o">=</span> <span class="o">&</span><span class="n">_block_literal</span><span class="p">;</span> <span class="c1">// assign literal to block variable</span>
+ <span class="n">block</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">block</span><span class="p">);</span> <span class="c1">// invoke block</span>
+ <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy stack version of const block copy</span>
+ <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy original version</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>C++ objects stored in <tt class="docutils literal"><span class="pre">__block</span></tt> storage start out on the stack in a
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure as do other variables. Such objects (if not
+<tt class="docutils literal"><span class="pre">const</span></tt> objects) must support a regular copy constructor. The <tt class="docutils literal"><span class="pre">block_byref</span></tt>
+data structure will have copy and destroy helper routines synthesized by the
+compiler. The copy helper will have code created to perform the copy
+constructor based on the initial stack <tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper
+will have code to do the destructor on the object stored within the supplied
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> heap data structure. For example,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__block</span> <span class="n">FOO</span> <span class="n">blockStorageFoo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>requires the normal constructor for the embedded <tt class="docutils literal"><span class="pre">blockStorageFoo</span></tt> object:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and at scope termination the destructor:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note that the forwarding indirection is <em>NOT</em> used.</p>
+<p>The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>for the appropriately named constructor and destructor for the class/struct
+<tt class="docutils literal"><span class="pre">FOO</span></tt>.</p>
+<p>To support member variable and function access the compiler will synthesize a
+<tt class="docutils literal"><span class="pre">const</span></tt> pointer to a block version of the <tt class="docutils literal"><span class="pre">this</span></tt> pointer.</p>
+</div>
+<div class="section" id="runtime-helper-functions">
+<span id="runtimehelperfunctions"></span><h2><a class="toc-backref" href="#id19">Runtime Helper Functions</a><a class="headerlink" href="#runtime-helper-functions" title="Permalink to this headline">¶</a></h2>
+<p>The runtime helper functions are described in
+<tt class="docutils literal"><span class="pre">/usr/local/include/Block_private.h</span></tt>. To summarize their use, a <tt class="docutils literal"><span class="pre">Block</span></tt>
+requires copy/dispose helpers if it imports any block variables, <tt class="docutils literal"><span class="pre">__block</span></tt>
+storage variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors. The (1<<26) bit is set and
+functions are generated.</p>
+<p>The block copy helper function should, for each of the variables of the type
+mentioned above, call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the copy helper and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the dispose helper where <tt class="docutils literal"><span class="pre"><appropo></span></tt> is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// id, NSObject, __attribute__((NSObject)), block, ...</span>
+ <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">=</span> <span class="mi">7</span><span class="p">,</span> <span class="c1">// a block variable</span>
+ <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">=</span> <span class="mi">8</span><span class="p">,</span> <span class="c1">// the on stack structure holding the __block variable</span>
+
+ <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">=</span> <span class="mi">16</span><span class="p">,</span> <span class="c1">// declared __weak</span>
+
+ <span class="n">BLOCK_BYREF_CALLER</span> <span class="o">=</span> <span class="mi">128</span><span class="p">,</span> <span class="c1">// called from byref copy/dispose helpers</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and of course the constructors/destructors for <tt class="docutils literal"><span class="pre">const</span></tt> copied C++ objects.</p>
+<p>The <tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure similarly requires copy/dispose helpers for
+block variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.</p>
+<p>Under ObjC we allow <tt class="docutils literal"><span class="pre">__weak</span></tt> as an attribute on <tt class="docutils literal"><span class="pre">__block</span></tt> variables, and
+this causes the addition of <tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_WEAK</span></tt> orred onto the
+<tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_BYREF</span></tt> flag when copying the <tt class="docutils literal"><span class="pre">block_byref</span></tt> structure in the
+<tt class="docutils literal"><span class="pre">Block</span></tt> copy helper, and onto the <tt class="docutils literal"><span class="pre">BLOCK_FIELD_<appropo></span></tt> field within the
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> copy/dispose helper calls.</p>
+<p>The prototypes, and summary, of the helper functions are:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Certain field types require runtime assistance when being copied to the</span>
+<span class="cm"> heap. The following function is used to copy fields of types: blocks,</span>
+<span class="cm"> pointers to byref structures, and objects (including</span>
+<span class="cm"> __attribute__((NSObject)) pointers. BLOCK_FIELD_IS_WEAK is orthogonal to</span>
+<span class="cm"> the other choices which are mutually exclusive. Only in a Block copy</span>
+<span class="cm"> helper will one see BLOCK_FIELD_IS_BYREF.</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_assign</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">destAddr</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+
+<span class="cm">/* Similarly a compiler generated dispose helper needs to call back for each</span>
+<span class="cm"> field of the byref data structure. (Currently the implementation only</span>
+<span class="cm"> packs one field into the byref structure but in principle there could be</span>
+<span class="cm"> more). The same flags used in the copy helper should be used for each</span>
+<span class="cm"> call generated to this function:</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_dispose</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="copyright">
+<h2><a class="toc-backref" href="#id20">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2>
+<p>Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:</p>
+<p>The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.</p>
+<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.txt (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/Block-ABI-Apple.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1 @@
+*NOTE* This document has moved to http://clang.llvm.org/docs/Block-ABI-Apple.html.
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/BlockLanguageSpec.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/BlockLanguageSpec.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/BlockLanguageSpec.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/BlockLanguageSpec.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,376 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Language Specification for Blocks — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="next" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
+ <link rel="prev" title="Objective-C Literals" href="ObjectiveCLiterals.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>Language Specification for Blocks</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Block-ABI-Apple.html">Block Implementation Specification</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="language-specification-for-blocks">
+<h1>Language Specification for Blocks<a class="headerlink" href="#language-specification-for-blocks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#revisions" id="id1">Revisions</a></li>
+<li><a class="reference internal" href="#overview" id="id2">Overview</a></li>
+<li><a class="reference internal" href="#the-block-type" id="id3">The Block Type</a></li>
+<li><a class="reference internal" href="#block-variable-declarations" id="id4">Block Variable Declarations</a></li>
+<li><a class="reference internal" href="#block-literal-expressions" id="id5">Block Literal Expressions</a></li>
+<li><a class="reference internal" href="#the-invoke-operator" id="id6">The Invoke Operator</a></li>
+<li><a class="reference internal" href="#the-copy-and-release-operations" id="id7">The Copy and Release Operations</a></li>
+<li><a class="reference internal" href="#the-block-storage-qualifier" id="id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a></li>
+<li><a class="reference internal" href="#control-flow" id="id9">Control Flow</a></li>
+<li><a class="reference internal" href="#objective-c-extensions" id="id10">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#c-extensions" id="id11">C++ Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="revisions">
+<h2><a class="toc-backref" href="#id1">Revisions</a><a class="headerlink" href="#revisions" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/2/25 — created</li>
+<li>2008/7/28 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> syntax</li>
+<li>2008/8/13 — revised, Block globals</li>
+<li>2008/8/21 — revised, C++ elaboration</li>
+<li>2008/11/1 — revised, <tt class="docutils literal"><span class="pre">__weak</span></tt> support</li>
+<li>2009/1/12 — revised, explicit return types</li>
+<li>2009/2/10 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> objects need retain</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++</p>
+</div>
+<div class="section" id="the-block-type">
+<h2><a class="toc-backref" href="#id3">The Block Type</a><a class="headerlink" href="#the-block-type" title="Permalink to this headline">¶</a></h2>
+<p>Like function types, the <span class="block-term">Block type</span> is a pair consisting
+of a result value type and a list of parameter types very similar to a
+function type. Blocks are intended to be used much like functions with
+the key distinction being that in addition to executable code they
+also contain various variable bindings to automatic (stack) or managed
+(heap) memory.</p>
+<p>The abstract declarator,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">char</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>describes a reference to a Block that, when invoked, takes two
+parameters, the first of type char and the second of type float, and
+returns a value of type int. The Block referenced is of opaque data
+that may reside in automatic (stack) memory, global memory, or heap
+memory.</p>
+</div>
+<div class="section" id="block-variable-declarations">
+<h2><a class="toc-backref" href="#id4">Block Variable Declarations</a><a class="headerlink" href="#block-variable-declarations" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">variable with Block type</span> is declared using function
+pointer style notation substituting <tt class="docutils literal"><span class="pre">^</span></tt> for <tt class="docutils literal"><span class="pre">*</span></tt>. The following are
+valid Block variable declarations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningVoidWithVoidArgument</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningIntWithIntAndCharArguments</span><span class="p">)(</span><span class="kt">int</span><span class="p">,</span> <span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">arrayOfTenBlocksReturningVoidWithIntArgument</span><span class="p">[</span><span class="mi">10</span><span class="p">])(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Variadic <tt class="docutils literal"><span class="pre">...</span></tt> arguments are supported. [variadic.c] A Block that
+takes no arguments must specify void in the argument list [voidarg.c].
+An empty parameter list does not represent, as K&R provide, an
+unspecified argument list. Note: both gcc and clang support K&R style
+as a convenience.</p>
+<p>A Block reference may be cast to a pointer of arbitrary type and vice
+versa. [cast.c] A Block reference may not be dereferenced via the
+pointer dereference operator <tt class="docutils literal"><span class="pre">*</span></tt>, and thus a Block’s size may not be
+computed at compile time. [sizeof.c]</p>
+</div>
+<div class="section" id="block-literal-expressions">
+<h2><a class="toc-backref" href="#id5">Block Literal Expressions</a><a class="headerlink" href="#block-literal-expressions" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">Block literal expression</span> produces a reference to a
+Block. It is introduced by the use of the <tt class="docutils literal"><span class="pre">^</span></tt> token as a unary
+operator.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Block_literal_expression</span> <span class="o">::=</span> <span class="o">^</span> <span class="n">block_decl</span> <span class="n">compound_statement_body</span>
+<span class="n">block_decl</span> <span class="o">::=</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">parameter_list</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">type_expression</span>
+</pre></div>
+</div>
+<p>where type expression is extended to allow <tt class="docutils literal"><span class="pre">^</span></tt> as a Block reference
+(pointer) where <tt class="docutils literal"><span class="pre">*</span></tt> is allowed as a function reference (pointer).</p>
+<p>The following Block literal:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">void</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>produces a reference to a Block with no arguments with no return value.</p>
+<p>The return type is optional and is inferred from the return
+statements. If the return statements return a value, they all must
+return a value of the same type. If there is no value returned the
+inferred type of the Block is void; otherwise it is the type of the
+return statement value.</p>
+<p>If the return type is omitted and the argument list is <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt>,
+the <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt> argument list may also be omitted.</p>
+<p>So:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">(</span> <span class="kt">void</span> <span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are exactly equivalent constructs for the same expression.</p>
+<p>The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.</p>
+<p>Given:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">pointerToFunctionThatReturnsIntWithCharArg</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="n">functionPointer</span><span class="p">;</span>
+<span class="o">^</span> <span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">int</span> <span class="p">((</span><span class="o">*</span><span class="p">)(</span><span class="kt">float</span> <span class="n">x</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are equivalent expressions, as is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>[returnfunctionptr.c]</p>
+<p>The compound statement body establishes a new lexical scope within
+that of its parent. Variables used within the scope of the compound
+statement are bound to the Block in the normal manner with the
+exception of those in automatic (stack) storage. Thus one may access
+functions and global variables as one would expect, as well as static
+local variables. [testme]</p>
+<p>Local automatic (stack) variables referenced within the compound
+statement of a Block are imported and captured by the Block as const
+copies. The capture (binding) is performed at the time of the Block
+literal expression evaluation.</p>
+<p>The compiler is not required to capture a variable if it can prove
+that no references to the variable will actually be evaluated.
+Programmers can force a variable to be captured by referencing it in a
+statement at the beginning of the Block, like so:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.</p>
+<p>The lifetime of variables declared in a Block is that of a function;
+each activation frame contains a new copy of variables declared within
+the local scope of the Block. Such variable declarations should be
+allowed anywhere [testme] rather than only when C99 parsing is
+requested, including for statements. [testme]</p>
+<p>Block literal expressions may occur within Block literal expressions
+(nest) and all variables captured by any nested blocks are implicitly
+also captured in the scopes of their enclosing Blocks.</p>
+<p>A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.</p>
+</div>
+<div class="section" id="the-invoke-operator">
+<h2><a class="toc-backref" href="#id6">The Invoke Operator</a><a class="headerlink" href="#the-invoke-operator" title="Permalink to this headline">¶</a></h2>
+<p>Blocks are <span class="block-term">invoked</span> using function call syntax with a
+list of expression parameters of types corresponding to the
+declaration and returning a result type also according to the
+declaration. Given:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">x</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">z</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>the following are all legal Block invocations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">x</span><span class="p">(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="nb">true</span> <span class="o">?</span> <span class="n">x</span> <span class="o">:</span> <span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-copy-and-release-operations">
+<h2><a class="toc-backref" href="#id7">The Copy and Release Operations</a><a class="headerlink" href="#the-copy-and-release-operations" title="Permalink to this headline">¶</a></h2>
+<p>The compiler and runtime provide <span class="block-term">copy</span> and
+<span class="block-term">release</span> operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.</p>
+<p>The copy operation <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, <tt class="docutils literal"><span class="pre">Block_release()</span></tt>, is styled as a
+function that takes an arbitrary Block reference and, if dynamically
+matched to a Block copy operation, allows recovery of the referenced
+allocated memory.</p>
+</div>
+<div class="section" id="the-block-storage-qualifier">
+<h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a><a class="headerlink" href="#the-block-storage-qualifier" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the new Block type we also introduce a new storage
+qualifier, <span class="block-term">__block</span>, for local variables. [testme: a
+__block declaration within a block literal] The <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+<tt class="docutils literal"><span class="pre">__block</span></tt> act as if they were in allocated storage and this storage
+is automatically recovered after last use of said variable. An
+implementation may choose an optimization where the storage is
+initially automatic and only “moved” to allocated (heap) storage upon
+a Block_copy of a referencing Block. Such variables may be mutated as
+normal variables are.</p>
+<p>In the case where a <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a Block one must assume
+that the <tt class="docutils literal"><span class="pre">__block</span></tt> variable resides in allocated storage and as such
+is assumed to reference a Block that is also in allocated storage
+(that it is the result of a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> operation). Despite this
+there is no provision to do a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> or a <tt class="docutils literal"><span class="pre">Block_release</span></tt> if
+an implementation provides initial automatic storage for Blocks. This
+is due to the inherent race condition of potentially several threads
+trying to update the shared variable and the need for synchronization
+around disposing of older values and copying new ones. Such
+synchronization is beyond the scope of this language specification.</p>
+</div>
+<div class="section" id="control-flow">
+<h2><a class="toc-backref" href="#id9">Control Flow</a><a class="headerlink" href="#control-flow" title="Permalink to this headline">¶</a></h2>
+<p>The compound statement of a Block is treated much like a function body
+with respect to control flow in that goto, break, and continue do not
+escape the Block. Exceptions are treated <em>normally</em> in that when
+thrown they pop stack frames until a catch clause is found.</p>
+</div>
+<div class="section" id="objective-c-extensions">
+<h2><a class="toc-backref" href="#id10">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Objective-C extends the definition of a Block reference type to be
+that also of id. A variable or expression of Block type may be
+messaged or used as a parameter wherever an id may be. The converse is
+also true. Block references may thus appear as properties and are
+subject to the assign, retain, and copy attribute logic that is
+reserved for objects.</p>
+<p>All Blocks are constructed to be Objective-C objects regardless of
+whether the Objective-C runtime is operational in the program or
+not. Blocks using automatic (stack) memory are objects and may be
+messaged, although they may not be assigned into <tt class="docutils literal"><span class="pre">__weak</span></tt> locations
+if garbage collection is enabled.</p>
+<p>Within a Block literal expression within a method definition
+references to instance variables are also imported into the lexical
+scope of the compound statement. These variables are implicitly
+qualified as references from self, and so self is imported as a const
+copy. The net effect is that instance variables can be mutated.</p>
+<p>The <span class="block-term">Block_copy</span> operator retains all objects held in
+variables of automatic storage referenced within the Block expression
+(or form strong references if running under garbage collection).
+Object variables of <tt class="docutils literal"><span class="pre">__block</span></tt> storage type are assumed to hold
+normal pointers with no provision for retain and release messages.</p>
+<p>Foundation defines (and supplies) <tt class="docutils literal"><span class="pre">-copy</span></tt> and <tt class="docutils literal"><span class="pre">-release</span></tt> methods for
+Blocks.</p>
+<p>In the Objective-C and Objective-C++ languages, we allow the
+<tt class="docutils literal"><span class="pre">__weak</span></tt> specifier for <tt class="docutils literal"><span class="pre">__block</span></tt> variables of object type. If
+garbage collection is not enabled, this qualifier causes these
+variables to be kept without retain messages being sent. This
+knowingly leads to dangling pointers if the Block (or a copy) outlives
+the lifetime of this object.</p>
+<p>In garbage collected environments, the <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is set to
+nil when the object it references is collected, as long as the
+<tt class="docutils literal"><span class="pre">__block</span></tt> variable resides in the heap (either by default or via
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt>). The initial Apple implementation does in fact
+start <tt class="docutils literal"><span class="pre">__block</span></tt> variables on the stack and migrate them to the heap
+only as a result of a <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation.</p>
+<p>It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked <tt class="docutils literal"><span class="pre">__weak</span></tt>, including
+<tt class="docutils literal"><span class="pre">__weak</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables.</p>
+</div>
+<div class="section" id="c-extensions">
+<h2><a class="toc-backref" href="#id11">C++ Extensions</a><a class="headerlink" href="#c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.</p>
+<p>As usual, within the block, references to captured variables become
+const-qualified, as if they were references to members of a const
+object. Note that this does not change the type of a variable of
+reference type.</p>
+<p>For example, given a class Foo:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Foo</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">fooRef</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="n">fooPtr</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>A Block that referenced these variables would import the variables as
+const variations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">const</span> <span class="n">Foo</span> <span class="n">block_foo</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">block_fooRef</span> <span class="o">=</span> <span class="n">fooRef</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="k">const</span> <span class="n">block_fooPtr</span> <span class="o">=</span> <span class="n">fooPtr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression. They are also copied when
+calling <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> on a Block allocated on the stack. In both
+cases, they are copied as if the variable were const-qualified, and
+it’s an error if there’s no such constructor.</p>
+<p>Captured variables in Blocks on the stack are destroyed when control
+leaves the compound statement that contains the Block literal
+expression. Captured variables in Blocks on the heap are destroyed
+when the reference count of the Block drops to zero.</p>
+<p>Variables declared as residing in <tt class="docutils literal"><span class="pre">__block</span></tt> storage may be initially
+allocated in the heap or may first appear on the stack and be copied
+to the heap as a result of a <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation. When copied
+from the stack, <tt class="docutils literal"><span class="pre">__block</span></tt> variables are copied using their normal
+qualification (i.e. without adding const). In C++11, <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables are copied as x-values if that is possible, then as l-values
+if not; if both fail, it’s an error. The destructor for any initial
+stack-based version is called at the variable’s normal end of scope.</p>
+<p>References to <tt class="docutils literal"><span class="pre">this</span></tt>, as well as references to non-static members of
+any enclosing class, are evaluated by capturing <tt class="docutils literal"><span class="pre">this</span></tt> just like a
+normal variable of C pointer type.</p>
+<p>Member variables that are Blocks may not be overloaded by the types of
+their arguments.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Block-ABI-Apple.html">Block Implementation Specification</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.5.1/tools/clang/docs/_build/html/ClangCheck.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/tools/clang/docs/_build/html/ClangCheck.html?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/tools/clang/docs/_build/html/ClangCheck.html (added)
+++ www-releases/trunk/3.5.1/tools/clang/docs/_build/html/ClangCheck.html Tue Jan 13 16:55:20 2015
@@ -0,0 +1,107 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>ClangCheck — Clang 3.5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 3.5 documentation" href="index.html" />
+ <link rel="next" title="ClangFormat" href="ClangFormat.html" />
+ <link rel="prev" title="Overview" href="ClangTools.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 3.5 documentation</span></a></h1>
+ <h2 class="heading"><span>ClangCheck</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ClangTools.html">Overview</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ClangFormat.html">ClangFormat</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clangcheck">
+<h1>ClangCheck<a class="headerlink" href="#clangcheck" title="Permalink to this headline">¶</a></h1>
+<p><cite>ClangCheck</cite> is a small wrapper around <a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> which can be used to
+do basic error checking and AST dumping.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat <span class="s"><<EOF > snippet.cc</span>
+<span class="gp">></span><span class="s"> void f() {</span>
+<span class="gp">></span><span class="s"> int a = 0</span>
+<span class="gp">></span><span class="s"> }</span>
+<span class="gp">></span><span class="s"> EOF</span>
+<span class="gp">$</span> ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+<span class="go">Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.</span>
+<span class="go">/Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of</span>
+<span class="go"> declaration</span>
+<span class="go"> int a = 0</span>
+<span class="go"> ^</span>
+<span class="go"> ;</span>
+<span class="go">(TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>></span>
+<span class="go"> (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')</span>
+<span class="go"> (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')</span>
+<span class="go"> (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')</span>
+<span class="go"> (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'</span>
+<span class="go"> (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1></span>
+<span class="go"> (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1></span>
+<span class="go"> (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'</span>
+<span class="go"> (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))</span>
+<span class="go">1 error generated.</span>
+<span class="go">Error while processing snippet.cc.</span>
+</pre></div>
+</div>
+<p>The ‘–’ at the end is important as it prevents <cite>clang-check</cite> from search for a
+compilation database. For more information on how to setup and use <cite>clang-check</cite>
+in a project, see <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a>.</p>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ClangTools.html">Overview</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ClangFormat.html">ClangFormat</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2014, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list