[cfe-commits] r170048 - in /cfe/trunk/docs: LanguageExtensions.html LanguageExtensions.rst LibASTMatchers.html LibASTMatchers.rst LibTooling.html LibTooling.rst PCHInternals.html PCHInternals.rst ThreadSanitizer.html ThreadSanitizer.rst Tooling.html Tooling.rst index.rst
Sean Silva
silvas at purdue.edu
Wed Dec 12 15:44:55 PST 2012
Author: silvas
Date: Wed Dec 12 17:44:55 2012
New Revision: 170048
URL: http://llvm.org/viewvc/llvm-project?rev=170048&view=rev
Log:
docs: Convert some docs to reST.
Converts:
LanguageExtensions
LibASTMatchers
LibTooling
PCHInternals
ThreadSanitizer
Tooling
Patch by Mykhailo Pustovit!
(with minor edits by Dmitri Gribenko and Sean Silva)
Added:
cfe/trunk/docs/LanguageExtensions.rst
cfe/trunk/docs/LibASTMatchers.rst
cfe/trunk/docs/LibTooling.rst
cfe/trunk/docs/PCHInternals.rst
cfe/trunk/docs/ThreadSanitizer.rst
cfe/trunk/docs/Tooling.rst
Removed:
cfe/trunk/docs/LanguageExtensions.html
cfe/trunk/docs/LibASTMatchers.html
cfe/trunk/docs/LibTooling.html
cfe/trunk/docs/PCHInternals.html
cfe/trunk/docs/ThreadSanitizer.html
cfe/trunk/docs/Tooling.html
Modified:
cfe/trunk/docs/index.rst
Removed: cfe/trunk/docs/LanguageExtensions.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/LanguageExtensions.html (original)
+++ cfe/trunk/docs/LanguageExtensions.html (removed)
@@ -1,2082 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
-<html>
-<head>
- <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>Clang Language Extensions</title>
- <link type="text/css" rel="stylesheet" href="../menu.css">
- <link type="text/css" rel="stylesheet" href="../content.css">
- <style type="text/css">
- td {
- vertical-align: top;
- }
- th { background-color: #ffddaa; }
- </style>
-</head>
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>Clang Language Extensions</h1>
-
-<ul>
-<li><a href="#intro">Introduction</a></li>
-<li><a href="#feature_check">Feature Checking Macros</a></li>
-<li><a href="#has_include">Include File Checking Macros</a></li>
-<li><a href="#builtinmacros">Builtin Macros</a></li>
-<li><a href="#vectors">Vectors and Extended Vectors</a></li>
-<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
-<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
-<li><a href="#user_specified_system_framework">'User-Specified' System Frameworks</a></li>
-<li><a href="#availability">Availability attribute</a></li>
-<li><a href="#checking_language_features">Checks for Standard Language Features</a>
- <ul>
- <li><a href="#cxx98">C++98</a>
- <ul>
- <li><a href="#cxx_exceptions">C++ exceptions</a></li>
- <li><a href="#cxx_rtti">C++ RTTI</a></li>
- </ul></li>
- <li><a href="#cxx11">C++11</a>
- <ul>
- <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes access control</a></li>
- <li><a href="#cxx_alias_templates">C++11 alias templates</a></li>
- <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li>
- <li><a href="#cxx_attributes">C++11 attributes</a></li>
- <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li>
- <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li>
- <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li>
- <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li>
- <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li>
- <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li>
- <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li>
- <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li>
- <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li>
- <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li>
- <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li>
- <li><a href="#cxx_lambdas">C++11 lambdas</a></li>
- <li><a href="#cxx_local_type_template_args">C++11 local and unnamed types as template arguments</a></li>
- <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li>
- <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li>
- <li><a href="#cxx_nullptr">C++11 nullptr</a></li>
- <li><a href="#cxx_override_control">C++11 override control</a></li>
- <li><a href="#cxx_range_for">C++11 range-based for loop</a></li>
- <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li>
- <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li>
- <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li>
- <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li>
- <li><a href="#cxx_auto_type">C++11 type inference</a></li>
- <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li>
- <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li>
- <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li>
- <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li>
- <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li>
- <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li>
- </ul></li>
- <li><a href="#c11">C11</a>
- <ul>
- <li><a href="#c_alignas">C11 alignment specifiers</a></li>
- <li><a href="#c_atomic">C11 atomic operations</a></li>
- <li><a href="#c_generic_selections">C11 generic selections</a></li>
- <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li>
- </ul></li>
-</ul></li>
-<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
-<li><a href="#blocks">Blocks</a></li>
-<li><a href="#objc_features">Objective-C Features</a>
- <ul>
- <li><a href="#objc_instancetype">Related result types</a></li>
- <li><a href="#objc_arc">Automatic reference counting</a></li>
- <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li>
- <li><a href="#objc_lambdas">Interoperability with C++11 lambdas</a></li>
- <li><a href="#objc_object_literals_subscripting">Object Literals and Subscripting</a></li>
- </ul>
-</li>
-<li><a href="#overloading-in-c">Function Overloading in C</a></li>
-<li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li>
-<li><a href="#builtins">Builtin Functions</a>
- <ul>
- <li><a href="#__builtin_readcyclecounter">__builtin_readcyclecounter</a></li>
- <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
- <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
- <li><a href="#__sync_swap">__sync_swap</a></li>
- </ul>
-</li>
-<li><a href="#non-standard-attributes">Non-standard C++11 Attributes</a>
-<ul>
- <li><a href="#clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</a></li>
-</ul>
-</li>
-<li><a href="#targetspecific">Target-Specific Extensions</a>
- <ul>
- <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
- </ul>
-</li>
-<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
-<li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a>
- <ul>
- <li><a href="#address_sanitizer">AddressSanitizer</a></li>
- </ul>
-</li>
-<li><a href="#threadsafety">Thread Safety Annotation Checking</a>
- <ul>
- <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>
- <li><a href="#ts_lockable"><tt>lockable</tt></a></li>
- <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li>
- <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li>
- <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li>
- <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li>
- <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li>
- <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li>
- <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li>
- <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li>
- <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li>
- <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li>
- <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li>
- <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li>
- <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li>
- <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li>
- <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li>
- <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li>
- </ul>
-</li>
-<li><a href="#type_safety">Type Safety Checking</a>
- <ul>
- <li><a href="#argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></a></li>
- <li><a href="#pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></a></li>
- <li><a href="#type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></a></li>
- </ul>
-</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="intro">Introduction</h2>
-<!-- ======================================================================= -->
-
-<p>This document describes the language extensions provided by Clang. In
-addition to the language extensions listed here, Clang aims to support a broad
-range of GCC extensions. Please see the <a
-href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
-more information on these extensions.</p>
-
-<!-- ======================================================================= -->
-<h2 id="feature_check">Feature Checking Macros</h2>
-<!-- ======================================================================= -->
-
-<p>Language extensions can be very useful, but only if you know you can depend
-on them. In order to allow fine-grain features checks, we support three builtin
-function-like macros. This allows you to directly test for a feature in your
-code without having to resort to something like autoconf or fragile "compiler
-version checks".</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__has_builtin">__has_builtin</a></h3>
-<!-- ======================================================================= -->
-
-<p>This function-like macro takes a single identifier argument that is the name
-of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
-not. It can be used like this:</p>
-
-<blockquote>
-<pre>
-#ifndef __has_builtin // Optional of course.
- #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
-#endif
-
-...
-#if __has_builtin(__builtin_trap)
- __builtin_trap();
-#else
- abort();
-#endif
-...
-</pre>
-</blockquote>
-
-
-<!-- ======================================================================= -->
-<h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3>
-<!-- ======================================================================= -->
-
-<p>These function-like macros take a single identifier argument that is the
-name of a feature. <code>__has_feature</code> evaluates to 1 if the feature
-is both supported by Clang and standardized in the current language standard
-or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
-<code>__has_extension</code> evaluates to 1 if the feature is supported by
-Clang in the current language (either as a language extension or a standard
-language feature) or 0 if not. They can be used like this:</p>
-
-<blockquote>
-<pre>
-#ifndef __has_feature // Optional of course.
- #define __has_feature(x) 0 // Compatibility with non-clang compilers.
-#endif
-#ifndef __has_extension
- #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
-#endif
-
-...
-#if __has_feature(cxx_rvalue_references)
-// This code will only be compiled with the -std=c++11 and -std=gnu++11
-// options, because rvalue references are only standardized in C++11.
-#endif
-
-#if __has_extension(cxx_rvalue_references)
-// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
-// and -std=gnu++98 options, because rvalue references are supported as a
-// language extension in C++98.
-#endif
-</pre>
-</blockquote>
-
-<p id="has_feature_back_compat">For backwards compatibility reasons,
-<code>__has_feature</code> can also be used to test for support for
-non-standardized features, i.e. features not prefixed <code>c_</code>,
-<code>cxx_</code> or <code>objc_</code>.</p>
-
-<p id="has_feature_for_non_language_features">
-Another use of <code>__has_feature</code> is to check for compiler features
-not related to the language standard, such as e.g.
-<a href="AddressSanitizer.html">AddressSanitizer</a>.
-
-<p>If the <code>-pedantic-errors</code> option is given,
-<code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
-
-<p>The feature tag is described along with the language feature below.</p>
-
-<p>The feature name or extension name can also be specified with a preceding and
-following <code>__</code> (double underscore) to avoid interference from a macro
-with the same name. For instance, <code>__cxx_rvalue_references__</code> can be
-used instead of <code>cxx_rvalue_references</code>.</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__has_attribute">__has_attribute</a></h3>
-<!-- ======================================================================= -->
-
-<p>This function-like macro takes a single identifier argument that is the name
-of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
-can be used like this:</p>
-
-<blockquote>
-<pre>
-#ifndef __has_attribute // Optional of course.
- #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
-#endif
-
-...
-#if __has_attribute(always_inline)
-#define ALWAYS_INLINE __attribute__((always_inline))
-#else
-#define ALWAYS_INLINE
-#endif
-...
-</pre>
-</blockquote>
-
-<p>The attribute name can also be specified with a preceding and
-following <code>__</code> (double underscore) to avoid interference from a macro
-with the same name. For instance, <code>__always_inline__</code> can be used
-instead of <code>always_inline</code>.</p>
-
-<!-- ======================================================================= -->
-<h2 id="has_include">Include File Checking Macros</h2>
-<!-- ======================================================================= -->
-
-<p>Not all developments systems have the same include files.
-The <a href="#__has_include">__has_include</a> and
-<a href="#__has_include_next">__has_include_next</a> macros allow you to
-check for the existence of an include file before doing
-a possibly failing #include directive.</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__has_include">__has_include</a></h3>
-<!-- ======================================================================= -->
-
-<p>This function-like macro takes a single file name string argument that
-is the name of an include file. It evaluates to 1 if the file can
-be found using the include paths, or 0 otherwise:</p>
-
-<blockquote>
-<pre>
-// Note the two possible file name string formats.
-#if __has_include("myinclude.h") && __has_include(<stdint.h>)
-# include "myinclude.h"
-#endif
-
-// To avoid problem with non-clang compilers not having this macro.
-#if defined(__has_include) && __has_include("myinclude.h")
-# include "myinclude.h"
-#endif
-</pre>
-</blockquote>
-
-<p>To test for this feature, use #if defined(__has_include).</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__has_include_next">__has_include_next</a></h3>
-<!-- ======================================================================= -->
-
-<p>This function-like macro takes a single file name string argument that
-is the name of an include file. It is like __has_include except that it
-looks for the second instance of the given file found in the include
-paths. It evaluates to 1 if the second instance of the file can
-be found using the include paths, or 0 otherwise:</p>
-
-<blockquote>
-<pre>
-// Note the two possible file name string formats.
-#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
-# include_next "myinclude.h"
-#endif
-
-// To avoid problem with non-clang compilers not having this macro.
-#if defined(__has_include_next) && __has_include_next("myinclude.h")
-# include_next "myinclude.h"
-#endif
-</pre>
-</blockquote>
-
-<p>Note that __has_include_next, like the GNU extension
-#include_next directive, is intended for use in headers only,
-and will issue a warning if used in the top-level compilation
-file. A warning will also be issued if an absolute path
-is used in the file argument.</p>
-
-
-<!-- ======================================================================= -->
-<h3><a name="__has_warning">__has_warning</a></h3>
-<!-- ======================================================================= -->
-
-<p>This function-like macro takes a string literal that represents a command
- line option for a warning and returns true if that is a valid warning
- option.</p>
-
-<blockquote>
-<pre>
-#if __has_warning("-Wformat")
-...
-#endif
-</pre>
-</blockquote>
-
-<!-- ======================================================================= -->
-<h2 id="builtinmacros">Builtin Macros</h2>
-<!-- ======================================================================= -->
-
-<dl>
- <dt><code>__BASE_FILE__</code></dt>
- <dd>Defined to a string that contains the name of the main input
- file passed to Clang.</dd>
-
- <dt><code>__COUNTER__</code></dt>
- <dd>Defined to an integer value that starts at zero and is
- incremented each time the <code>__COUNTER__</code> macro is
- expanded.</dd>
-
- <dt><code>__INCLUDE_LEVEL__</code></dt>
- <dd>Defined to an integral value that is the include depth of the
- file currently being translated. For the main file, this value is
- zero.</dd>
-
- <dt><code>__TIMESTAMP__</code></dt>
- <dd>Defined to the date and time of the last modification of the
- current source file.</dd>
-
- <dt><code>__clang__</code></dt>
- <dd>Defined when compiling with Clang</dd>
-
- <dt><code>__clang_major__</code></dt>
- <dd>Defined to the major marketing version number of Clang (e.g., the
- 2 in 2.0.1). Note that marketing version numbers should not be used to
- check for language features, as different vendors use different numbering
- schemes. Instead, use the <a href="#feature_check">feature checking
- macros</a>.</dd>
-
- <dt><code>__clang_minor__</code></dt>
- <dd>Defined to the minor version number of Clang (e.g., the 0 in
- 2.0.1). Note that marketing version numbers should not be used to
- check for language features, as different vendors use different numbering
- schemes. Instead, use the <a href="#feature_check">feature checking
- macros</a>.</dd>
-
- <dt><code>__clang_patchlevel__</code></dt>
- <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd>
-
- <dt><code>__clang_version__</code></dt>
- <dd>Defined to a string that captures the Clang marketing version, including
- the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd>
-</dl>
-
-<!-- ======================================================================= -->
-<h2 id="vectors">Vectors and Extended Vectors</h2>
-<!-- ======================================================================= -->
-
-<p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p>
-
-<p>OpenCL vector types are created using <tt>ext_vector_type</tt> attribute. It
-support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An
-example is:</p>
-
-<blockquote>
-<pre>
-typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
-typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
-
-float4 foo(float2 a, float2 b) {
- float4 c;
- c.xz = a;
- c.yw = b;
- return c;
-}
-</pre>
-</blockquote>
-
-<p>Query for this feature with
-<tt>__has_extension(attribute_ext_vector_type)</tt>.</p>
-
-<p>Giving <tt>-faltivec</tt> option to clang enables support for AltiVec vector
-syntax and functions. For example:</p>
-
-<blockquote>
-<pre>
-vector float foo(vector int a) {
- vector int b;
- b = vec_add(a, a) + a;
- return (vector float)b;
-}
-</pre>
-</blockquote>
-
-<p>NEON vector types are created using <tt>neon_vector_type</tt> and
-<tt>neon_polyvector_type</tt> attributes. For example:</p>
-
-<blockquote>
-<pre>
-typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t;
-typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t;
-
-int8x8_t foo(int8x8_t a) {
- int8x8_t v;
- v = a;
- return v;
-}
-</pre>
-</blockquote>
-
-<!-- ======================================================================= -->
-<h3><a name="vector_literals">Vector Literals</a></h3>
-<!-- ======================================================================= -->
-
-<p>Vector literals can be used to create vectors from a set of scalars, or
-vectors. Either parentheses or braces form can be used. In the parentheses form
-the number of literal values specified must be one, i.e. referring to a scalar
-value, or must match the size of the vector type being created. If a single
-scalar literal value is specified, the scalar literal value will be replicated
-to all the components of the vector type. In the brackets form any number of
-literals can be specified. For example:</p>
-
-<blockquote>
-<pre>
-typedef int v4si __attribute__((__vector_size__(16)));
-typedef float float4 __attribute__((ext_vector_type(4)));
-typedef float float2 __attribute__((ext_vector_type(2)));
-
-v4si vsi = (v4si){1, 2, 3, 4};
-float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
-vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
-vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
-vector int vi3 = (vector int)(1, 2); // error
-vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
-vector int vi5 = (vector int)(1, 2, 3, 4);
-float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
-</pre>
-</blockquote>
-
-<!-- ======================================================================= -->
-<h3><a name="vector_operations">Vector Operations</a></h3>
-<!-- ======================================================================= -->
-
-<p>The table below shows the support for each operation by vector extension.
-A dash indicates that an operation is not accepted according to a corresponding
-specification.</p>
-
-<table width="500" border="1" cellspacing="0">
- <tr>
- <th>Operator</th>
- <th>OpenCL</th>
- <th>AltiVec</th>
- <th>GCC</th>
- <th>NEON</th>
- </tr>
- <tr>
- <td>[]</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>unary operators +, -</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>++, --</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>+, -, *, /, %</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>bitwise operators &, |, ^, ~</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>>>, <<</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>!, &&,||</td>
- <td align="center">no</td>
- <td align="center">-</td>
- <td align="center">-</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>==,!=, >, <, >=, <=</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>=</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- </tr>
- <tr>
- <td>:?</td>
- <td align="center">yes</td>
- <td align="center">-</td>
- <td align="center">-</td>
- <td align="center">-</td>
- </tr>
- <tr>
- <td>sizeof</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- <td align="center">yes</td>
- </tr>
-</table>
-
-<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
-
-<!-- ======================================================================= -->
-<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
-<!-- ======================================================================= -->
-
-<p>An optional string message can be added to the <tt>deprecated</tt>
-and <tt>unavailable</tt> attributes. For example:</p>
-
-<blockquote>
-<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
-</blockquote>
-
-<p>If the deprecated or unavailable declaration is used, the message
-will be incorporated into the appropriate diagnostic:</p>
-
-<blockquote>
-<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
- [-Wdeprecated-declarations]
- explode();
- ^</pre>
-</blockquote>
-
-<p>Query for this feature
-with <tt>__has_extension(attribute_deprecated_with_message)</tt>
-and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
-
-<!-- ======================================================================= -->
-<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
-<!-- ======================================================================= -->
-
-<p>Clang allows attributes to be written on individual enumerators.
-This allows enumerators to be deprecated, made unavailable, etc. The
-attribute must appear after the enumerator name and before any
-initializer, like so:</p>
-
-<blockquote>
-<pre>enum OperationMode {
- OM_Invalid,
- OM_Normal,
- OM_Terrified __attribute__((deprecated)),
- OM_AbortOnError __attribute__((deprecated)) = 4
-};</pre>
-</blockquote>
-
-<p>Attributes on the <tt>enum</tt> declaration do not apply to
-individual enumerators.</p>
-
-<p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
-
-<!-- ======================================================================= -->
-<h2 id="user_specified_system_framework">'User-Specified' System Frameworks</h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides a mechanism by which frameworks can be built in such a way
-that they will always be treated as being 'system frameworks', even if they are
-not present in a system framework directory. This can be useful to system
-framework developers who want to be able to test building other applications
-with development builds of their framework, including the manner in which the
-compiler changes warning behavior for system headers.</p>
-
-<p>Framework developers can opt-in to this mechanism by creating a
-'.system_framework' file at the top-level of their framework. That is, the
-framework should have contents like:</p>
-
-<pre>
- .../TestFramework.framework
- .../TestFramework.framework/.system_framework
- .../TestFramework.framework/Headers
- .../TestFramework.framework/Headers/TestFramework.h
- ...
-</pre>
-
-<p>Clang will treat the presence of this file as an indicator that the framework
-should be treated as a system framework, regardless of how it was found in the
-framework search path. For consistency, we recommend that such files never be
-included in installed versions of the framework.</p>
-
-<!-- ======================================================================= -->
-<h2 id="availability">Availability attribute</h2>
-<!-- ======================================================================= -->
-
-<p>Clang introduces the <code>availability</code> attribute, which 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 <code>f</code>:</p>
-
-<pre>
-void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
-</pre>
-
-<p>The availability attribute states that <code>f</code> 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 <code>f</code>: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to <code>f()</code> 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 <code>f()</code> is no longer available.</p>
-
-<p>The availablility 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>
- <dt>introduced=<i>version</i></dt>
- <dd>The first version in which this declaration was introduced.</dd>
-
- <dt>deprecated=<i>version</i></dt>
- <dd>The first version in which this declaration was deprecated, meaning that users should migrate away from this API.</dd>
-
- <dt>obsoleted=<i>version</i></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=<i>string-literal</i></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>
- <dt>ios</dt>
- <dd>Apple's iOS operating system. The minimum deployment target is specified by the <code>-mios-version-min=<i>version</i></code> or <code>-miphoneos-version-min=<i>version</i></code> command-line arguments.</dd>
-
- <dt>macosx</dt>
- <dd>Apple's Mac OS X operating system. The minimum deployment target is specified by the <code>-mmacosx-version-min=<i>version</i></code> 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
- href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly
-linked</a>, as if the <code>weak_import</code> 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>
-
-<!-- ======================================================================= -->
-<h2 id="checking_language_features">Checks for Standard Language Features</h2>
-<!-- ======================================================================= -->
-
-<p>The <tt>__has_feature</tt> macro can be used to query if certain standard
-language features are enabled. The <tt>__has_extension</tt> macro can be used
-to query if language features are available as an extension when compiling for
-a standard which does not provide them. The features which can be tested are
-listed here.</p>
-
-<h3 id="cxx98">C++98</h3>
-
-<p>The features listed below are part of the C++98 standard. These features are
-enabled by default when compiling C++ code.</p>
-
-<h4 id="cxx_exceptions">C++ exceptions</h4>
-
-<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
-example, compiling code with <tt>-fno-exceptions</tt> disables C++ exceptions.</p>
-
-<h4 id="cxx_rtti">C++ RTTI</h4>
-
-<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
-compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
-
-<h3 id="cxx11">C++11</h3>
-
-<p>The features listed below are part of the C++11 standard. As a result, all
-these features are enabled with the <tt>-std=c++11</tt> or <tt>-std=gnu++11</tt>
-option when compiling C++ code.</p>
-
-<h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4>
-
-<p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
-
-<h4 id="cxx_alias_templates">C++11 alias templates</h4>
-
-<p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
-<tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
-C++11's alias declarations and alias templates is enabled.</p>
-
-<h4 id="cxx_alignas">C++11 alignment specifiers</h4>
-
-<p>Use <tt>__has_feature(cxx_alignas)</tt> or
-<tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment
-specifiers using <tt>alignas</tt> is enabled.</p>
-
-<h4 id="cxx_attributes">C++11 attributes</h4>
-
-<p>Use <tt>__has_feature(cxx_attributes)</tt> or
-<tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
-parsing with C++11's square bracket notation is enabled.</p>
-
-<h4 id="cxx_constexpr">C++11 generalized constant expressions</h4>
-
-<p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support
-for generalized constant expressions (e.g., <tt>constexpr</tt>) is
-enabled.</p>
-
-<h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4>
-
-<p>Use <tt>__has_feature(cxx_decltype)</tt> or
-<tt>__has_extension(cxx_decltype)</tt> to determine if support for the
-<tt>decltype()</tt> specifier is enabled. C++11's <tt>decltype</tt>
-does not require type-completeness of a function call expression.
-Use <tt>__has_feature(cxx_decltype_incomplete_return_types)</tt>
-or <tt>__has_extension(cxx_decltype_incomplete_return_types)</tt>
-to determine if support for this feature is enabled.</p>
-
-<h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4>
-
-<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
-<tt>__has_extension(cxx_default_function_template_args)</tt> to determine
-if support for default template arguments in function templates is enabled.</p>
-
-<h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4>
-
-<p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or
-<tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for
-defaulted function definitions (with <tt>= default</tt>) is enabled.</p>
-
-<h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4>
-
-<p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if
-support for delegating constructors is enabled.</p>
-
-<h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4>
-
-<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
-<tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
-deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
-
-<h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4>
-<p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p>
-
-<h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4>
-
-<p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if
-support for generalized initializers (using braced lists and
-<tt>std::initializer_list</tt>) is enabled.</p>
-
-<h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4>
-
-<p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will
-implicitly generate move constructors and move assignment operators where needed.</p>
-
-<h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4>
-
-<p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p>
-
-<h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4>
-
-<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
-<tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
-inline namespaces is enabled.</p>
-
-<h4 id="cxx_lambdas">C++11 lambdas</h4>
-
-<p>Use <tt>__has_feature(cxx_lambdas)</tt> or
-<tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
-is enabled. </p>
-
-<h4 id="cxx_local_type_template_args">C++11 local and unnamed types as template arguments</h4>
-
-<p>Use <tt>__has_feature(cxx_local_type_template_args)</tt> or
-<tt>__has_extension(cxx_local_type_template_args)</tt> to determine if
-support for local and unnamed types as template arguments is enabled.</p>
-
-<h4 id="cxx_noexcept">C++11 noexcept</h4>
-
-<p>Use <tt>__has_feature(cxx_noexcept)</tt> or
-<tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
-exception specifications is enabled.</p>
-
-<h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4>
-
-<p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p>
-
-<h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4>
-
-<p>Use <tt>__has_feature(cxx_nullptr)</tt> or
-<tt>__has_extension(cxx_nullptr)</tt> to determine if support for
-<tt>nullptr</tt> is enabled.</p>
-
-<h4 id="cxx_override_control">C++11 <tt>override control</tt></h4>
-
-<p>Use <tt>__has_feature(cxx_override_control)</tt> or
-<tt>__has_extension(cxx_override_control)</tt> to determine if support for
-the override control keywords is enabled.</p>
-
-<h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4>
-<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
-<tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
-if support for reference-qualified functions (e.g., member functions with
-<code>&</code> or <code>&&</code> applied to <code>*this</code>)
-is enabled.</p>
-
-<h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4>
-
-<p>Use <tt>__has_feature(cxx_range_for)</tt> or
-<tt>__has_extension(cxx_range_for)</tt> to determine if support for the
-range-based for loop is enabled. </p>
-
-<h4 id="cxx_raw_string_literals">C++11 raw string literals</h4>
-<p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support
-for raw string literals (e.g., <tt>R"x(foo\bar)x"</tt>) is enabled.</p>
-
-<h4 id="cxx_rvalue_references">C++11 rvalue references</h4>
-
-<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
-<tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
-rvalue references is enabled. </p>
-
-<h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4>
-
-<p>Use <tt>__has_feature(cxx_static_assert)</tt> or
-<tt>__has_extension(cxx_static_assert)</tt> to determine if support for
-compile-time assertions using <tt>static_assert</tt> is enabled.</p>
-
-<h4 id="cxx_auto_type">C++11 type inference</h4>
-
-<p>Use <tt>__has_feature(cxx_auto_type)</tt> or
-<tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is
-supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
-will instead be a storage class specifier, as in C or C++98.</p>
-
-<h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4>
-
-<p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
-<tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
-strongly typed, scoped enumerations is enabled.</p>
-
-<h4 id="cxx_trailing_return">C++11 trailing return type</h4>
-
-<p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
-<tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
-alternate function declaration syntax with trailing return type is enabled.</p>
-
-<h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4>
-<p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if
-support for Unicode string literals is enabled.</p>
-
-<h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4>
-
-<p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled.</p>
-
-<h4 id="cxx_user_literals">C++11 user-defined literals</h4>
-
-<p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled.</p>
-
-<h4 id="cxx_variadic_templates">C++11 variadic templates</h4>
-
-<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
-<tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
-for variadic templates is enabled.</p>
-
-<h3 id="c11">C11</h3>
-
-<p>The features listed below are part of the C11 standard. As a result, all
-these features are enabled with the <tt>-std=c11</tt> or <tt>-std=gnu11</tt>
-option when compiling C code. Additionally, because these features are all
-backward-compatible, they are available as extensions in all language modes.</p>
-
-<h4 id="c_alignas">C11 alignment specifiers</h4>
-
-<p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt>
-to determine if support for alignment specifiers using <tt>_Alignas</tt>
-is enabled.</p>
-
-<h4 id="c_atomic">C11 atomic operations</h4>
-
-<p>Use <tt>__has_feature(c_atomic)</tt> or <tt>__has_extension(c_atomic)</tt>
-to determine if support for atomic types using <tt>_Atomic</tt> is enabled.
-Clang also provides <a href="#__c11_atomic">a set of builtins</a> which can be
-used to implement the <tt><stdatomic.h></tt> operations on
-<tt>_Atomic</tt> types.</p>
-
-<h4 id="c_generic_selections">C11 generic selections</h4>
-
-<p>Use <tt>__has_feature(c_generic_selections)</tt> or
-<tt>__has_extension(c_generic_selections)</tt> to determine if support for
-generic selections is enabled.</p>
-
-<p>As an extension, the C11 generic selection expression is available in all
-languages supported by Clang. The syntax is the same as that given in the
-C11 standard.</p>
-
-<p>In C, type compatibility is decided according to the rules given in the
-appropriate standard, but in C++, which lacks the type compatibility rules
-used in C, types are considered compatible only if they are equivalent.</p>
-
-<h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4>
-
-<p>Use <tt>__has_feature(c_static_assert)</tt> or
-<tt>__has_extension(c_static_assert)</tt> to determine if support for
-compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
-
-<!-- ======================================================================= -->
-<h2 id="checking_type_traits">Checks for Type Traits</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports the <a href="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_extension(X)</code> indicates the presence of the type trait. For example:
-<blockquote>
-<pre>
-#if __has_extension(is_convertible_to)
-template<typename From, typename To>
-struct is_convertible_to {
- static const bool value = __is_convertible_to(From, To);
-};
-#else
-// Emulate type trait
-#endif
-</pre>
-</blockquote>
-
-<p>The following type traits are supported by Clang:</p>
-<ul>
- <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
- <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
- <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
- <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
- <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
- <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
- <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
- <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
- <li><code>__is_abstract</code> (GNU, Microsoft)</li>
- <li><code>__is_base_of</code> (GNU, Microsoft)</li>
- <li><code>__is_class</code> (GNU, Microsoft)</li>
- <li><code>__is_convertible_to</code> (Microsoft)</li>
- <li><code>__is_empty</code> (GNU, Microsoft)</li>
- <li><code>__is_enum</code> (GNU, Microsoft)</li>
- <li><code>__is_interface_class</code> (Microsoft)</li>
- <li><code>__is_pod</code> (GNU, Microsoft)</li>
- <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
- <li><code>__is_union</code> (GNU, Microsoft)</li>
- <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
- <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li>
- <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li>
- <li><code>__is_trivially_assignable(totype, fromtype)</code>: Determines whether a value of type <tt>totype</tt> can be assigned to from a value of type <tt>fromtype</tt> such that no non-trivial functions are called as part of that assignment. This trait is required to implement the C++11 standard library.</li>
- <li><code>__is_trivially_constructible(type, argtypes...)</code>: Determines whether a value of type <tt>type</tt> can be direct-initialized with arguments of types <tt>argtypes...</tt> such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library.</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="blocks">Blocks</h2>
-<!-- ======================================================================= -->
-
-<p>The syntax and high level language feature description is in <a
-href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
-details for the clang implementation are in <a
-href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
-
-
-<p>Query for this feature with __has_extension(blocks).</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_features">Objective-C Features</h2>
-<!-- ======================================================================= -->
-
-<h3 id="objc_instancetype">Related result types</h3>
-
-<p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p>
-
-<blockquote>
-<pre>
- at interface NSObject
-+ (id)alloc;
-- (id)init;
- at end
-
- at interface NSArray : NSObject
- at end
-</pre>
-</blockquote>
-
-<p>and this common initialization pattern</p>
-
-<blockquote>
-<pre>
-NSArray *array = [[NSArray alloc] init];
-</pre>
-</blockquote>
-
-<p>the type of the expression <code>[NSArray alloc]</code> is
-<code>NSArray*</code> because <code>alloc</code> implicitly has a
-related result type. Similarly, the type of the expression
-<code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
-<code>init</code> has a related result type and its receiver is known
-to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p>
-
-<p>A method with a related result type can be declared by using the
-type <tt>instancetype</tt> as its result type. <tt>instancetype</tt>
-is a contextual keyword that is only permitted in the result type of
-an Objective-C method, e.g.</p>
-
-<pre>
- at interface A
-+ (<b>instancetype</b>)constructAnA;
- at end
-</pre>
-
-<p>The related result type can also be inferred for some methods.
-To determine whether a method has an inferred related result type, the first
-word in the camel-case selector (e.g., "init" in "initWithObjects") is
-considered, and the method will have a related result type if its return
-type is compatible with the type of its class and if</p>
-
-<ul>
-
- <li>the first word is "alloc" or "new", and the method is a class
- method, or</li>
-
- <li>the first word is "autorelease", "init", "retain", or "self",
- and the method is an instance method.</li>
-
-</ul>
-
-<p>If a method with a related result type is overridden by a subclass
-method, the subclass method must also return a type that is compatible
-with the subclass type. For example:</p>
-
-<blockquote>
-<pre>
- at interface NSString : NSObject
-- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
- at end
-</pre>
-</blockquote>
-
-<p>Related result types only affect the type of a message send or
-property access via the given method. In all other respects, a method
-with a related result type is treated the same way as method that
-returns <tt>id</tt>.</p>
-
-<p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether
-the <tt>instancetype</tt> contextual keyword is available.</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_arc">Automatic reference counting </h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides support for C++11 enumerations with a fixed
-underlying type within Objective-C. For example, one can write an
-enumeration type as:</p>
-
-<pre>
-typedef enum : unsigned char { Red, Green, Blue } Color;
-</pre>
-
-<p>This specifies that the underlying type, which is used to store the
-enumeration value, is <tt>unsigned char</tt>.</p>
-
-<p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether
-support for fixed underlying types is available in Objective-C.</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_lambdas">Interoperability with C++11 lambdas</h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides interoperability between C++11 lambdas and
-blocks-based APIs, by permitting a lambda to be implicitly converted
-to a block pointer with the corresponding signature. For example,
-consider an API such as <code>NSArray</code>'s array-sorting
-method:</p>
-
-<pre> - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; </pre>
-
-<p><code>NSComparator</code> is simply a typedef for the block pointer
-<code>NSComparisonResult (^)(id, id)</code>, and parameters of this
-type are generally provided with block literals as arguments. However,
-one can also use a C++11 lambda so long as it provides the same
-signature (in this case, accepting two parameters of type
-<code>id</code> and returning an <code>NSComparisonResult</code>):</p>
-
-<pre>
- NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
- @"String 02"];
- const NSStringCompareOptions comparisonOptions
- = NSCaseInsensitiveSearch | NSNumericSearch |
- NSWidthInsensitiveSearch | NSForcedOrderingSearch;
- NSLocale *currentLocale = [NSLocale currentLocale];
- NSArray *sorted
- = [array sortedArrayUsingComparator:<b>[=](id s1, id s2) -> NSComparisonResult {
- NSRange string1Range = NSMakeRange(0, [s1 length]);
- return [s1 compare:s2 options:comparisonOptions
- range:string1Range locale:currentLocale];
- }</b>];
- NSLog(@"sorted: %@", sorted);
-</pre>
-
-<p>This code relies on an implicit conversion from the type of the
-lambda expression (an unnamed, local class type called the <i>closure
-type</i>) to the corresponding block pointer type. The conversion
-itself is expressed by a conversion operator in that closure type
-that produces a block pointer with the same signature as the lambda
-itself, e.g.,</p>
-
-<pre>
- operator NSComparisonResult (^)(id, id)() const;
-</pre>
-
-<p>This conversion function returns a new block that simply forwards
-the two parameters to the lambda object (which it captures by copy),
-then returns the result. The returned block is first copied (with
-<tt>Block_copy</tt>) and then autoreleased. As an optimization, if a
-lambda expression is immediately converted to a block pointer (as in
-the first example, above), then the block is not copied and
-autoreleased: rather, it is given the same lifetime as a block literal
-written at that point in the program, which avoids the overhead of
-copying a block to the heap in the common case.</p>
-
-<p>The conversion from a lambda to a block pointer is only available
-in Objective-C++, and not in C++ with blocks, due to its use of
-Objective-C memory management (autorelease).</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_object_literals_subscripting">Object Literals and Subscripting</h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides support for <a href="ObjectiveCLiterals.html">Object Literals
-and Subscripting</a> in Objective-C, which simplifies common Objective-C
-programming patterns, makes programs more concise, and improves the safety of
-container creation. There are several feature macros associated with object
-literals and subscripting: <code>__has_feature(objc_array_literals)</code>
-tests the availability of array literals;
-<code>__has_feature(objc_dictionary_literals)</code> tests the availability of
-dictionary literals; <code>__has_feature(objc_subscripting)</code> tests the
-availability of object subscripting.</p>
-
-<!-- ======================================================================= -->
-<h2 id="objc_default_synthesize_properties">Objective-C Autosynthesis of Properties</h2>
-<!-- ======================================================================= -->
-
-<p> Clang provides support for autosynthesis of declared properties. Using this
-feature, clang provides default synthesis of those properties not declared @dynamic
-and not having user provided backing getter and setter methods.
-<code>__has_feature(objc_default_synthesize_properties)</code> checks for availability
-of this feature in version of clang being used.</p>
-
-<!-- ======================================================================= -->
-<h2 id="overloading-in-c">Function Overloading in C</h2>
-<!-- ======================================================================= -->
-
-<p>Clang provides support for C++ function overloading in C. Function
-overloading in C is introduced using the <tt>overloadable</tt> attribute. For
-example, one might provide several overloaded versions of a <tt>tgsin</tt>
-function that invokes the appropriate standard function computing the sine of a
-value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
-precision:</p>
-
-<blockquote>
-<pre>
-#include <math.h>
-float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
-double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
-long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
-</pre>
-</blockquote>
-
-<p>Given these declarations, one can call <tt>tgsin</tt> with a
-<tt>float</tt> value to receive a <tt>float</tt> result, with a
-<tt>double</tt> to receive a <tt>double</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>
- <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
- double</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>T*</tt> to a pointer of type
- <tt>U*</tt> is considered a pointer conversion (with conversion
- rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
-
- <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
- is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
- conversion is given "conversion" rank.</li>
-</ul>
-
-<p>The declaration of <tt>overloadable</tt> functions is restricted to
-function declarations and definitions. Most importantly, if any
-function with a given name is given the <tt>overloadable</tt>
-attribute, then all function declarations and definitions with that
-name (and in that scope) must have the <tt>overloadable</tt>
-attribute. This rule even applies to redeclarations of functions whose original
-declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
-
-<blockquote>
-<pre>
-int f(int) __attribute__((overloadable));
-float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
-
-int g(int) __attribute__((overloadable));
-int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
-</pre>
-</blockquote>
-
-<p>Functions marked <tt>overloadable</tt> must have
-prototypes. Therefore, the following code is ill-formed:</p>
-
-<blockquote>
-<pre>
-int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
-</pre>
-</blockquote>
-
-<p>However, <tt>overloadable</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>unavailable</tt> attribute:</p>
-
-<blockquote>
-<pre>
-void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
-</pre>
-</blockquote>
-
-<p>Functions declared with the <tt>overloadable</tt> attribute have
-their names mangled according to the same rules as C++ function
-names. For example, the three <tt>tgsin</tt> functions in our
-motivating example get the mangled names <tt>_Z5tgsinf</tt>,
-<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
-caveats to this use of name mangling:</p>
-
-<ul>
-
- <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>static inline</tt> with <tt>overloadable</tt> functions.</li>
-
- <li>The <tt>overloadable</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>overloadable</tt>
- function occurs within an <tt>extern "C"</tt> linkage specification,
- it's name <i>will</i> be mangled in the same way as it would in
- C.</li>
-</ul>
-
-<p>Query for this feature with __has_extension(attribute_overloadable).</p>
-
-<!-- ======================================================================= -->
-<h2 id="complex-list-init">Initializer lists for complex numbers in C</h2>
-<!-- ======================================================================= -->
-
-<p>clang supports an extension which allows the following in C:</p>
-
-<blockquote>
-<pre>
-#include <math.h>
-#include <complex.h>
-complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
-</pre>
-</blockquote>
-
-<p>This construct is useful because there is no way to separately
-initialize the real and imaginary parts of a complex variable in
-standard C, given that clang does not support <code>_Imaginary</code>.
-(clang also supports the <code>__real__</code> and <code>__imag__</code>
-extensions from gcc, which help in some cases, but are not usable in
-static initializers.)
-
-<p>Note that this extension does not allow eliding the braces; the
-meaning of the following two lines is different:</p>
-
-<blockquote>
-<pre>
-complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
-complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
-</pre>
-</blockquote>
-
-<p>This extension also works in C++ mode, as far as that goes, but does not
- apply to the C++ <code>std::complex</code>. (In C++11, list
- initialization allows the same syntax to be used with
- <code>std::complex</code> with the same meaning.)
-
-<!-- ======================================================================= -->
-<h2 id="builtins">Builtin Functions</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports a number of builtin library functions with the same syntax as
-GCC, including things like <tt>__builtin_nan</tt>,
-<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
-<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
-addition to the GCC builtins, Clang supports a number of builtins that GCC does
-not, which are listed here.</p>
-
-<p>Please note that Clang does not and will not support all of the GCC builtins
-for vector operations. Instead of using builtins, you should use the functions
-defined in target-specific header files like <tt><xmmintrin.h></tt>, which
-define portable wrappers for these. Many of the Clang versions of these
-functions are implemented directly in terms of <a href="#vectors">extended
-vector support</a> instead of builtins, in order to reduce the number of
-builtins that we need to implement.</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__builtin_readcyclecounter">__builtin_readcyclecounter</a></h3>
-<!-- ======================================================================= -->
-
-<p><tt>__builtin_readcyclecounter</tt> is used to access the cycle counter
-register (or a similar low-latency, high-accuracy clock) on those targets that
-support it.
-</p>
-
-<p><b>Syntax:</b></p>
-
-<pre>
-__builtin_readcyclecounter()
-</pre>
-
-<p><b>Example of Use:</b></p>
-
-<pre>
-unsigned long long t0 = __builtin_readcyclecounter();
-do_something();
-unsigned long long t1 = __builtin_readcyclecounter();
-unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
-</pre>
-
-<p><b>Description:</b></p>
-
-<p>The __builtin_readcyclecounter() builtin returns the cycle counter value,
-which may be either global or process/thread-specific depending on the target.
-As the backing counters often overflow quickly (on the order of
-seconds) this should only be used for timing small intervals. When not
-supported by the target, the return value is always zero. This builtin
-takes no arguments and produces an unsigned long long result.
-</p>
-
-<p>Query for this feature with __has_builtin(__builtin_readcyclecounter).</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
-<!-- ======================================================================= -->
-
-<p><tt>__builtin_shufflevector</tt> is used to express generic vector
-permutation/shuffle/swizzle operations. This builtin is also very important for
-the implementation of various target-specific header files like
-<tt><xmmintrin.h></tt>.
-</p>
-
-<p><b>Syntax:</b></p>
-
-<pre>
-__builtin_shufflevector(vec1, vec2, index1, index2, ...)
-</pre>
-
-<p><b>Examples:</b></p>
-
-<pre>
- // Identity operation - return 4-element vector V1.
- __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
-
- // "Splat" element 0 of V1 into a 4-element result.
- __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
-
- // Reverse 4-element vector V1.
- __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
-
- // Concatenate every other element of 4-element vectors V1 and V2.
- __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
-
- // Concatenate every other element of 8-element vectors V1 and V2.
- __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
-</pre>
-
-<p><b>Description:</b></p>
-
-<p>The first two arguments to __builtin_shufflevector are vectors that have the
-same element type. The remaining arguments are a list of integers that specify
-the elements indices of the first two vectors that should be extracted and
-returned in a new vector. These element indices are numbered sequentially
-starting with the first vector, continuing into the second vector. Thus, if
-vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
-</p>
-
-<p>The result of __builtin_shufflevector is a vector
-with the same element type as vec1/vec2 but that has an element count equal to
-the number of indices specified.
-</p>
-
-<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
-<!-- ======================================================================= -->
-
-<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
-the program cannot be reached, even if the compiler might otherwise think it
-can. This is useful to improve optimization and eliminates certain warnings.
-For example, without the <tt>__builtin_unreachable</tt> in the example below,
-the compiler assumes that the inline asm can fall through and prints a "function
-declared 'noreturn' should not return" warning.
-</p>
-
-<p><b>Syntax:</b></p>
-
-<pre>
-__builtin_unreachable()
-</pre>
-
-<p><b>Example of Use:</b></p>
-
-<pre>
-void myabort(void) __attribute__((noreturn));
-void myabort(void) {
- asm("int3");
- __builtin_unreachable();
-}
-</pre>
-
-<p><b>Description:</b></p>
-
-<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
-it has undefined behavior, it is a statement that it is never reached and the
-optimizer can take advantage of this to produce better code. This builtin takes
-no arguments and produces a void result.
-</p>
-
-<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__sync_swap">__sync_swap</a></h3>
-<!-- ======================================================================= -->
-
-<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
-memory.
-</p>
-
-<p><b>Syntax:</b></p>
-
-<pre>
-<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
-</pre>
-
-<p><b>Example of Use:</b></p>
-
-<pre>
-int old_value = __sync_swap(&value, new_value);
-</pre>
-
-<p><b>Description:</b></p>
-
-<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
-intrinsics to allow code to atomically swap the current value with the new
-value. More importantly, it helps developers write more efficient and correct
-code by avoiding expensive loops around __sync_bool_compare_and_swap() or
-relying on the platform specific implementation details of
-__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
-</p>
-
-<!-- ======================================================================= -->
-<h3><a name="__c11_atomic">__c11_atomic builtins</a></h3>
-<!-- ======================================================================= -->
-
-<p>Clang provides a set of builtins which are intended to be used to implement
-C11's <tt><stdatomic.h></tt> header. These builtins provide the semantics
-of the <tt>_explicit</tt> form of the corresponding C11 operation, and are named
-with a <tt>__c11_</tt> prefix. The supported operations are:</p>
-
-<ul>
- <li><tt>__c11_atomic_init</tt></li>
- <li><tt>__c11_atomic_thread_fence</tt></li>
- <li><tt>__c11_atomic_signal_fence</tt></li>
- <li><tt>__c11_atomic_is_lock_free</tt></li>
- <li><tt>__c11_atomic_store</tt></li>
- <li><tt>__c11_atomic_load</tt></li>
- <li><tt>__c11_atomic_exchange</tt></li>
- <li><tt>__c11_atomic_compare_exchange_strong</tt></li>
- <li><tt>__c11_atomic_compare_exchange_weak</tt></li>
- <li><tt>__c11_atomic_fetch_add</tt></li>
- <li><tt>__c11_atomic_fetch_sub</tt></li>
- <li><tt>__c11_atomic_fetch_and</tt></li>
- <li><tt>__c11_atomic_fetch_or</tt></li>
- <li><tt>__c11_atomic_fetch_xor</tt></li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="non-standard-attributes">Non-standard C++11 Attributes</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports one non-standard C++11 attribute. It resides in the
-<tt>clang</tt> attribute namespace.</p>
-
-<!-- ======================================================================= -->
-<h3 id="clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</h3>
-<!-- ======================================================================= -->
-
-<p>The <tt>clang::fallthrough</tt> attribute is used along with the
-<tt>-Wimplicit-fallthrough</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>break;</tt>, so it can be placed in most places
-where <tt>break;</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>
-<pre>
-// compile with -Wimplicit-fallthrough
-switch (n) {
-case 22:
-case 33: // no warning: no statements between case labels
- f();
-case 44: // warning: unannotated fall-through
- g();
- <b>[[clang::fallthrough]];</b>
-case 55: // no warning
- if (x) {
- h();
- break;
- }
- else {
- i();
- <b>[[clang::fallthrough]];</b>
- }
-case 66: // no warning
- p();
- <b>[[clang::fallthrough]];</b> // warning: fallthrough annotation does not directly precede case label
- q();
-case 77: // warning: unannotated fall-through
- r();
-}
-</pre>
-
-<!-- ======================================================================= -->
-<h2 id="targetspecific">Target-Specific Extensions</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports some language features conditionally on some targets.</p>
-
-<!-- ======================================================================= -->
-<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
-<!-- ======================================================================= -->
-
-<p>The X86 backend has these language extensions:</p>
-
-<!-- ======================================================================= -->
-<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
-<!-- ======================================================================= -->
-
-<p>Annotating a pointer with address space #256 causes it to be code generated
-relative to the X86 GS segment register, and address space #257 causes it to be
-relative to the X86 FS segment. Note that this is a very very low-level
-feature that should only be used if you know what you're doing (for example in
-an OS kernel).</p>
-
-<p>Here is an example:</p>
-
-<pre>
-#define GS_RELATIVE __attribute__((address_space(256)))
-int foo(int GS_RELATIVE *P) {
- return *P;
-}
-</pre>
-
-<p>Which compiles to (on X86-32):</p>
-
-<pre>
-_foo:
- movl 4(%esp), %eax
- movl %gs:(%eax), %eax
- ret
-</pre>
-
-<!-- ======================================================================= -->
-<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports additional attributes that are useful for documenting program
-invariants and rules for static analysis tools. The extensions documented here
-are used by the <a
-href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
-engine</a> that is part of Clang's Analysis library.</p>
-
-<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
-
-<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
-attribute. This attribute, which is typically affixed to a function prototype,
-indicates that a call to a given function never returns. Function prototypes for
-common functions like <tt>exit</tt> are typically annotated with this attribute,
-as well as a variety of common assertion handlers. Users can educate the static
-analyzer about their own custom assertion handles (thus cutting down on false
-positives due to false paths) by marking their own "panic" functions
-with this attribute.</p>
-
-<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
-there are special functions that for all intents and purposes should be
-considered panic functions (i.e., they are only called when an internal program
-error occurs) but may actually return so that the program can fail gracefully.
-The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
-as being interpreted as "no return" functions by the analyzer (thus
-pruning bogus paths) but will not affect compilation (as in the case of
-<tt>noreturn</tt>).</p>
-
-<p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
-same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
-placed at the end of function prototypes:</p>
-
-<pre>
- void foo() <b>__attribute__((analyzer_noreturn))</b>;
-</pre>
-
-<p>Query for this feature with
-<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
-
-<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
-
-<p>Many methods in Objective-C have conventional meanings determined
-by their selectors. For the purposes of static analysis, 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 <q>method family</q> that a method belongs to.</p>
-
-<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
-where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
-<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
-can only be placed at the end of a method declaration:</p>
-
-<pre>
- - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
-</pre>
-
-<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
-<a href="#attr_retain_release">retaining behavior attributes</a>
-described below.</p>
-
-<p>Query for this feature with
-<tt>__has_attribute(objc_method_family)</tt>.</p>
-
-<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
-
-<p>In Objective-C, functions and methods are generally assumed to take
-and return objects with +0 retain counts, with some exceptions for
-special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
-there are exceptions, and so Clang provides attributes to allow these
-exceptions to be documented, which helps the analyzer find leaks (and
-ignore non-leaks). Some exceptions may be better described using
-the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
-attribute instead.</p>
-
-<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
-<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
-and <tt>cf_returns_not_retained</tt> attributes can be placed on
-methods and functions that return Objective-C or CoreFoundation
-objects. They are commonly placed at the end of a function prototype
-or method declaration:</p>
-
-<pre>
- id foo() <b>__attribute__((ns_returns_retained))</b>;
-
- - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
-</pre>
-
-<p>The <tt>*_returns_retained</tt> attributes specify that the
-returned object has a +1 retain count.
-The <tt>*_returns_not_retained</tt> attributes specify that the return
-object has a +0 retain count, even if the normal convention for its
-selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
-returned object is +0, but is guaranteed to live at least as long as the
-next flush of an autorelease pool.</p>
-
-<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
-attributes can be placed on an parameter declaration; they specify
-that the argument is expected to have a +1 retain count, which will be
-balanced in some way by the function or method.
-The <tt>ns_consumes_self</tt> attribute can only be placed on an
-Objective-C method; it specifies that the method expects
-its <tt>self</tt> parameter to have a +1 retain count, which it will
-balance in some way.</p>
-
-<pre>
- void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
-
- - (void) bar <b>__attribute__((ns_consumes_self))</b>;
- - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
-</pre>
-
-<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
-<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
-
-<!-- ======================================================================= -->
-<h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2>
-<!-- ======================================================================= -->
-<h3 id="address_sanitizer">AddressSanitizer</h3>
-<p> Use <code>__has_feature(address_sanitizer)</code>
-to check if the code is being built with <a
- href="AddressSanitizer.html">AddressSanitizer</a>.
-</p>
-<p>Use <tt>__attribute__((no_address_safety_analysis))</tt> on a function
-declaration to specify that address safety instrumentation (e.g.
-AddressSanitizer) should not be applied to that function.
-</p>
-
-<!-- ======================================================================= -->
-<h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports additional attributes for checking basic locking policies in
-multithreaded programs.
-Clang currently parses the following list of attributes, although
-<b>the implementation for these annotations is currently in development.</b>
-For more details, see the
-<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
-</p>
-
-<h4 id="ts_noanal">no_thread_safety_analysis</h4>
-
-<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
-declaration to specify that the thread safety analysis should not be run on that
-function. This attribute provides an escape hatch (e.g. for situations when it
-is difficult to annotate the locking policy). </p>
-
-<h4 id="ts_lockable">lockable</h4>
-
-<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
-that it has a lockable type (e.g. a Mutex class). This annotation is primarily
-used to check consistency.</p>
-
-<h4 id="ts_scopedlockable">scoped_lockable</h4>
-
-<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
-specify that it has a "scoped" lockable type. Objects of this type will acquire
-the lock upon construction and release it upon going out of scope.
- This annotation is primarily used to check
-consistency.</p>
-
-<h4 id="ts_guardedvar">guarded_var</h4>
-
-<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
-specify that the variable must be accessed while holding some lock.</p>
-
-<h4 id="ts_ptguardedvar">pt_guarded_var</h4>
-
-<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
-specify that the pointer must be dereferenced while holding some lock.</p>
-
-<h4 id="ts_guardedby">guarded_by(l)</h4>
-
-<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
-specify that the variable must be accessed while holding lock <tt>l</tt>.</p>
-
-<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
-
-<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
-specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p>
-
-<h4 id="ts_acquiredbefore">acquired_before(...)</h4>
-
-<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
-of a lockable variable to specify that the lock must be acquired before all
-attribute arguments. Arguments must be lockable type, and there must be at
-least one argument.</p>
-
-<h4 id="ts_acquiredafter">acquired_after(...)</h4>
-
-<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
-of a lockable variable to specify that the lock must be acquired after all
-attribute arguments. Arguments must be lockable type, and there must be at
-least one argument.</p>
-
-<h4 id="ts_elf">exclusive_lock_function(...)</h4>
-
-<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
-declaration to specify that the function acquires all listed locks
-exclusively. This attribute takes zero or more arguments: either of lockable
-type or integers indexing into function parameters of lockable type. If no
-arguments are given, the acquired lock is implicitly <tt>this</tt> of the
-enclosing object.</p>
-
-<h4 id="ts_slf">shared_lock_function(...)</h4>
-
-<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
-declaration to specify that the function acquires all listed locks, although
- the locks may be shared (e.g. read locks). This attribute takes zero or more
-arguments: either of lockable type or integers indexing into function
-parameters of lockable type. If no arguments are given, the acquired lock is
-implicitly <tt>this</tt> of the enclosing object.</p>
-
-<h4 id="ts_etf">exclusive_trylock_function(...)</h4>
-
-<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
-declaration to specify that the function will try (without blocking) to acquire
-all listed locks exclusively. This attribute takes one or more arguments. The
-first argument is an integer or boolean value specifying the return value of a
-successful lock acquisition. The remaining arugments are either of lockable type
-or integers indexing into function parameters of lockable type. If only one
-argument is given, the acquired lock is implicitly <tt>this</tt> of the
-enclosing object.</p>
-
-<h4 id="ts_stf">shared_trylock_function(...)</h4>
-
-<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
-declaration to specify that the function will try (without blocking) to acquire
-all listed locks, although the locks may be shared (e.g. read locks). This
-attribute takes one or more arguments. The first argument is an integer or
-boolean value specifying the return value of a successful lock acquisition. The
-remaining arugments are either of lockable type or integers indexing into
-function parameters of lockable type. If only one argument is given, the
-acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
-
-<h4 id="ts_uf">unlock_function(...)</h4>
-
-<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
-declaration to specify that the function release all listed locks. This
-attribute takes zero or more arguments: either of lockable type or integers
-indexing into function parameters of lockable type. If no arguments are given,
-the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
-
-<h4 id="ts_lr">lock_returned(l)</h4>
-
-<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
-declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt>
-must be of lockable type). This annotation is used to aid in resolving lock
-expressions.</p>
-
-<h4 id="ts_le">locks_excluded(...)</h4>
-
-<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
-to specify that the function must not be called with the listed locks. Arguments
-must be lockable type, and there must be at least one argument.</p>
-
-<h4 id="ts_elr">exclusive_locks_required(...)</h4>
-
-<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
-declaration to specify that the function must be called while holding the listed
-exclusive locks. Arguments must be lockable type, and there must be at
-least one argument.</p>
-
-<h4 id="ts_slr">shared_locks_required(...)</h4>
-
-<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
-declaration to specify that the function must be called while holding the listed
-shared locks. Arguments must be lockable type, and there must be at
-least one argument.</p>
-
-<!-- ======================================================================= -->
-<h2 id="type_safety">Type Safety Checking</h2>
-<!-- ======================================================================= -->
-
-<p>Clang supports additional attributes to enable checking type safety
-properties that can't be enforced by C type system. Usecases include:</p>
-<ul>
-<li>MPI library implementations, where these attributes enable checking that
- buffer type matches the passed <tt>MPI_Datatype</tt>;</li>
-<li>for HDF5 library there is a similar usecase as MPI;</li>
-<li>checking types of variadic functions' arguments for functions like
- <tt>fcntl()</tt> and <tt>ioctl()</tt>.</li>
-</ul>
-
-<p>You can detect support for these attributes with __has_attribute(). For
-example:</p>
-
-<blockquote>
-<pre>
-#if defined(__has_attribute)
-# if __has_attribute(argument_with_type_tag) && \
- __has_attribute(pointer_with_type_tag) && \
- __has_attribute(type_tag_for_datatype)
-# define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
-/* ... other macros ... */
-# endif
-#endif
-
-#if !defined(ATTR_MPI_PWT)
-#define ATTR_MPI_PWT(buffer_idx, type_idx)
-#endif
-
-int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
- ATTR_MPI_PWT(1,3);
-</pre>
-</blockquote>
-
-<h3 id="argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></h3>
-
-<p>Use <tt>__attribute__((argument_with_type_tag(arg_kind, arg_idx,
-type_tag_idx)))</tt> on a function declaration to specify that the function
-accepts a type tag that determines the type of some other argument.
-<tt>arg_kind</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>pointer_with_type_tag</tt> can be used in most of non-variadic
-cases).</p>
-
-<p>For example:</p>
-<blockquote>
-<pre>
-int fcntl(int fd, int cmd, ...)
- __attribute__(( argument_with_type_tag(fcntl,3,2) ));
-</pre>
-</blockquote>
-
-<h3 id="pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></h3>
-
-<p>Use <tt>__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx,
-type_tag_idx)))</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>
-<blockquote>
-<pre>
-int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
- __attribute__(( pointer_with_type_tag(mpi,1,3) ));
-</pre>
-</blockquote>
-
-<h3 id="type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></h3>
-
-<p>Clang supports annotating type tags of two forms.</p>
-
-<ul>
-<li><b>Type tag that is an expression containing a reference to some declared
-identifier.</b> Use <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt>
-on a declaration with that identifier:
-
-<blockquote>
-<pre>
-extern struct mpi_datatype mpi_datatype_int
- __attribute__(( type_tag_for_datatype(mpi,int) ));
-#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
-</pre>
-</blockquote></li>
-
-<li><b>Type tag that is an integral literal.</b> Introduce a <tt>static
-const</tt> variable with a corresponding initializer value and attach
-<tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> on that
-declaration, for example:
-
-<blockquote>
-<pre>
-#define MPI_INT ((MPI_Datatype) 42)
-static const MPI_Datatype mpi_datatype_int
- __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
-</pre>
-</blockquote></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><tt>layout_compatible</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>MPI_DOUBLE_INT</tt>.
-
-<p>For example:</p>
-<blockquote>
-<pre>
-/* In mpi.h */
-struct internal_mpi_double_int { double d; int i; };
-extern struct mpi_datatype mpi_datatype_double_int
- __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int,
- layout_compatible) ));
-
-#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
-
-/* In user code */
-struct my_pair { double a; int b; };
-struct my_pair *buffer;
-MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
-
-struct my_int_pair { int a; int b; }
-struct my_int_pair *buffer2;
-MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
- // type 'struct my_int_pair'
- // doesn't match specified MPI_Datatype
-</pre>
-</blockquote>
-</li>
-
-<li><tt>must_be_null</tt> specifies that the expression should be a null
-pointer constant, for example:
-
-<blockquote>
-<pre>
-/* In mpi.h */
-extern struct mpi_datatype mpi_datatype_null
- __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
-
-#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
-
-/* In user code */
-MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
- // was specified but buffer
- // is not a null pointer
-</pre>
-</blockquote>
-</li>
-</ul>
-
-</div>
-</body>
-</html>
Added: cfe/trunk/docs/LanguageExtensions.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/LanguageExtensions.rst (added)
+++ cfe/trunk/docs/LanguageExtensions.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,1838 @@
+=========================
+Clang Language Extensions
+=========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document describes the language extensions provided by Clang. In addition
+to the language extensions listed here, Clang aims to support a broad range of
+GCC extensions. Please see the `GCC manual
+<http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
+these extensions.
+
+.. _langext-feature_check:
+
+Feature Checking Macros
+=======================
+
+Language extensions can be very useful, but only if you know you can depend on
+them. In order to allow fine-grain features checks, we support three builtin
+function-like macros. This allows you to directly test for a feature in your
+code without having to resort to something like autoconf or fragile "compiler
+version checks".
+
+``__has_builtin``
+-----------------
+
+This function-like macro takes a single identifier argument that is the name of
+a builtin function. It evaluates to 1 if the builtin is supported or 0 if not.
+It can be used like this:
+
+.. code-block:: c++
+
+ #ifndef __has_builtin // Optional of course.
+ #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
+ #endif
+
+ ...
+ #if __has_builtin(__builtin_trap)
+ __builtin_trap();
+ #else
+ abort();
+ #endif
+ ...
+
+.. _langext-__has_feature-__has_extension:
+
+``__has_feature`` and ``__has_extension``
+-----------------------------------------
+
+These function-like macros take a single identifier argument that is the name
+of a feature. ``__has_feature`` evaluates to 1 if the feature is both
+supported by Clang and standardized in the current language standard or 0 if
+not (but see :ref:`below <langext-has-feature-back-compat>`), while
+``__has_extension`` evaluates to 1 if the feature is supported by Clang in the
+current language (either as a language extension or a standard language
+feature) or 0 if not. They can be used like this:
+
+.. code-block:: c++
+
+ #ifndef __has_feature // Optional of course.
+ #define __has_feature(x) 0 // Compatibility with non-clang compilers.
+ #endif
+ #ifndef __has_extension
+ #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
+ #endif
+
+ ...
+ #if __has_feature(cxx_rvalue_references)
+ // This code will only be compiled with the -std=c++11 and -std=gnu++11
+ // options, because rvalue references are only standardized in C++11.
+ #endif
+
+ #if __has_extension(cxx_rvalue_references)
+ // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
+ // and -std=gnu++98 options, because rvalue references are supported as a
+ // language extension in C++98.
+ #endif
+
+.. _langext-has-feature-back-compat:
+
+For backwards compatibility reasons, ``__has_feature`` can also be used to test
+for support for non-standardized features, i.e. features not prefixed ``c_``,
+``cxx_`` or ``objc_``.
+
+Another use of ``__has_feature`` is to check for compiler features not related
+to the language standard, such as e.g. `AddressSanitizer
+<AddressSanitizer.html>`_.
+
+If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
+to ``__has_feature``.
+
+The feature tag is described along with the language feature below.
+
+The feature name or extension name can also be specified with a preceding and
+following ``__`` (double underscore) to avoid interference from a macro with
+the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
+of ``cxx_rvalue_references``.
+
+``__has_attribute``
+-------------------
+
+This function-like macro takes a single identifier argument that is the name of
+an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
+can be used like this:
+
+.. code-block:: c++
+
+ #ifndef __has_attribute // Optional of course.
+ #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
+ #endif
+
+ ...
+ #if __has_attribute(always_inline)
+ #define ALWAYS_INLINE __attribute__((always_inline))
+ #else
+ #define ALWAYS_INLINE
+ #endif
+ ...
+
+The attribute name can also be specified with a preceding and following ``__``
+(double underscore) to avoid interference from a macro with the same name. For
+instance, ``__always_inline__`` can be used instead of ``always_inline``.
+
+Include File Checking Macros
+============================
+
+Not all developments systems have the same include files. The
+:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
+you to check for the existence of an include file before doing a possibly
+failing ``#include`` directive.
+
+.. _langext-__has_include:
+
+``__has_include``
+-----------------
+
+This function-like macro takes a single file name string argument that is the
+name of an include file. It evaluates to 1 if the file can be found using the
+include paths, or 0 otherwise:
+
+.. code-block:: c++
+
+ // Note the two possible file name string formats.
+ #if __has_include("myinclude.h") && __has_include(<stdint.h>)
+ # include "myinclude.h"
+ #endif
+
+ // To avoid problem with non-clang compilers not having this macro.
+ #if defined(__has_include) && __has_include("myinclude.h")
+ # include "myinclude.h"
+ #endif
+
+To test for this feature, use ``#if defined(__has_include)``.
+
+.. _langext-__has_include_next:
+
+``__has_include_next``
+----------------------
+
+This function-like macro takes a single file name string argument that is the
+name of an include file. It is like ``__has_include`` except that it looks for
+the second instance of the given file found in the include paths. It evaluates
+to 1 if the second instance of the file can be found using the include paths,
+or 0 otherwise:
+
+.. code-block:: c++
+
+ // Note the two possible file name string formats.
+ #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
+ # include_next "myinclude.h"
+ #endif
+
+ // To avoid problem with non-clang compilers not having this macro.
+ #if defined(__has_include_next) && __has_include_next("myinclude.h")
+ # include_next "myinclude.h"
+ #endif
+
+Note that ``__has_include_next``, like the GNU extension ``#include_next``
+directive, is intended for use in headers only, and will issue a warning if
+used in the top-level compilation file. A warning will also be issued if an
+absolute path is used in the file argument.
+
+``__has_warning``
+-----------------
+
+This function-like macro takes a string literal that represents a command line
+option for a warning and returns true if that is a valid warning option.
+
+.. code-block:: c++
+
+ #if __has_warning("-Wformat")
+ ...
+ #endif
+
+Builtin Macros
+==============
+
+``__BASE_FILE__``
+ Defined to a string that contains the name of the main input file passed to
+ Clang.
+
+``__COUNTER__``
+ Defined to an integer value that starts at zero and is incremented each time
+ the ``__COUNTER__`` macro is expanded.
+
+``__INCLUDE_LEVEL__``
+ Defined to an integral value that is the include depth of the file currently
+ being translated. For the main file, this value is zero.
+
+``__TIMESTAMP__``
+ Defined to the date and time of the last modification of the current source
+ file.
+
+``__clang__``
+ Defined when compiling with Clang
+
+``__clang_major__``
+ Defined to the major marketing version number of Clang (e.g., the 2 in
+ 2.0.1). Note that marketing version numbers should not be used to check for
+ language features, as different vendors use different numbering schemes.
+ Instead, use the :ref:`langext-feature_check`.
+
+``__clang_minor__``
+ Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
+ that marketing version numbers should not be used to check for language
+ features, as different vendors use different numbering schemes. Instead, use
+ the :ref:`langext-feature_check`.
+
+``__clang_patchlevel__``
+ Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
+
+``__clang_version__``
+ Defined to a string that captures the Clang marketing version, including the
+ Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``".
+
+.. _langext-vectors:
+
+Vectors and Extended Vectors
+============================
+
+Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
+
+OpenCL vector types are created using ``ext_vector_type`` attribute. It
+support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
+is:
+
+.. code-block:: c++
+
+ typedef float float4 __attribute__((ext_vector_type(4)));
+ typedef float float2 __attribute__((ext_vector_type(2)));
+
+ float4 foo(float2 a, float2 b) {
+ float4 c;
+ c.xz = a;
+ c.yw = b;
+ return c;
+ }
+
+Query for this feature with ``__has_extension(attribute_ext_vector_type)``.
+
+Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax
+and functions. For example:
+
+.. code-block:: c++
+
+ vector float foo(vector int a) {
+ vector int b;
+ b = vec_add(a, a) + a;
+ return (vector float)b;
+ }
+
+NEON vector types are created using ``neon_vector_type`` and
+``neon_polyvector_type`` attributes. For example:
+
+.. code-block:: c++
+
+ typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
+ typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
+
+ int8x8_t foo(int8x8_t a) {
+ int8x8_t v;
+ v = a;
+ return v;
+ }
+
+Vector Literals
+---------------
+
+Vector literals can be used to create vectors from a set of scalars, or
+vectors. Either parentheses or braces form can be used. In the parentheses
+form the number of literal values specified must be one, i.e. referring to a
+scalar value, or must match the size of the vector type being created. If a
+single scalar literal value is specified, the scalar literal value will be
+replicated to all the components of the vector type. In the brackets form any
+number of literals can be specified. For example:
+
+.. code-block:: c++
+
+ typedef int v4si __attribute__((__vector_size__(16)));
+ typedef float float4 __attribute__((ext_vector_type(4)));
+ typedef float float2 __attribute__((ext_vector_type(2)));
+
+ v4si vsi = (v4si){1, 2, 3, 4};
+ float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
+ vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
+ vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
+ vector int vi3 = (vector int)(1, 2); // error
+ vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
+ vector int vi5 = (vector int)(1, 2, 3, 4);
+ float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
+
+Vector Operations
+-----------------
+
+The table below shows the support for each operation by vector extension. A
+dash indicates that an operation is not accepted according to a corresponding
+specification.
+
+============================== ====== ======= === ====
+ Opeator OpenCL AltiVec GCC NEON
+============================== ====== ======= === ====
+[] yes yes yes --
+unary operators +, -- yes yes yes --
+++, -- -- yes yes yes --
++,--,*,/,% yes yes yes --
+bitwise operators &,|,^,~ yes yes yes --
+>>,<< yes yes yes --
+!, &&, || no -- -- --
+==, !=, >, <, >=, <= yes yes -- --
+= yes yes yes yes
+:? yes -- -- --
+sizeof yes yes yes yes
+============================== ====== ======= === ====
+
+See also :ref:`langext-__builtin_shufflevector`.
+
+Messages on ``deprecated`` and ``unavailable`` Attributes
+=========================================================
+
+An optional string message can be added to the ``deprecated`` and
+``unavailable`` attributes. For example:
+
+.. code-block:: c++
+
+ void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
+
+If the deprecated or unavailable declaration is used, the message will be
+incorporated into the appropriate diagnostic:
+
+.. code-block:: c++
+
+ harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
+ [-Wdeprecated-declarations]
+ explode();
+ ^
+
+Query for this feature with
+``__has_extension(attribute_deprecated_with_message)`` and
+``__has_extension(attribute_unavailable_with_message)``.
+
+Attributes on Enumerators
+=========================
+
+Clang allows attributes to be written on individual enumerators. This allows
+enumerators to be deprecated, made unavailable, etc. The attribute must appear
+after the enumerator name and before any initializer, like so:
+
+.. code-block:: c++
+
+ enum OperationMode {
+ OM_Invalid,
+ OM_Normal,
+ OM_Terrified __attribute__((deprecated)),
+ OM_AbortOnError __attribute__((deprecated)) = 4
+ };
+
+Attributes on the ``enum`` declaration do not apply to individual enumerators.
+
+Query for this feature with ``__has_extension(enumerator_attributes)``.
+
+'User-Specified' System Frameworks
+==================================
+
+Clang provides a mechanism by which frameworks can be built in such a way that
+they will always be treated as being "system frameworks", even if they are not
+present in a system framework directory. This can be useful to system
+framework developers who want to be able to test building other applications
+with development builds of their framework, including the manner in which the
+compiler changes warning behavior for system headers.
+
+Framework developers can opt-in to this mechanism by creating a
+"``.system_framework``" file at the top-level of their framework. That is, the
+framework should have contents like:
+
+.. code-block:: none
+
+ .../TestFramework.framework
+ .../TestFramework.framework/.system_framework
+ .../TestFramework.framework/Headers
+ .../TestFramework.framework/Headers/TestFramework.h
+ ...
+
+Clang will treat the presence of this file as an indicator that the framework
+should be treated as a system framework, regardless of how it was found in the
+framework search path. For consistency, we recommend that such files never be
+included in installed versions of the framework.
+
+Availability attribute
+======================
+
+Clang introduces the ``availability`` attribute, which 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 ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` 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 ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+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 ``f()`` is no longer available.
+
+The availablility 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:
+
+introduced=\ *version*
+ The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+ The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=\ *version*
+ The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+ This declaration is never available on this platform.
+
+message=\ *string-literal*
+ 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.
+
+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:
+
+``ios``
+ Apple's iOS operating system. The minimum deployment target is specified by
+ the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+ command-line arguments.
+
+``macosx``
+ Apple's Mac OS X operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+
+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
+`weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` 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.
+
+Checks for Standard Language Features
+=====================================
+
+The ``__has_feature`` macro can be used to query if certain standard language
+features are enabled. The ``__has_extension`` macro can be used to query if
+language features are available as an extension when compiling for a standard
+which does not provide them. The features which can be tested are listed here.
+
+C++98
+-----
+
+The features listed below are part of the C++98 standard. These features are
+enabled by default when compiling C++ code.
+
+C++ exceptions
+^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
+enabled. For example, compiling code with ``-fno-exceptions`` disables C++
+exceptions.
+
+C++ RTTI
+^^^^^^^^
+
+Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
+example, compiling code with ``-fno-rtti`` disables the use of RTTI.
+
+C++11
+-----
+
+The features listed below are part of the C++11 standard. As a result, all
+these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
+when compiling C++ code.
+
+C++11 SFINAE includes access control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_access_control_sfinae)`` or
+``__has_extension(cxx_access_control_sfinae)`` to determine whether
+access-control errors (e.g., calling a private constructor) are considered to
+be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
+<http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
+
+C++11 alias templates
+^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_alias_templates)`` or
+``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
+alias declarations and alias templates is enabled.
+
+C++11 alignment specifiers
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
+determine if support for alignment specifiers using ``alignas`` is enabled.
+
+C++11 attributes
+^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
+determine if support for attribute parsing with C++11's square bracket notation
+is enabled.
+
+C++11 generalized constant expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
+constant expressions (e.g., ``constexpr``) is enabled.
+
+C++11 ``decltype()``
+^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
+determine if support for the ``decltype()`` specifier is enabled. C++11's
+``decltype`` does not require type-completeness of a function call expression.
+Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
+``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
+support for this feature is enabled.
+
+C++11 default template arguments in function templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_default_function_template_args)`` or
+``__has_extension(cxx_default_function_template_args)`` to determine if support
+for default template arguments in function templates is enabled.
+
+C++11 ``default``\ ed functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_defaulted_functions)`` or
+``__has_extension(cxx_defaulted_functions)`` to determine if support for
+defaulted function definitions (with ``= default``) is enabled.
+
+C++11 delegating constructors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
+delegating constructors is enabled.
+
+C++11 ``deleted`` functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_deleted_functions)`` or
+``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
+function definitions (with ``= delete``) is enabled.
+
+C++11 explicit conversion functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
+``explicit`` conversion functions is enabled.
+
+C++11 generalized initializers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
+generalized initializers (using braced lists and ``std::initializer_list``) is
+enabled.
+
+C++11 implicit move constructors/assignment operators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
+generate move constructors and move assignment operators where needed.
+
+C++11 inheriting constructors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
+inheriting constructors is enabled. Clang does not currently implement this
+feature.
+
+C++11 inline namespaces
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_inline_namespaces)`` or
+``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
+namespaces is enabled.
+
+C++11 lambdas
+^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
+determine if support for lambdas is enabled.
+
+C++11 local and unnamed types as template arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_local_type_template_args)`` or
+``__has_extension(cxx_local_type_template_args)`` to determine if support for
+local and unnamed types as template arguments is enabled.
+
+C++11 noexcept
+^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
+determine if support for noexcept exception specifications is enabled.
+
+C++11 in-class non-static data member initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
+initialization of non-static data members is enabled.
+
+C++11 ``nullptr``
+^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
+determine if support for ``nullptr`` is enabled.
+
+C++11 ``override control``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_override_control)`` or
+``__has_extension(cxx_override_control)`` to determine if support for the
+override control keywords is enabled.
+
+C++11 reference-qualified functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_reference_qualified_functions)`` or
+``__has_extension(cxx_reference_qualified_functions)`` to determine if support
+for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
+applied to ``*this``) is enabled.
+
+C++11 range-based ``for`` loop
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
+determine if support for the range-based for loop is enabled.
+
+C++11 raw string literals
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
+string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
+
+C++11 rvalue references
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_rvalue_references)`` or
+``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
+references is enabled.
+
+C++11 ``static_assert()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_static_assert)`` or
+``__has_extension(cxx_static_assert)`` to determine if support for compile-time
+assertions using ``static_assert`` is enabled.
+
+C++11 type inference
+^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
+determine C++11 type inference is supported using the ``auto`` specifier. If
+this is disabled, ``auto`` will instead be a storage class specifier, as in C
+or C++98.
+
+C++11 strongly typed enumerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_strong_enums)`` or
+``__has_extension(cxx_strong_enums)`` to determine if support for strongly
+typed, scoped enumerations is enabled.
+
+C++11 trailing return type
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_trailing_return)`` or
+``__has_extension(cxx_trailing_return)`` to determine if support for the
+alternate function declaration syntax with trailing return type is enabled.
+
+C++11 Unicode string literals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
+string literals is enabled.
+
+C++11 unrestricted unions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
+unrestricted unions is enabled.
+
+C++11 user-defined literals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_user_literals)`` to determine if support for
+user-defined literals is enabled.
+
+C++11 variadic templates
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(cxx_variadic_templates)`` or
+``__has_extension(cxx_variadic_templates)`` to determine if support for
+variadic templates is enabled.
+
+C11
+---
+
+The features listed below are part of the C11 standard. As a result, all these
+features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
+compiling C code. Additionally, because these features are all
+backward-compatible, they are available as extensions in all language modes.
+
+C11 alignment specifiers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
+if support for alignment specifiers using ``_Alignas`` is enabled.
+
+C11 atomic operations
+^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
+if support for atomic types using ``_Atomic`` is enabled. Clang also provides
+:ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement
+the ``<stdatomic.h>`` operations on ``_Atomic`` types.
+
+C11 generic selections
+^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(c_generic_selections)`` or
+``__has_extension(c_generic_selections)`` to determine if support for generic
+selections is enabled.
+
+As an extension, the C11 generic selection expression is available in all
+languages supported by Clang. The syntax is the same as that given in the C11
+standard.
+
+In C, type compatibility is decided according to the rules given in the
+appropriate standard, but in C++, which lacks the type compatibility rules used
+in C, types are considered compatible only if they are equivalent.
+
+C11 ``_Static_assert()``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
+to determine if support for compile-time assertions using ``_Static_assert`` is
+enabled.
+
+Checks for Type Traits
+======================
+
+Clang supports the `GNU C++ type traits
+<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
+`Microsoft Visual C++ Type traits
+<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. For each
+supported type trait ``__X``, ``__has_extension(X)`` indicates the presence of
+the type trait. For example:
+
+.. code-block:: c++
+
+ #if __has_extension(is_convertible_to)
+ template<typename From, typename To>
+ struct is_convertible_to {
+ static const bool value = __is_convertible_to(From, To);
+ };
+ #else
+ // Emulate type trait
+ #endif
+
+The following type traits are supported by Clang:
+
+* ``__has_nothrow_assign`` (GNU, Microsoft)
+* ``__has_nothrow_copy`` (GNU, Microsoft)
+* ``__has_nothrow_constructor`` (GNU, Microsoft)
+* ``__has_trivial_assign`` (GNU, Microsoft)
+* ``__has_trivial_copy`` (GNU, Microsoft)
+* ``__has_trivial_constructor`` (GNU, Microsoft)
+* ``__has_trivial_destructor`` (GNU, Microsoft)
+* ``__has_virtual_destructor`` (GNU, Microsoft)
+* ``__is_abstract`` (GNU, Microsoft)
+* ``__is_base_of`` (GNU, Microsoft)
+* ``__is_class`` (GNU, Microsoft)
+* ``__is_convertible_to`` (Microsoft)
+* ``__is_empty`` (GNU, Microsoft)
+* ``__is_enum`` (GNU, Microsoft)
+* ``__is_interface_class`` (Microsoft)
+* ``__is_pod`` (GNU, Microsoft)
+* ``__is_polymorphic`` (GNU, Microsoft)
+* ``__is_union`` (GNU, Microsoft)
+* ``__is_literal(type)``: Determines whether the given type is a literal type
+* ``__is_final``: Determines whether the given type is declared with a
+ ``final`` class-virt-specifier.
+* ``__underlying_type(type)``: Retrieves the underlying type for a given
+ ``enum`` type. This trait is required to implement the C++11 standard
+ library.
+* ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value
+ of type ``totype`` can be assigned to from a value of type ``fromtype`` such
+ that no non-trivial functions are called as part of that assignment. This
+ trait is required to implement the C++11 standard library.
+* ``__is_trivially_constructible(type, argtypes...)``: Determines whether a
+ value of type ``type`` can be direct-initialized with arguments of types
+ ``argtypes...`` such that no non-trivial functions are called as part of
+ that initialization. This trait is required to implement the C++11 standard
+ library.
+
+Blocks
+======
+
+The syntax and high level language feature description is in
+`BlockLanguageSpec.txt <BlockLanguageSpec.txt>`_. Implementation and ABI
+details for the clang implementation are in `Block-ABI-Apple.txt
+<Block-ABI-Apple.txt>`_.
+
+Query for this feature with ``__has_extension(blocks)``.
+
+Objective-C Features
+====================
+
+Related result types
+--------------------
+
+According to Cocoa conventions, Objective-C methods with certain names
+("``init``", "``alloc``", etc.) always return objects that are an instance of
+the receiving class's type. Such methods are said to have a "related result
+type", meaning that a message send to one of these methods will have the same
+static type as an instance of the receiver class. For example, given the
+following classes:
+
+.. code-block:: objc
+
+ @interface NSObject
+ + (id)alloc;
+ - (id)init;
+ @end
+
+ @interface NSArray : NSObject
+ @end
+
+and this common initialization pattern
+
+.. code-block:: objc
+
+ NSArray *array = [[NSArray alloc] init];
+
+the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
+``alloc`` implicitly has a related result type. Similarly, the type of the
+expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
+related result type and its receiver is known to have the type ``NSArray *``.
+If neither ``alloc`` nor ``init`` had a related result type, the expressions
+would have had type ``id``, as declared in the method signature.
+
+A method with a related result type can be declared by using the type
+``instancetype`` as its result type. ``instancetype`` is a contextual keyword
+that is only permitted in the result type of an Objective-C method, e.g.
+
+.. code-block:: objc
+
+ @interface A
+ + (instancetype)constructAnA;
+ @end
+
+The related result type can also be inferred for some methods. To determine
+whether a method has an inferred related result type, the first word in the
+camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
+and the method will have a related result type if its return type is compatible
+with the type of its class and if:
+
+* the first word is "``alloc``" or "``new``", and the method is a class method,
+ or
+
+* the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
+ and the method is an instance method.
+
+If a method with a related result type is overridden by a subclass method, the
+subclass method must also return a type that is compatible with the subclass
+type. For example:
+
+.. code-block:: objc
+
+ @interface NSString : NSObject
+ - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
+ @end
+
+Related result types only affect the type of a message send or property access
+via the given method. In all other respects, a method with a related result
+type is treated the same way as method that returns ``id``.
+
+Use ``__has_feature(objc_instancetype)`` to determine whether the
+``instancetype`` contextual keyword is available.
+
+Automatic reference counting
+----------------------------
+
+Clang provides support for `automated reference counting
+<AutomaticReferenceCounting.html>`_ in Objective-C, which eliminates the need
+for manual ``retain``/``release``/``autorelease`` message sends. There are two
+feature macros associated with automatic reference counting:
+``__has_feature(objc_arc)`` indicates the availability of automated reference
+counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
+automated reference counting also includes support for ``__weak`` pointers to
+Objective-C objects.
+
+Enumerations with a fixed underlying type
+-----------------------------------------
+
+Clang provides support for C++11 enumerations with a fixed underlying type
+within Objective-C. For example, one can write an enumeration type as:
+
+.. code-block:: c++
+
+ typedef enum : unsigned char { Red, Green, Blue } Color;
+
+This specifies that the underlying type, which is used to store the enumeration
+value, is ``unsigned char``.
+
+Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
+underlying types is available in Objective-C.
+
+Interoperability with C++11 lambdas
+-----------------------------------
+
+Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
+permitting a lambda to be implicitly converted to a block pointer with the
+corresponding signature. For example, consider an API such as ``NSArray``'s
+array-sorting method:
+
+.. code-block:: objc
+
+ - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
+
+``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
+(^)(id, id)``, and parameters of this type are generally provided with block
+literals as arguments. However, one can also use a C++11 lambda so long as it
+provides the same signature (in this case, accepting two parameters of type
+``id`` and returning an ``NSComparisonResult``):
+
+.. code-block:: objc
+
+ NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
+ @"String 02"];
+ const NSStringCompareOptions comparisonOptions
+ = NSCaseInsensitiveSearch | NSNumericSearch |
+ NSWidthInsensitiveSearch | NSForcedOrderingSearch;
+ NSLocale *currentLocale = [NSLocale currentLocale];
+ NSArray *sorted
+ = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
+ NSRange string1Range = NSMakeRange(0, [s1 length]);
+ return [s1 compare:s2 options:comparisonOptions
+ range:string1Range locale:currentLocale];
+ }];
+ NSLog(@"sorted: %@", sorted);
+
+This code relies on an implicit conversion from the type of the lambda
+expression (an unnamed, local class type called the *closure type*) to the
+corresponding block pointer type. The conversion itself is expressed by a
+conversion operator in that closure type that produces a block pointer with the
+same signature as the lambda itself, e.g.,
+
+.. code-block:: objc
+
+ operator NSComparisonResult (^)(id, id)() const;
+
+This conversion function returns a new block that simply forwards the two
+parameters to the lambda object (which it captures by copy), then returns the
+result. The returned block is first copied (with ``Block_copy``) and then
+autoreleased. As an optimization, if a lambda expression is immediately
+converted to a block pointer (as in the first example, above), then the block
+is not copied and autoreleased: rather, it is given the same lifetime as a
+block literal written at that point in the program, which avoids the overhead
+of copying a block to the heap in the common case.
+
+The conversion from a lambda to a block pointer is only available in
+Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
+management (autorelease).
+
+Object Literals and Subscripting
+--------------------------------
+
+Clang provides support for `Object Literals and Subscripting
+<ObjectiveCLiterals.html>`_ in Objective-C, which simplifies common Objective-C
+programming patterns, makes programs more concise, and improves the safety of
+container creation. There are several feature macros associated with object
+literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
+availability of array literals; ``__has_feature(objc_dictionary_literals)``
+tests the availability of dictionary literals;
+``__has_feature(objc_subscripting)`` tests the availability of object
+subscripting.
+
+Objective-C Autosynthesis of Properties
+---------------------------------------
+
+Clang provides support for autosynthesis of declared properties. Using this
+feature, clang provides default synthesis of those properties not declared
+ at dynamic and not having user provided backing getter and setter methods.
+``__has_feature(objc_default_synthesize_properties)`` checks for availability
+of this feature in version of clang being used.
+
+Function Overloading in C
+=========================
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the ``overloadable`` attribute. For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+ #include <math.h>
+ float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+ double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+ long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` 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:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+ considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+ compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+ and ``U`` are compatible types. This conversion is given "conversion" rank.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute. This rule even applies to redeclarations of
+functions whose original declaration had the ``overloadable`` attribute, e.g.,
+
+.. code-block:: c
+
+ int f(int) __attribute__((overloadable));
+ float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+ int g(int) __attribute__((overloadable));
+ int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes. Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+ int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` 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 ``unavailable`` attribute:
+
+.. code-block:: c++
+
+ void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
+caveats to this use of name mangling:
+
+* 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 ``static inline`` with ``overloadable``
+ functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an ``overloadable`` function occurs within an ``extern "C"``
+ linkage specification, it's name *will* be mangled in the same way as it
+ would in C.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+Initializer lists for complex numbers in C
+==========================================
+
+clang supports an extension which allows the following in C:
+
+.. code-block:: c++
+
+ #include <math.h>
+ #include <complex.h>
+ complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
+
+This construct is useful because there is no way to separately initialize the
+real and imaginary parts of a complex variable in standard C, given that clang
+does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
+``__imag__`` extensions from gcc, which help in some cases, but are not usable
+in static initializers.)
+
+Note that this extension does not allow eliding the braces; the meaning of the
+following two lines is different:
+
+.. code-block:: c++
+
+ complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
+ complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
+
+This extension also works in C++ mode, as far as that goes, but does not apply
+to the C++ ``std::complex``. (In C++11, list initialization allows the same
+syntax to be used with ``std::complex`` with the same meaning.)
+
+Builtin Functions
+=================
+
+Clang supports a number of builtin library functions with the same syntax as
+GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
+``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
+``__sync_fetch_and_add``, etc. In addition to the GCC builtins, Clang supports
+a number of builtins that GCC does not, which are listed here.
+
+Please note that Clang does not and will not support all of the GCC builtins
+for vector operations. Instead of using builtins, you should use the functions
+defined in target-specific header files like ``<xmmintrin.h>``, which define
+portable wrappers for these. Many of the Clang versions of these functions are
+implemented directly in terms of :ref:`extended vector support
+<langext-vectors>` instead of builtins, in order to reduce the number of
+builtins that we need to implement.
+
+``__builtin_readcyclecounter``
+------------------------------
+
+``__builtin_readcyclecounter`` is used to access the cycle counter register (or
+a similar low-latency, high-accuracy clock) on those targets that support it.
+
+**Syntax**:
+
+.. code-block:: c++
+
+ __builtin_readcyclecounter()
+
+**Example of Use**:
+
+.. code-block:: c++
+
+ unsigned long long t0 = __builtin_readcyclecounter();
+ do_something();
+ unsigned long long t1 = __builtin_readcyclecounter();
+ unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
+
+**Description**:
+
+The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
+which may be either global or process/thread-specific depending on the target.
+As the backing counters often overflow quickly (on the order of seconds) this
+should only be used for timing small intervals. When not supported by the
+target, the return value is always zero. This builtin takes no arguments and
+produces an unsigned long long result.
+
+Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``.
+
+.. _langext-__builtin_shufflevector:
+
+``__builtin_shufflevector``
+---------------------------
+
+``__builtin_shufflevector`` is used to express generic vector
+permutation/shuffle/swizzle operations. This builtin is also very important
+for the implementation of various target-specific header files like
+``<xmmintrin.h>``.
+
+**Syntax**:
+
+.. code-block:: c++
+
+ __builtin_shufflevector(vec1, vec2, index1, index2, ...)
+
+**Examples**:
+
+.. code-block:: c++
+
+ // Identity operation - return 4-element vector V1.
+ __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
+
+ // "Splat" element 0 of V1 into a 4-element result.
+ __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
+
+ // Reverse 4-element vector V1.
+ __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
+
+ // Concatenate every other element of 4-element vectors V1 and V2.
+ __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
+
+ // Concatenate every other element of 8-element vectors V1 and V2.
+ __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
+
+**Description**:
+
+The first two arguments to ``__builtin_shufflevector`` are vectors that have
+the same element type. The remaining arguments are a list of integers that
+specify the elements indices of the first two vectors that should be extracted
+and returned in a new vector. These element indices are numbered sequentially
+starting with the first vector, continuing into the second vector. Thus, if
+``vec1`` is a 4-element vector, index 5 would refer to the second element of
+``vec2``.
+
+The result of ``__builtin_shufflevector`` is a vector with the same element
+type as ``vec1``/``vec2`` but that has an element count equal to the number of
+indices specified.
+
+Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
+
+``__builtin_unreachable``
+-------------------------
+
+``__builtin_unreachable`` is used to indicate that a specific point in the
+program cannot be reached, even if the compiler might otherwise think it can.
+This is useful to improve optimization and eliminates certain warnings. For
+example, without the ``__builtin_unreachable`` in the example below, the
+compiler assumes that the inline asm can fall through and prints a "function
+declared '``noreturn``' should not return" warning.
+
+**Syntax**:
+
+.. code-block:: c++
+
+ __builtin_unreachable()
+
+**Example of use**:
+
+.. code-block:: c++
+
+ void myabort(void) __attribute__((noreturn));
+ void myabort(void) {
+ asm("int3");
+ __builtin_unreachable();
+ }
+
+**Description**:
+
+The ``__builtin_unreachable()`` builtin has completely undefined behavior.
+Since it has undefined behavior, it is a statement that it is never reached and
+the optimizer can take advantage of this to produce better code. This builtin
+takes no arguments and produces a void result.
+
+Query for this feature with ``__has_builtin(__builtin_unreachable)``.
+
+``__sync_swap``
+---------------
+
+``__sync_swap`` is used to atomically swap integers or pointers in memory.
+
+**Syntax**:
+
+.. code-block:: c++
+
+ type __sync_swap(type *ptr, type value, ...)
+
+**Example of Use**:
+
+.. code-block:: c++
+
+ int old_value = __sync_swap(&value, new_value);
+
+**Description**:
+
+The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
+atomic intrinsics to allow code to atomically swap the current value with the
+new value. More importantly, it helps developers write more efficient and
+correct code by avoiding expensive loops around
+``__sync_bool_compare_and_swap()`` or relying on the platform specific
+implementation details of ``__sync_lock_test_and_set()``. The
+``__sync_swap()`` builtin is a full barrier.
+
+.. _langext-__c11_atomic:
+
+__c11_atomic builtins
+---------------------
+
+Clang provides a set of builtins which are intended to be used to implement
+C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
+``_explicit`` form of the corresponding C11 operation, and are named with a
+``__c11_`` prefix. The supported operations are:
+
+* ``__c11_atomic_init``
+* ``__c11_atomic_thread_fence``
+* ``__c11_atomic_signal_fence``
+* ``__c11_atomic_is_lock_free``
+* ``__c11_atomic_store``
+* ``__c11_atomic_load``
+* ``__c11_atomic_exchange``
+* ``__c11_atomic_compare_exchange_strong``
+* ``__c11_atomic_compare_exchange_weak``
+* ``__c11_atomic_fetch_add``
+* ``__c11_atomic_fetch_sub``
+* ``__c11_atomic_fetch_and``
+* ``__c11_atomic_fetch_or``
+* ``__c11_atomic_fetch_xor``
+
+Non-standard C++11 Attributes
+=============================
+
+Clang supports one non-standard C++11 attribute. It resides in the ``clang``
+attribute namespace.
+
+The ``clang::fallthrough`` attribute
+------------------------------------
+
+The ``clang::fallthrough`` attribute is used along with the
+``-Wimplicit-fallthrough`` 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 ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+Here is an example:
+
+.. code-block:: c++
+
+ // compile with -Wimplicit-fallthrough
+ switch (n) {
+ case 22:
+ case 33: // no warning: no statements between case labels
+ f();
+ case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+ case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+ case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+ case 77: // warning: unannotated fall-through
+ r();
+ }
+
+Target-Specific Extensions
+==========================
+
+Clang supports some language features conditionally on some targets.
+
+X86/X86-64 Language Extensions
+------------------------------
+
+The X86 backend has these language extensions:
+
+Memory references off the GS segment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Annotating a pointer with address space #256 causes it to be code generated
+relative to the X86 GS segment register, and address space #257 causes it to be
+relative to the X86 FS segment. Note that this is a very very low-level
+feature that should only be used if you know what you're doing (for example in
+an OS kernel).
+
+Here is an example:
+
+.. code-block:: c++
+
+ #define GS_RELATIVE __attribute__((address_space(256)))
+ int foo(int GS_RELATIVE *P) {
+ return *P;
+ }
+
+Which compiles to (on X86-32):
+
+.. code-block:: gas
+
+ _foo:
+ movl 4(%esp), %eax
+ movl %gs:(%eax), %eax
+ ret
+
+Static Analysis-Specific Extensions
+===================================
+
+Clang supports additional attributes that are useful for documenting program
+invariants and rules for static analysis tools. The extensions documented here
+are used by the `path-sensitive static analyzer engine
+<http://clang.llvm.org/StaticAnalysis.html>`_ that is part of Clang's Analysis
+library.
+
+The ``analyzer_noreturn`` attribute
+-----------------------------------
+
+Clang's static analysis engine understands the standard ``noreturn`` attribute.
+This attribute, which is typically affixed to a function prototype, indicates
+that a call to a given function never returns. Function prototypes for common
+functions like ``exit`` are typically annotated with this attribute, as well as
+a variety of common assertion handlers. Users can educate the static analyzer
+about their own custom assertion handles (thus cutting down on false positives
+due to false paths) by marking their own "panic" functions with this attribute.
+
+While useful, ``noreturn`` is not applicable in all cases. Sometimes there are
+special functions that for all intents and purposes should be considered panic
+functions (i.e., they are only called when an internal program error occurs)
+but may actually return so that the program can fail gracefully. The
+``analyzer_noreturn`` attribute allows one to annotate such functions as being
+interpreted as "no return" functions by the analyzer (thus pruning bogus paths)
+but will not affect compilation (as in the case of ``noreturn``).
+
+**Usage**: The ``analyzer_noreturn`` attribute can be placed in the same places
+where the ``noreturn`` attribute can be placed. It is commonly placed at the
+end of function prototypes:
+
+.. code-block:: c++
+
+ void foo() __attribute__((analyzer_noreturn));
+
+Query for this feature with ``__has_attribute(analyzer_noreturn)``.
+
+.. _langext-objc_method_family:
+
+The ``objc_method_family`` attribute
+------------------------------------
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. For the purposes of static analysis, 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.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (NSString*) initMyStringValue __attribute__((objc_method_family(none)));
+
+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 :ref:`retaining behavior attributes <langext-objc-retain-release>`
+described below.
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+.. _langext-objc-retain-release:
+
+Objective-C retaining behavior attributes
+-----------------------------------------
+
+In Objective-C, functions and methods are generally assumed to take and return
+objects with +0 retain counts, with some exceptions for special methods like
+``+alloc`` and ``init``. However, there are exceptions, and so Clang provides
+attributes to allow these exceptions to be documented, which helps the analyzer
+find leaks (and ignore non-leaks). Some exceptions may be better described
+using the :ref:`objc_method_family <langext-objc_method_family>` attribute
+instead.
+
+**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
+ ``ns_returns_autoreleased``, ``cf_returns_retained``, and
+ ``cf_returns_not_retained`` attributes can be placed on methods and functions
+ that return Objective-C or CoreFoundation objects. They are commonly placed
+ at the end of a function prototype or method declaration:
+
+.. code-block:: objc
+
+ id foo() __attribute__((ns_returns_retained));
+
+ - (NSString*) bar: (int) x __attribute__((ns_returns_retained));
+
+The ``*_returns_retained`` attributes specify that the returned object has a +1
+retain count. The ``*_returns_not_retained`` attributes specify that the return
+object has a +0 retain count, even if the normal convention for its selector
+would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
++0, but is guaranteed to live at least as long as the next flush of an
+autorelease pool.
+
+**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
+an parameter declaration; they specify that the argument is expected to have a
++1 retain count, which will be balanced in some way by the function or method.
+The ``ns_consumes_self`` attribute can only be placed on an Objective-C
+method; it specifies that the method expects its ``self`` parameter to have a
++1 retain count, which it will balance in some way.
+
+.. code-block:: objc
+
+ void foo(__attribute__((ns_consumed)) NSString *string);
+
+ - (void) bar __attribute__((ns_consumes_self));
+ - (void) baz: (id) __attribute__((ns_consumed)) x;
+
+Query for these features with ``__has_attribute(ns_consumed)``,
+``__has_attribute(ns_returns_retained)``, etc.
+
+Dynamic Analysis-Specific Extensions
+====================================
+
+.. _langext-address_sanitizer:
+
+AddressSanitizer
+----------------
+
+Use ``__has_feature(address_sanitizer)`` to check if the code is being built
+with `AddressSanitizer <AddressSanitizer.html>`_.
+
+Use ``__attribute__((no_address_safety_analysis))`` on a function declaration
+to specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+Thread-Safety Annotation Checking
+=================================
+
+Clang supports additional attributes for checking basic locking policies in
+multithreaded programs. Clang currently parses the following list of
+attributes, although **the implementation for these annotations is currently in
+development.** For more details, see the `GCC implementation
+<http://gcc.gnu.org/wiki/ThreadSafetyAnnotation>`_.
+
+``no_thread_safety_analysis``
+-----------------------------
+
+Use ``__attribute__((no_thread_safety_analysis))`` on a function declaration to
+specify that the thread safety analysis should not be run on that function.
+This attribute provides an escape hatch (e.g. for situations when it is
+difficult to annotate the locking policy).
+
+``lockable``
+------------
+
+Use ``__attribute__((lockable))`` on a class definition to specify that it has
+a lockable type (e.g. a Mutex class). This annotation is primarily used to
+check consistency.
+
+``scoped_lockable``
+-------------------
+
+Use ``__attribute__((scoped_lockable))`` on a class definition to specify that
+it has a "scoped" lockable type. Objects of this type will acquire the lock
+upon construction and release it upon going out of scope. This annotation is
+primarily used to check consistency.
+
+``guarded_var``
+---------------
+
+Use ``__attribute__((guarded_var))`` on a variable declaration to specify that
+the variable must be accessed while holding some lock.
+
+``pt_guarded_var``
+------------------
+
+Use ``__attribute__((pt_guarded_var))`` on a pointer declaration to specify
+that the pointer must be dereferenced while holding some lock.
+
+``guarded_by(l)``
+-----------------
+
+Use ``__attribute__((guarded_by(l)))`` on a variable declaration to specify
+that the variable must be accessed while holding lock ``l``.
+
+``pt_guarded_by(l)``
+--------------------
+
+Use ``__attribute__((pt_guarded_by(l)))`` on a pointer declaration to specify
+that the pointer must be dereferenced while holding lock ``l``.
+
+``acquired_before(...)``
+------------------------
+
+Use ``__attribute__((acquired_before(...)))`` on a declaration of a lockable
+variable to specify that the lock must be acquired before all attribute
+arguments. Arguments must be lockable type, and there must be at least one
+argument.
+
+``acquired_after(...)``
+-----------------------
+
+Use ``__attribute__((acquired_after(...)))`` on a declaration of a lockable
+variable to specify that the lock must be acquired after all attribute
+arguments. Arguments must be lockable type, and there must be at least one
+argument.
+
+``exclusive_lock_function(...)``
+--------------------------------
+
+Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
+to specify that the function acquires all listed locks exclusively. This
+attribute takes zero or more arguments: either of lockable type or integers
+indexing into function parameters of lockable type. If no arguments are given,
+the acquired lock is implicitly ``this`` of the enclosing object.
+
+``shared_lock_function(...)``
+-----------------------------
+
+Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
+specify that the function acquires all listed locks, although the locks may be
+shared (e.g. read locks). This attribute takes zero or more arguments: either
+of lockable type or integers indexing into function parameters of lockable
+type. If no arguments are given, the acquired lock is implicitly ``this`` of
+the enclosing object.
+
+``exclusive_trylock_function(...)``
+-----------------------------------
+
+Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
+to specify that the function will try (without blocking) to acquire all listed
+locks exclusively. This attribute takes one or more arguments. The first
+argument is an integer or boolean value specifying the return value of a
+successful lock acquisition. The remaining arugments are either of lockable
+type or integers indexing into function parameters of lockable type. If only
+one argument is given, the acquired lock is implicitly ``this`` of the
+enclosing object.
+
+``shared_trylock_function(...)``
+--------------------------------
+
+Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
+specify that the function will try (without blocking) to acquire all listed
+locks, although the locks may be shared (e.g. read locks). This attribute
+takes one or more arguments. The first argument is an integer or boolean value
+specifying the return value of a successful lock acquisition. The remaining
+arugments are either of lockable type or integers indexing into function
+parameters of lockable type. If only one argument is given, the acquired lock
+is implicitly ``this`` of the enclosing object.
+
+``unlock_function(...)``
+------------------------
+
+Use ``__attribute__((unlock_function(...)))`` on a function declaration to
+specify that the function release all listed locks. This attribute takes zero
+or more arguments: either of lockable type or integers indexing into function
+parameters of lockable type. If no arguments are given, the acquired lock is
+implicitly ``this`` of the enclosing object.
+
+``lock_returned(l)``
+--------------------
+
+Use ``__attribute__((lock_returned(l)))`` on a function declaration to specify
+that the function returns lock ``l`` (``l`` must be of lockable type). This
+annotation is used to aid in resolving lock expressions.
+
+``locks_excluded(...)``
+-----------------------
+
+Use ``__attribute__((locks_excluded(...)))`` on a function declaration to
+specify that the function must not be called with the listed locks. Arguments
+must be lockable type, and there must be at least one argument.
+
+``exclusive_locks_required(...)``
+---------------------------------
+
+Use ``__attribute__((exclusive_locks_required(...)))`` on a function
+declaration to specify that the function must be called while holding the
+listed exclusive locks. Arguments must be lockable type, and there must be at
+least one argument.
+
+``shared_locks_required(...)``
+------------------------------
+
+Use ``__attribute__((shared_locks_required(...)))`` on a function declaration
+to specify that the function must be called while holding the listed shared
+locks. Arguments must be lockable type, and there must be at least one
+argument.
+
+Type Safety Checking
+====================
+
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by C type system. Usecases include:
+
+* MPI library implementations, where these attributes enable checking that
+ buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar usecase as MPI;
+* checking types of variadic functions' arguments for functions like
+ ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``. For
+example:
+
+.. code-block:: c++
+
+ #if defined(__has_attribute)
+ # if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+ /* ... other macros ... */
+ # endif
+ #endif
+
+ #if !defined(ATTR_MPI_PWT)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx)
+ #endif
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+
+``argument_with_type_tag(...)``
+-------------------------------
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+``arg_kind`` is an identifier that should be used when annotating all
+applicable type tags.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most of non-variadic cases).
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+
+``pointer_with_type_tag(...)``
+------------------------------
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+For example:
+
+.. code-block:: c++
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+``type_tag_for_datatype(...)``
+------------------------------
+
+Clang supports annotating type tags of two forms.
+
+* **Type tag that is an expression containing a reference to some declared
+ identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
+ declaration with that identifier:
+
+ .. code-block:: c++
+
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+
+* **Type tag that is an integral literal.** Introduce a ``static const``
+ variable with a corresponding initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
+ for example:
+
+ .. code-block:: c++
+
+ #define MPI_INT ((MPI_Datatype) 42)
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
+
+The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag. There are two supported flags:
+
+* ``layout_compatible`` 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 ``MPI_DOUBLE_INT``.
+
+ For example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
+ // type 'struct my_int_pair'
+ // doesn't match specified MPI_Datatype
+
+* ``must_be_null`` specifies that the expression should be a null pointer
+ constant, for example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+
+ /* In user code */
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+
Removed: cfe/trunk/docs/LibASTMatchers.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibASTMatchers.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/LibASTMatchers.html (original)
+++ cfe/trunk/docs/LibASTMatchers.html (removed)
@@ -1,130 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-<title>Matching the Clang AST</title>
-<link type="text/css" rel="stylesheet" href="../menu.css" />
-<link type="text/css" rel="stylesheet" href="../content.css" />
-</head>
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>Matching the Clang AST</h1>
-<p>This document explains how to use Clang's LibASTMatchers to match interesting
-nodes of the AST and execute code that uses the matched nodes. Combined with
-<a href="LibTooling.html">LibTooling</a>, LibASTMatchers helps to write
-code-to-code transformation tools or query tools.</p>
-
-<p>We assume basic knowledge about the Clang AST. See the
-<a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a> if
-you want to learn more about how the AST is structured.</p>
-
-<!-- FIXME: create tutorial and link to the tutorial -->
-
-<!-- ======================================================================= -->
-<h2 id="intro">Introduction</h2>
-<!-- ======================================================================= -->
-
-<p>LibASTMatchers provides a domain specific language to create predicates on Clang's
-AST. This DSL is written in and can be used from C++, allowing users to write
-a single program to both match AST nodes and access the node's C++ interface
-to extract attributes, source locations, or any other information provided on
-the AST level.</p>
-
-<p>AST matchers are predicates on nodes in the AST. Matchers are created
-by calling creator functions that allow building up a tree of matchers, where
-inner matchers are used to make the match more specific.</p>
-
-</p>For example, to create a matcher that matches all class or union declarations
-in the AST of a translation unit, you can call
-<a href="LibASTMatchersReference.html#recordDecl0Anchor">recordDecl()</a>.
-To narrow the match down, for example to find all class or union declarations with the name "Foo",
-insert a <a href="LibASTMatchersReference.html#hasName0Anchor">hasName</a>
-matcher: the call recordDecl(hasName("Foo")) returns a matcher that matches classes
-or unions that are named "Foo", in any namespace. By default, matchers that accept
-multiple inner matchers use an implicit <a href="LibASTMatchersReference.html#allOf0Anchor">allOf()</a>.
-This allows further narrowing down the match, for example to match all classes
-that are derived from "Bar": recordDecl(hasName("Foo"), isDerivedFrom("Bar")).</p>
-
-<!-- ======================================================================= -->
-<h2 id="writing">How to create a matcher</h2>
-<!-- ======================================================================= -->
-
-<p>With more than a thousand classes in the Clang AST, one can quickly get lost
-when trying to figure out how to create a matcher for a specific pattern. This
-section will teach you how to use a rigorous step-by-step pattern to build the
-matcher you are interested in. Note that there will always be matchers missing
-for some part of the AST. See the section about <a href="#writing">how to write
-your own AST matchers</a> later in this document.</p>
-
-<p>The precondition to using the matchers is to understand how the AST
-for what you want to match looks like. The <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>
-teaches you how to dump a translation unit's AST into a human readable format.</p>
-
-<!-- FIXME: Introduce link to ASTMatchersTutorial.html -->
-<!-- FIXME: Introduce link to ASTMatchersCookbook.html -->
-
-<p>In general, the strategy to create the right matchers is:</p>
-<ol>
-<li>Find the outermost class in Clang's AST you want to match.</li>
-<li>Look at the <a href="LibASTMatchersReference.html">AST Matcher Reference</a> for matchers that either match the
-node you're interested in or narrow down attributes on the node.</li>
-<li>Create your outer match expression. Verify that it works as expected.</li>
-<li>Examine the matchers for what the next inner node you want to match is.</li>
-<li>Repeat until the matcher is finished.</li>
-</ol>
-
-<!-- ======================================================================= -->
-<h2 id="binding">Binding nodes in match expressions</h2>
-<!-- ======================================================================= -->
-
-<p>Matcher expressions allow you to specify which parts of the AST are interesting
-for a certain task. Often you will want to then do something with the nodes
-that were matched, like building source code transformations.</p>
-
-<p>To that end, matchers that match specific AST nodes (so called node matchers)
-are bindable; for example, recordDecl(hasName("MyClass")).bind("id") will bind
-the matched recordDecl node to the string "id", to be later retrieved in the
-<a href="http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html">match callback</a>.</p>
-
-<!-- FIXME: Introduce link to ASTMatchersTutorial.html -->
-<!-- FIXME: Introduce link to ASTMatchersCookbook.html -->
-
-<!-- ======================================================================= -->
-<h2 id="writing">Writing your own matchers</h2>
-<!-- ======================================================================= -->
-
-<p>There are multiple different ways to define a matcher, depending on its
-type and flexibility.</p>
-<ul>
-<li><b>VariadicDynCastAllOfMatcher<Base, Derived></b><p>Those match all nodes
-of type <i>Base</i> if they can be dynamically casted to <i>Derived</i>. The
-names of those matchers are nouns, which closely resemble <i>Derived</i>.
-VariadicDynCastAllOfMatchers are the backbone of the matcher hierarchy. Most
-often, your match expression will start with one of them, and you can
-<a href="#binding">bind</a> the node they represent to ids for later processing.</p>
-<p>VariadicDynCastAllOfMatchers are callable classes that model variadic
-template functions in C++03. They take an aribtrary number of Matcher<Derived>
-and return a Matcher<Base>.</p></li>
-<li><b>AST_MATCHER_P(Type, Name, ParamType, Param)</b><p> Most matcher definitions
-use the matcher creation macros. Those define both the matcher of type Matcher<Type>
-itself, and a matcher-creation function named <i>Name</i> that takes a parameter
-of type <i>ParamType</i> and returns the corresponding matcher.</p>
-<p>There are multiple matcher definition macros that deal with polymorphic return
-values and different parameter counts. See <a href="http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html">ASTMatchersMacros.h</a>.
-</p></li>
-<li><b>Matcher creation functions</b><p>Matchers are generated by nesting
-calls to matcher creation functions. Most of the time those functions are either
-created by using VariadicDynCastAllOfMatcher or the matcher creation macros
-(see below). The free-standing functions are an indication that this matcher
-is just a combination of other matchers, as is for example the case with
-<a href="LibASTMatchersReference.html#callee1Anchor">callee</a>.</p></li>
-</ul>
-
-</div>
-</body>
-</html>
-
Added: cfe/trunk/docs/LibASTMatchers.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibASTMatchers.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/LibASTMatchers.rst (added)
+++ cfe/trunk/docs/LibASTMatchers.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,134 @@
+======================
+Matching the Clang AST
+======================
+
+This document explains how to use Clang's LibASTMatchers to match interesting
+nodes of the AST and execute code that uses the matched nodes. Combined with
+:doc:`LibTooling`, LibASTMatchers helps to write code-to-code transformation
+tools or query tools.
+
+We assume basic knowledge about the Clang AST. See the `Introduction to the
+Clang AST <IntroductionToTheClangAST.html>`_ if you want to learn more about
+how the AST is structured.
+
+.. FIXME: create tutorial and link to the tutorial
+
+Introduction
+------------
+
+LibASTMatchers provides a domain specific language to create predicates on
+Clang's AST. This DSL is written in and can be used from C++, allowing users
+to write a single program to both match AST nodes and access the node's C++
+interface to extract attributes, source locations, or any other information
+provided on the AST level.
+
+AST matchers are predicates on nodes in the AST. Matchers are created by
+calling creator functions that allow building up a tree of matchers, where
+inner matchers are used to make the match more specific.
+
+For example, to create a matcher that matches all class or union declarations
+in the AST of a translation unit, you can call `recordDecl()
+<LibASTMatchersReference.html#recordDecl0Anchor>`_. To narrow the match down,
+for example to find all class or union declarations with the name "``Foo``",
+insert a `hasName <LibASTMatchersReference.html#hasName0Anchor>`_ matcher: the
+call ``recordDecl(hasName("Foo"))`` returns a matcher that matches classes or
+unions that are named "``Foo``", in any namespace. By default, matchers that
+accept multiple inner matchers use an implicit `allOf()
+<LibASTMatchersReference.html#allOf0Anchor>`_. This allows further narrowing
+down the match, for example to match all classes that are derived from
+"``Bar``": ``recordDecl(hasName("Foo"), isDerivedFrom("Bar"))``.
+
+How to create a matcher
+-----------------------
+
+With more than a thousand classes in the Clang AST, one can quickly get lost
+when trying to figure out how to create a matcher for a specific pattern. This
+section will teach you how to use a rigorous step-by-step pattern to build the
+matcher you are interested in. Note that there will always be matchers missing
+for some part of the AST. See the section about :ref:`how to write your own
+AST matchers <astmatchers-writing>` later in this document.
+
+.. FIXME: why is it linking back to the same section?!
+
+The precondition to using the matchers is to understand how the AST for what you
+want to match looks like. The
+`Introduction to the Clang AST <IntroductionToTheClangAST.html>`_ teaches you
+how to dump a translation unit's AST into a human readable format.
+
+.. FIXME: Introduce link to ASTMatchersTutorial.html
+.. FIXME: Introduce link to ASTMatchersCookbook.html
+
+In general, the strategy to create the right matchers is:
+
+#. Find the outermost class in Clang's AST you want to match.
+#. Look at the `AST Matcher Reference <LibASTMatchersReference.html>`_ for
+ matchers that either match the node you're interested in or narrow down
+ attributes on the node.
+#. Create your outer match expression. Verify that it works as expected.
+#. Examine the matchers for what the next inner node you want to match is.
+#. Repeat until the matcher is finished.
+
+.. _astmatchers-bind:
+
+Binding nodes in match expressions
+----------------------------------
+
+Matcher expressions allow you to specify which parts of the AST are interesting
+for a certain task. Often you will want to then do something with the nodes
+that were matched, like building source code transformations.
+
+To that end, matchers that match specific AST nodes (so called node matchers)
+are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will
+bind the matched ``recordDecl`` node to the string "``id``", to be later
+retrieved in the `match callback
+<http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html>`_.
+
+.. FIXME: Introduce link to ASTMatchersTutorial.html
+.. FIXME: Introduce link to ASTMatchersCookbook.html
+
+Writing your own matchers
+-------------------------
+
+There are multiple different ways to define a matcher, depending on its type
+and flexibility.
+
+``VariadicDynCastAllOfMatcher<Base, Derived>``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Those match all nodes of type *Base* if they can be dynamically casted to
+*Derived*. The names of those matchers are nouns, which closely resemble
+*Derived*. ``VariadicDynCastAllOfMatchers`` are the backbone of the matcher
+hierarchy. Most often, your match expression will start with one of them, and
+you can :ref:`bind <astmatchers-bind>` the node they represent to ids for later
+processing.
+
+``VariadicDynCastAllOfMatchers`` are callable classes that model variadic
+template functions in C++03. They take an aribtrary number of
+``Matcher<Derived>`` and return a ``Matcher<Base>``.
+
+``AST_MATCHER_P(Type, Name, ParamType, Param)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most matcher definitions use the matcher creation macros. Those define both
+the matcher of type ``Matcher<Type>`` itself, and a matcher-creation function
+named *Name* that takes a parameter of type *ParamType* and returns the
+corresponding matcher.
+
+There are multiple matcher definition macros that deal with polymorphic return
+values and different parameter counts. See `ASTMatchersMacros.h
+<http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html>`_.
+
+.. _astmatchers-writing:
+
+Matcher creation functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Matchers are generated by nesting calls to matcher creation functions. Most of
+the time those functions are either created by using
+``VariadicDynCastAllOfMatcher`` or the matcher creation macros (see below).
+The free-standing functions are an indication that this matcher is just a
+combination of other matchers, as is for example the case with `callee
+<LibASTMatchersReference.html#callee1Anchor>`_.
+
+.. FIXME: "... macros (see below)" --- there isn't anything below
+
Removed: cfe/trunk/docs/LibTooling.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibTooling.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/LibTooling.html (original)
+++ cfe/trunk/docs/LibTooling.html (removed)
@@ -1,212 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-<title>LibTooling</title>
-<link type="text/css" rel="stylesheet" href="../menu.css">
-<link type="text/css" rel="stylesheet" href="../content.css">
-</head>
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>LibTooling</h1>
-<p>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.</p>
-<p>For the information on how to setup Clang Tooling for LLVM see
-<a href="HowToSetupToolingForLLVM.html">HowToSetupToolingForLLVM.html</a></p>
-
-<!-- ======================================================================= -->
-<h2 id="intro">Introduction</h2>
-<!-- ======================================================================= -->
-
-<p>Tools built with LibTooling, like Clang Plugins, run
-<code>FrontendActions</code> 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
-<code>SyntaxOnlyAction</code>, which runs a quick syntax check, over a bunch of
-code.</p>
-
-<!-- ======================================================================= -->
-<h2 id="runoncode">Parsing a code snippet in memory.</h2>
-<!-- ======================================================================= -->
-
-<p>If you ever wanted to run a <code>FrontendAction</code> over some sample
-code, for example to unit test parts of the Clang AST,
-<code>runToolOnCode</code> is what you looked for. Let me give you an example:
-<pre>
- #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 {};"));
- }
-</pre>
-
-<!-- ======================================================================= -->
-<h2 id="standalonetool">Writing a standalone tool.</h2>
-<!-- ======================================================================= -->
-
-<p>Once you unit tested your <code>FrontendAction</code> 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
-<code>CompilationDatabase</code>. 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 <code>CommonOptionsParser</code> class
-that takes the responsibility to parse command-line parameters related to
-compilation databases and inputs, so that all tools share the implementation.
-</p>
-
-<h3 id="parsingcommonoptions">Parsing common tools options.</h3>
-<p><code>CompilationDatabase</code> can be read from a build directory or the
-command line. Using <code>CommonOptionsParser</code> allows for explicit
-specification of a compile command line, specification of build path using the
-<code>-p</code> command-line option, and automatic location of the compilation
-database using source files paths.
-<pre>
-#include "clang/Tooling/CommonOptionsParser.h"
-
-using namespace clang::tooling;
-
-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);
-
- // Use OptionsParser.GetCompilations() and OptionsParser.GetSourcePathList()
- // to retrieve CompilationDatabase and the list of input file paths.
-}
-</pre>
-</p>
-
-<h3 id="tool">Creating and running a ClangTool.</h3>
-<p>Once we have a <code>CompilationDatabase</code>, we can create a
-<code>ClangTool</code> and run our <code>FrontendAction</code> over some code.
-For example, to run the <code>SyntaxOnlyAction</code> over the files "a.cc" and
-"b.cc" one would write:
-<pre>
- // 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>());
-</pre>
-</p>
-
-<h3 id="main">Putting it together - the first tool.</h3>
-<p>Now we combine the two previous steps into our first real tool. This example
-tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
-<pre>
-// 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;
-
-// 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);
- ClangTool Tool(OptionsParser.GetCompilations(),
- OptionsParser.GetSourcePathList());
- return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
-}
-</pre>
-</p>
-
-<h3 id="running">Running the tool on some code.</h3>
-<p>When you check out and build clang, clang-check is already built and
-available to you in bin/clang-check inside your build directory.</p>
-<p>You can run clang-check on a file in the llvm repository by specifying
-all the needed parameters after a "--" separator:
-<pre>
- $ 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
-</pre>
-</p>
-
-<p>As an alternative, you can also configure cmake to output a compile command
-database into its build directory:
-<pre>
- # 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 .
-</pre>
-</p>
-<p>
-This creates a file called compile_commands.json in the build directory. Now
-you can run clang-check over files in the project by specifying the build path
-as first argument and some source files as further positional arguments:
-<pre>
- $ cd /path/to/source/llvm
- $ export BD=/path/to/build/llvm
- $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
-</pre>
-</p>
-
-<h3 id="builtin">Builtin includes.</h3>
-<p>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.2/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.</p>
-
-<p>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.</p>
-
-<h3 id="linking">Linking.</h3>
-<p>Please note that this presents the linking requirements at the time of this
-writing. For the most up-to-date information, look at one of the tools'
-Makefiles (for example
-<a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).
-</p>
-
-<p>To link a binary using the tooling infrastructure, link in the following
-libraries:
-<ul>
-<li>Tooling</li>
-<li>Frontend</li>
-<li>Driver</li>
-<li>Serialization</li>
-<li>Parse</li>
-<li>Sema</li>
-<li>Analysis</li>
-<li>Edit</li>
-<li>AST</li>
-<li>Lex</li>
-<li>Basic</li>
-</ul>
-</p>
-
-</div>
-</body>
-</html>
-
Added: cfe/trunk/docs/LibTooling.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibTooling.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/LibTooling.rst (added)
+++ cfe/trunk/docs/LibTooling.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,206 @@
+==========
+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
+`HowToSetupToolingForLLVM.html <HowToSetupToolingForLLVM.html>`_
+
+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"
+
+ using namespace clang::tooling;
+
+ 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);
+
+ // 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>());
+
+Putting it together --- the first tool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now we combine the two previous steps into our first real tool. 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;
+
+ // 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);
+ ClangTool Tool(OptionsParser.GetCompilations(),
+ OptionsParser.GetSourcePathList());
+ return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+ }
+
+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
+
+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.2/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
+^^^^^^^
+
+Please note that this presents the linking requirements at the time of this
+writing. For the most up-to-date information, 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>`_).
+
+To link a binary using the tooling infrastructure, link in the following
+libraries:
+
+* Tooling
+* Frontend
+* Driver
+* Serialization
+* Parse
+* Sema
+* Analysis
+* Edit
+* AST
+* Lex
+* Basic
+
Removed: cfe/trunk/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/PCHInternals.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/PCHInternals.html (original)
+++ cfe/trunk/docs/PCHInternals.html (removed)
@@ -1,658 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
- <title>Precompiled Header and Modules Internals</title>
- <link type="text/css" rel="stylesheet" href="../menu.css">
- <link type="text/css" rel="stylesheet" href="../content.css">
- <style type="text/css">
- td {
- vertical-align: top;
- }
- </style>
-</head>
-
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>Precompiled Header and Modules Internals</h1>
-
- <p>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 <a
- href="UsersManual.html#precompiledheaders">User's Manual</a>.</p>
-
- <p><b>Table of Contents</b></p>
- <ul>
- <li><a href="#usage">Using Precompiled Headers with
- <tt>clang</tt></a></li>
- <li><a href="#philosophy">Design Philosophy</a></li>
- <li><a href="#contents">Serialized AST File Contents</a>
- <ul>
- <li><a href="#metadata">Metadata Block</a></li>
- <li><a href="#sourcemgr">Source Manager Block</a></li>
- <li><a href="#preprocessor">Preprocessor Block</a></li>
- <li><a href="#types">Types Block</a></li>
- <li><a href="#decls">Declarations Block</a></li>
- <li><a href="#stmt">Statements and Expressions</a></li>
- <li><a href="#idtable">Identifier Table Block</a></li>
- <li><a href="#method-pool">Method Pool Block</a></li>
- </ul>
- </li>
- <li><a href="#tendrils">AST Reader Integration Points</a></li>
- <li><a href="#chained">Chained precompiled headers</a></li>
- <li><a href="#modules">Modules</a></li>
-</ul>
-
-<h2 id="usage">Using Precompiled Headers with <tt>clang</tt></h2>
-
-<p>The Clang compiler frontend, <tt>clang -cc1</tt>, supports two command line
-options for generating and using PCH files.<p>
-
-<p>To generate PCH files using <tt>clang -cc1</tt>, use the option
-<b><tt>-emit-pch</tt></b>:
-
-<pre> $ clang -cc1 test.h -emit-pch -o test.h.pch </pre>
-
-<p>This option is transparently used by <tt>clang</tt> 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 <b><tt>-include-pch</tt></b> option:</p>
-
-<pre>
- $ clang -cc1 -include-pch test.h.pch test.c -o test.s
-</pre>
-
-<h2 id="philosophy">Design Philosophy</h2>
-
-<p>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
- <i>precompile</i> 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.</p>
-
-<p>A precompiled header implementation improves performance when:</p>
-<ul>
- <li>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.</li>
-
- <li>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.</li>
-</ul>
-
-<p>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 <a href="#modules">modules</a>.</p>
-
-<p>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 <a href="http://llvm.org/docs/BitCodeFormat.html">LLVM's bitcode
-file format</a>.</p>
-
-<p>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.</p>
-
-<p>When given the <code>-print-stats</code> 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 <code>Cocoa.h</code> header (which is built as a precompiled
-header), this option illustrates how little of the actual precompiled
-header is required:</p>
-
-<pre>
-*** PCH Statistics:
- 933 stat cache hits
- 4 stat cache misses
- 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
-</pre>
-
-<p>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.</p>
-
-<p>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 <a href="#chained">later section</a>.
-
-<h2 id="contents">AST File Contents</h2>
-
-<img src="PCHLayout.png" style="float:right" alt="Precompiled header layout">
-
-<p>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 <a
- href="http://llvm.org/docs/BitCodeFormat.html">LLVM's bitstream
-format</a>. The contents of each of these logical blocks are described
-below.</p>
-
-<p>For a given AST file, the <a
-href="http://llvm.org/cmds/llvm-bcanalyzer.html"><code>llvm-bcanalyzer</code></a>
-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.</p>
-
-<h3 id="metadata">Metadata Block</h3>
-
-<p>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:</p>
-
-<dl>
- <dt>Language options</dt>
- <dd>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 <code>LangOptions</code> class.</dd>
-
- <dt>Target architecture</dt>
- <dd>The target triple that describes the architecture, platform, and
-ABI for which the AST file was generated, e.g.,
-<code>i386-apple-darwin9</code>.</dd>
-
- <dt>AST version</dt>
- <dd>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).</dd>
-
- <dt>Original file name</dt>
- <dd>The full path of the header that was used to generate the
-AST file.</dd>
-
- <dt>Predefines buffer</dt>
- <dd>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 "<code>#define __STDC__ 1</code>" when we are compiling C
-without Microsoft extensions. The predefines buffer itself is stored
-within the <a href="#sourcemgr">source manager block</a>, but its
-contents are verified along with the rest of the metadata.</dd>
-
-</dl>
-
-<p>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.</p>
-
-<p>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.</p>
-
-<h3 id="sourcemgr">Source Manager Block</h3>
-
-<p>The source manager block contains the serialized representation of
-Clang's <a
- href="InternalsManual.html#SourceLocation">SourceManager</a> 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.</p>
-
-<p>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.</p>
-
-<p>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 <code>LLVM_CLANG_SOURCEMANAGER_H</code>)
-along with a cached version of the results of the <code>stat()</code>
-system calls performed when building the AST file. The
-latter is particularly useful in reducing system time when searching
-for include files.</p>
-
-<h3 id="preprocessor">Preprocessor Block</h3>
-
-<p>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 <a
- href="#idtable">identifier table</a>.</p>
-
-<h3 id="types">Types Block</h3>
-
-<p>The types block contains the serialized representation of all of
-the types referenced in the translation unit. Each Clang type node
-(<code>PointerType</code>, <code>FunctionProtoType</code>, 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.</p>
-
-<p>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 <code>NUM_PREDEF_TYPE_IDS</code> represent predefined types
-(<code>void</code>, <code>float</code>, etc.), while other
-"user-defined" type IDs are assigned consecutively from
-<code>NUM_PREDEF_TYPE_IDS</code> 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 <code>const</code>,
-<code>volatile</code>, and <code>restrict</code> qualifiers, as in
-Clang's <a
- href="http://clang.llvm.org/docs/InternalsManual.html#Type">QualType</a>
-class.</p>
-
-<h3 id="decls">Declarations Block</h3>
-
-<p>The declarations block contains the serialized representation of
-all of the declarations referenced in the translation unit. Each Clang
-declaration node (<code>VarDecl</code>, <code>FunctionDecl</code>,
-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 <code>Decl</code> 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.</p>
-
-<p>Declarations in Clang's abstract syntax trees are stored
-hierarchically. At the top of the hierarchy is the translation unit
-(<code>TranslationUnitDecl</code>), 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 <a
-href="http://clang.llvm.org/docs/InternalsManual.html#DeclContext">declaration
-context</a>, as represented by the <code>DeclContext</code> class.
-Declaration contexts provide the mechanism to perform name lookup
-within a given declaration (e.g., find the member named <code>x</code>
-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).</p>
-
-<p>In Clang's AST file format, deserializing a declaration
-that is a <code>DeclContext</code> 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:</p>
-
-<ul>
- <li>When the front end performs name lookup to find a name
- <code>x</code> within a given declaration context (for example,
- during semantic analysis of the expression <code>p->x</code>,
- where <code>p</code>'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.</li>
-
- <li>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.</li>
-</ul>
-
-<h3 id="stmt">Statements and Expressions</h3>
-
-<p>Statements and expressions are stored in the AST file in
-both the <a href="#types">types</a> and the <a
- href="#decls">declarations</a> 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.</p>
-
-<p>As with types and declarations, each statement and expression kind
-in Clang's abstract syntax tree (<code>ForStmt</code>,
-<code>CallExpr</code>, 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 <a
-href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse
-Polish Notation</a>. For example, an expression <code>3 - 4 + 5</code>
-would be represented as follows:</p>
-
-<table border="1">
- <tr><td><code>IntegerLiteral(5)</code></td></tr>
- <tr><td><code>IntegerLiteral(4)</code></td></tr>
- <tr><td><code>IntegerLiteral(3)</code></td></tr>
- <tr><td><code>BinaryOperator(-)</code></td></tr>
- <tr><td><code>BinaryOperator(+)</code></td></tr>
- <tr><td>STOP</td></tr>
-</table>
-
-<p>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 <i>N</i>
-subexpressions--<code>BinaryOperator</code> 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.</p>
-
-<h3 id="idtable">Identifier Table Block</h3>
-
-<p>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
-<code>IdentifierInfo</code> structure). The serialized representation
-contains:</p>
-
-<ul>
- <li>The actual identifier string.</li>
- <li>Flags that describe whether this identifier is the name of a
- built-in, a poisoned identifier, an extension token, or a
- macro.</li>
- <li>If the identifier names a macro, the offset of the macro
- definition within the <a href="#preprocessor">preprocessor
- block</a>.</li>
- <li>If the identifier names one or more declarations visible from
- translation unit scope, the <a href="#decls">declaration IDs</a> of these
- declarations.</li>
-</ul>
-
-<p>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
-<code>IdentifierInfo</code> structure will have the same contents it
-would have after parsing the headers in the AST file.</p>
-
-<p>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.</p>
-
-<h3 id="method-pool">Method Pool Block</h3>
-
-<p>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 <a href="#idtable">identifier
-table</a>: 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 (<code>Sema::InstanceMethodPool</code> and
-<code>Sema::FactoryMethodPool</code> for instance and class methods,
-respectively).</p>
-
-<p>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.</p>
-
-<h2 id="tendrils">AST Reader Integration Points</h2>
-
-<p>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.</p>
-
-<p>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 <code>ASTReader</code>
-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. <code>ASTReader</code> implements the
-following abstract classes:</p>
-
-<dl>
- <dt><code>StatSysCallCache</code></dt>
- <dd>This abstract interface is associated with the
- <code>FileManager</code> class, and is used whenever the file
- manager is going to perform a <code>stat()</code> system call.</dd>
-
- <dt><code>ExternalSLocEntrySource</code></dt>
- <dd>This abstract interface is associated with the
- <code>SourceManager</code> class, and is used whenever the
- <a href="#sourcemgr">source manager</a> needs to load the details
- of a file, buffer, or macro instantiation.</dd>
-
- <dt><code>IdentifierInfoLookup</code></dt>
- <dd>This abstract interface is associated with the
- <code>IdentifierTable</code> 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 <a href="#idtable">identifier table</a>
- to load any top-level declarations or macros associated with that
- identifier.</dd>
-
- <dt><code>ExternalASTSource</code></dt>
- <dd>This abstract interface is associated with the
- <code>ASTContext</code> 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).</dd>
-
- <dt><code>ExternalSemaSource</code></dt>
- <dd>This abstract interface is associated with the <code>Sema</code>
- class, and is used whenever semantic analysis needs to read
- information from the <a href="#methodpool">global method
- pool</a>.</dd>
-</dl>
-
-<h2 id="chained">Chained precompiled headers</h2>
-
-<p>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
-<i>preamble</i>--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 #includes, 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.</p>
-
-<p>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
-<code>B.h</code> that includes another header <code>A.h</code> can
-modify the state produced by parsing <code>A.h</code>, e.g., by
-<code>#undef</code>'ing a macro defined in <code>A.h</code>.</p>
-
-<p>There are several ways in which chained precompiled headers
-generalize the AST file model:</p>
-
-<dl>
- <dt>Numbering of IDs</dt>
- <dd>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.</dd>
-
- <dt>Name lookup</dt>
- <dd>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 <a href="#idtable">identifier table</a>:
- 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.</dd>
-
- <dt>Update records</dt>
- <dd>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.</dd>
-</dl>
-
-<h2 id="modules">Modules</h2>
-
-<p>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:
-
-<dl>
- <dt>Numbering of IDs</dt>
- <dd>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.</dd>
-
- <dt>Declaration merging</dt>
- <dd>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
- <tt>printf</tt> or could forward-declare <tt>struct stat</tt>. 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 <tt>printf</tt> or <tt>struct stat</tt> 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.</dd>
-
- <dt>Name Visibility</dt>
- <dd>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.</dd>
-
-</dl>
-
-</div>
-
-</body>
-</html>
Added: cfe/trunk/docs/PCHInternals.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/PCHInternals.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/PCHInternals.rst (added)
+++ cfe/trunk/docs/PCHInternals.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,573 @@
+========================================
+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 `User's Manual <UsersManual.html#precompiledheaders>`_.
+
+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
+
+ *** PCH Statistics:
+ 933 stat cache hits
+ 4 stat cache misses
+ 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
+`SourceManager <InternalsManual.html#SourceLocation>`_ 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``) along with a cached version of the results of
+the ``stat()`` system calls performed when building the AST file. The latter
+is particularly useful in reducing system time when searching for include
+files.
+
+.. _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
+`QualType <http://clang.llvm.org/docs/InternalsManual.html#Type>`_ 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 `declaration
+context <http://clang.llvm.org/docs/InternalsManual.html#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:
+
+``StatSysCallCache``
+ This abstract interface is associated with the ``FileManager`` class, and is
+ used whenever the file manager is going to perform a ``stat()`` system call.
+
+``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.
+
Removed: cfe/trunk/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThreadSanitizer.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/ThreadSanitizer.html (original)
+++ cfe/trunk/docs/ThreadSanitizer.html (removed)
@@ -1,126 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
-<html>
-<head>
- <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>ThreadSanitizer, a race detector</title>
- <link type="text/css" rel="stylesheet" href="../menu.css">
- <link type="text/css" rel="stylesheet" href="../content.css">
- <style type="text/css">
- td {
- vertical-align: top;
- }
- </style>
-</head>
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>ThreadSanitizer</h1>
-<ul>
- <li> <a href="#intro">Introduction</a>
- <li> <a href="#howtobuild">How to Build</a>
- <li> <a href="#platforms">Supported Platforms</a>
- <li> <a href="#usage">Usage</a>
- <li> <a href="#limitations">Limitations</a>
- <li> <a href="#status">Current Status</a>
- <li> <a href="#moreinfo">More Information</a>
-</ul>
-
-<h2 id="intro">Introduction</h2>
-ThreadSanitizer is a tool that detects data races. <BR>
-It consists of a compiler instrumentation module and a run-time library. <BR>
-Typical slowdown introduced by ThreadSanitizer is <b>5x-15x</b> (TODO: these numbers are
-approximate so far).
-
-<h2 id="howtobuild">How to build</h2>
-Follow the <a href="../get_started.html">clang build instructions</a>.
-CMake build is supported.<BR>
-
-<h2 id="platforms">Supported Platforms</h2>
-ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). <BR>
-Support for MacOS 10.7 (64-bit only) is planned for late 2012. <BR>
-Support for 32-bit platforms is problematic and not yet planned.
-
-
-
-<h2 id="usage">Usage</h2>
-Simply compile your program with <tt>-fsanitize=thread -fPIE</tt> and link it
-with <tt>-fsanitize=thread -pie</tt>.<BR>
-To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
-Use <tt>-g</tt> to get file names and line numbers in the warning messages. <BR>
-
-Example:
-<pre>
-% cat projects/compiler-rt/lib/tsan/output_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;
-}
-</pre>
-
-<pre>
-% clang -fsanitize=thread -g -O1 tiny_race.c -fPIE -pie
-</pre>
-
-If a bug is detected, the program will print an error message to stderr.
-Currently, ThreadSanitizer symbolizes its output using an external
-<tt>addr2line</tt>
-process (this will be fixed in future).
-<pre>
-% TSAN_OPTIONS=strip_path_prefix=`pwd`/ # Don't print full paths.
-% ./a.out 2> log
-% cat log
-WARNING: ThreadSanitizer: data race (pid=19219)
- Write of size 4 at 0x7fcf47b21bc0 by thread 1:
- #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 1 (running) created at:
- #0 pthread_create ??:0 (exe+0x00000000c790)
- #1 main tiny_race.c:9 (exe+0x00000000a3a4)
-</pre>
-
-
-<h2 id="limitations">Limitations</h2>
-<ul>
-<li> ThreadSanitizer uses more real memory than a native run.
-At the default settings the memory overhead is 9x plus 9Mb per each thread.
-Settings with 5x and 3x overhead (but less accurate analysis) are also available.
-<li> ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
-This means that tools like <tt>ulimit</tt> may not work as usually expected.
-<li> Static linking is not supported.
-<li> ThreadSanitizer requires <tt>-fPIE -pie</tt>
-</ul>
-
-
-<h2 id="status">Current Status</h2>
-ThreadSanitizer is in alpha stage.
-It is known to work on large C++ programs using pthreads, but we do not promise
-anything (yet). <BR>
-C++11 threading is not yet supported. <BR>
-The test suite is integrated into CMake build and can be run with
-<tt>make check-tsan</tt> command. <BR>
-
-We are actively working on enhancing the tool -- stay tuned.
-Any help, especially in the form of minimized standalone tests is more than welcome.
-
-<h2 id="moreinfo">More Information</h2>
-<a href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.
-
-
-</div>
-</body>
-</html>
Added: cfe/trunk/docs/ThreadSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThreadSanitizer.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/ThreadSanitizer.rst (added)
+++ cfe/trunk/docs/ThreadSanitizer.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,95 @@
+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 **5x-15x** (TODO: these numbers are approximate so far).
+
+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 10.04). Support
+for MacOS 10.7 (64-bit only) is planned for late 2012. Support for 32-bit
+platforms is problematic and not yet planned.
+
+Usage
+-----
+
+Simply compile your program with ``-fsanitize=thread -fPIE`` and link it with
+``-fsanitize=thread -pie``. 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/output_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 -fPIE -pie
+
+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
+
+ % TSAN_OPTIONS=strip_path_prefix=`pwd`/ # Don't print full paths.
+ % ./a.out 2> log
+ % cat log
+ WARNING: ThreadSanitizer: data race (pid=19219)
+ Write of size 4 at 0x7fcf47b21bc0 by thread 1:
+ #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 1 (running) created at:
+ #0 pthread_create ??:0 (exe+0x00000000c790)
+ #1 main tiny_race.c:9 (exe+0x00000000a3a4)
+
+Limitations
+-----------
+
+* ThreadSanitizer uses more real memory than a native run. At the default
+ settings the memory overhead is 9x plus 9Mb per each thread. Settings with 5x
+ and 3x overhead (but less accurate analysis) 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.
+* Static linking is not supported.
+* ThreadSanitizer requires ``-fPIE -pie``.
+
+Current Status
+--------------
+
+ThreadSanitizer is in alpha stage. It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet). C++11 threading is not
+yet supported. 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/>`_.
+
Removed: cfe/trunk/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/Tooling.html?rev=170047&view=auto
==============================================================================
--- cfe/trunk/docs/Tooling.html (original)
+++ cfe/trunk/docs/Tooling.html (removed)
@@ -1,120 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-<title>Writing Clang Tools</title>
-<link type="text/css" rel="stylesheet" href="../menu.css">
-<link type="text/css" rel="stylesheet" href="../content.css">
-</head>
-<body>
-
-<!--#include virtual="../menu.html.incl"-->
-
-<div id="content">
-
-<h1>Writing Clang Tools</h1>
-<p>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.</p>
-
-<!-- ======================================================================= -->
-<h2 id="libclang"><a href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a></h2>
-<!-- ======================================================================= -->
-
-<p>LibClang 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.</p>
-<p>Canonical examples of when to use LibClang:</p>
-<ul>
- <li>Xcode</li>
- <li>Clang Python Bindings</li>
-</ul>
-<p>Use LibClang when you...</p>
-<ul>
- <li>want to interface with clang from other languages than C++</li>
- <li>need a stable interface that takes care to be backwards compatible</li>
- <li>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.</li>
-</ul>
-<p>Do not use LibClang when you...</p>
-<ul>
- <li>want full control over the Clang AST</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="clang-plugins"><a href="ClangPlugins.html">Clang Plugins</a></h2>
-<!-- ======================================================================= -->
-
-<p>Clang Plugins 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.</p>
-<p>Canonical examples of when to use Clang Plugins:</p>
-<ul>
- <li>special lint-style warnings or errors for your project</li>
- <li>creating additional build artifacts from a single compile step</li>
-</ul>
-<p>Use Clang Plugins when you...</p>
-<ul>
- <li>need your tool to rerun if any of the dependencies change</li>
- <li>want your tool to make or break a build</li>
- <li>need full control over the Clang AST</li>
-</ul>
-<p>Do not use Clang Plugins when you...</p>
-<ul>
- <li>want to run tools outside of your build environment</li>
- <li>want full control on how Clang is set up, including mapping of in-memory
- virtual files</li>
- <li>need to run over a specific subset of files in your project which is not
- necessarily related to any changes which would trigger rebuilds</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="libtooling"><a href="LibTooling.html">LibTooling</a></h2>
-<!-- ======================================================================= -->
-
-<p>LibTooling is a C++ interface aimed at writing standalone tools, as well as
-integrating into services that run clang tools.</p>
-<p>Canonical examples of when to use LibTooling:</p>
-<ul>
- <li>a simple syntax checker</li>
- <li>refactoring tools</li>
-</ul>
-<p>Use LibTooling when you...</p>
-<ul>
- <li>want to run tools over a single file, or a specific subset of files,
- independently of the build system</li>
- <li>want full control over the Clang AST</li>
- <li>want to share code with Clang Plugins</li>
-</ul>
-<p>Do not use LibTooling when you...</p>
-<ul>
- <li>want to run as part of the build triggered by dependency changes</li>
- <li>want a stable interface so you don't need to change your code when the
- AST API changes</li>
- <li>want high level abstractions like cursors and code completion out of the
- box</li>
- <li>do not want to write your tools in C++</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="clang-tools"><a href="ClangTools.html">Clang Tools</a></h2>
-<!-- ======================================================================= -->
-
-<p>These 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.</p>
-<p>Examples of tools we are building or planning as part of the Clang
-project:</p>
-<ul>
- <li>Syntax checking (clang-check)</li>
- <li>Automatic fixing of compile errors (clangc-fixit)</li>
- <li>Automatic code formatting</li>
- <li>Migration tools for new features in new language standards</li>
- <li>Core refactoring tools</li>
-</ul>
-
-</div>
-</body>
-</html>
-
Added: cfe/trunk/docs/Tooling.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/Tooling.rst?rev=170048&view=auto
==============================================================================
--- cfe/trunk/docs/Tooling.rst (added)
+++ cfe/trunk/docs/Tooling.rst Wed Dec 12 17:44:55 2012
@@ -0,0 +1,100 @@
+===================
+Writing Clang Tools
+===================
+
+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
+-------------
+
+`Clang Plugins <ClangPlugins.html>`_ 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
+----------
+
+`LibTooling <LibTooling.html>`_ 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 Plgins
+
+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++
+
+Clang Tools
+-----------
+
+`Clang tools <ClangTools.html>`_ 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
+* Migration tools for new features in new language standards
+* Core refactoring tools
+
Modified: cfe/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=170048&r1=170047&r2=170048&view=diff
==============================================================================
--- cfe/trunk/docs/index.rst (original)
+++ cfe/trunk/docs/index.rst Wed Dec 12 17:44:55 2012
@@ -12,6 +12,12 @@
.. toctree::
:maxdepth: 2
+ LanguageExtensions
+ LibASTMatchers
+ LibTooling
+ PCHInternals
+ ThreadSanitizer
+ Tooling
Indices and tables
More information about the cfe-commits
mailing list