[www-releases] r372328 - Check in 9.0.0 source and docs

Hans Wennborg via llvm-commits llvm-commits at lists.llvm.org
Thu Sep 19 07:32:55 PDT 2019 

Added: www-releases/trunk/9.0.0/tools/clang/docs/AttributeReference.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/AttributeReference.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/AttributeReference.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/AttributeReference.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,9718 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Attributes in Clang — Clang 9 documentation</title>
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Diagnostic flags in Clang" href="DiagnosticsReference.html" />
+    <link rel="prev" title="Clang command line argument reference" href="ClangCommandLineReference.html" /> 
+  </head><body>
+      <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+          <span>Clang 9 documentation</span></a></h1>
+        <h2 class="heading"><span>Attributes in Clang</span></h2>
+      </div>
+      <div class="topnav" role="navigation" aria-label="top navigation">
+      
+        <p>
+        «  <a href="ClangCommandLineReference.html">Clang command line argument reference</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="attributes-in-clang">
+<h1>Attributes in Clang<a class="headerlink" href="#attributes-in-clang" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id182">Introduction</a></li>
+<li><a class="reference internal" href="#function-attributes" id="id183">Function Attributes</a><ul>
+<li><a class="reference internal" href="#pragma-omp-declare-simd" id="id184">#pragma omp declare simd</a></li>
+<li><a class="reference internal" href="#pragma-omp-declare-target" id="id185">#pragma omp declare target</a></li>
+<li><a class="reference internal" href="#noreturn" id="id186">_Noreturn</a></li>
+<li><a class="reference internal" href="#abi-tag" id="id187">abi_tag</a></li>
+<li><a class="reference internal" href="#acquire-capability-acquire-shared-capability" id="id188">acquire_capability, acquire_shared_capability</a></li>
+<li><a class="reference internal" href="#alloc-align" id="id189">alloc_align</a></li>
+<li><a class="reference internal" href="#alloc-size" id="id190">alloc_size</a></li>
+<li><a class="reference internal" href="#allocator" id="id191">allocator</a></li>
+<li><a class="reference internal" href="#artificial" id="id192">artificial</a></li>
+<li><a class="reference internal" href="#assert-capability-assert-shared-capability" id="id193">assert_capability, assert_shared_capability</a></li>
+<li><a class="reference internal" href="#assume-aligned" id="id194">assume_aligned</a></li>
+<li><a class="reference internal" href="#availability" id="id195">availability</a></li>
+<li><a class="reference internal" href="#callback" id="id196">callback</a></li>
+<li><a class="reference internal" href="#carries-dependency" id="id197">carries_dependency</a></li>
+<li><a class="reference internal" href="#cf-consumed" id="id198">cf_consumed</a></li>
+<li><a class="reference internal" href="#cf-returns-not-retained" id="id199">cf_returns_not_retained</a></li>
+<li><a class="reference internal" href="#cf-returns-retained" id="id200">cf_returns_retained</a></li>
+<li><a class="reference internal" href="#code-seg" id="id201">code_seg</a></li>
+<li><a class="reference internal" href="#convergent" id="id202">convergent</a></li>
+<li><a class="reference internal" href="#cpu-dispatch" id="id203">cpu_dispatch</a></li>
+<li><a class="reference internal" href="#cpu-specific" id="id204">cpu_specific</a></li>
+<li><a class="reference internal" href="#diagnose-if" id="id205">diagnose_if</a></li>
+<li><a class="reference internal" href="#disable-tail-calls" id="id206">disable_tail_calls</a></li>
+<li><a class="reference internal" href="#enable-if" id="id207">enable_if</a></li>
+<li><a class="reference internal" href="#exclude-from-explicit-instantiation" id="id208">exclude_from_explicit_instantiation</a></li>
+<li><a class="reference internal" href="#flatten" id="id209">flatten</a></li>
+<li><a class="reference internal" href="#force-align-arg-pointer" id="id210">force_align_arg_pointer</a></li>
+<li><a class="reference internal" href="#format" id="id211">format</a></li>
+<li><a class="reference internal" href="#gnu-inline" id="id212">gnu_inline</a></li>
+<li><a class="reference internal" href="#ifunc" id="id213">ifunc</a></li>
+<li><a class="reference internal" href="#import-module" id="id214">import_module</a></li>
+<li><a class="reference internal" href="#import-name" id="id215">import_name</a></li>
+<li><a class="reference internal" href="#internal-linkage" id="id216">internal_linkage</a></li>
+<li><a class="reference internal" href="#interrupt-arm" id="id217">interrupt (ARM)</a></li>
+<li><a class="reference internal" href="#interrupt-avr" id="id218">interrupt (AVR)</a></li>
+<li><a class="reference internal" href="#interrupt-mips" id="id219">interrupt (MIPS)</a></li>
+<li><a class="reference internal" href="#interrupt-riscv" id="id220">interrupt (RISCV)</a></li>
+<li><a class="reference internal" href="#kernel" id="id221">kernel</a></li>
+<li><a class="reference internal" href="#lifetimebound" id="id222">lifetimebound</a></li>
+<li><a class="reference internal" href="#long-call-far" id="id223">long_call, far</a></li>
+<li><a class="reference internal" href="#micromips" id="id224">micromips</a></li>
+<li><a class="reference internal" href="#mig-server-routine" id="id225">mig_server_routine</a></li>
+<li><a class="reference internal" href="#min-vector-width" id="id226">min_vector_width</a></li>
+<li><a class="reference internal" href="#no-caller-saved-registers" id="id227">no_caller_saved_registers</a></li>
+<li><a class="reference internal" href="#no-sanitize" id="id228">no_sanitize</a></li>
+<li><a class="reference internal" href="#no-sanitize-address-no-address-safety-analysis" id="id229">no_sanitize_address, no_address_safety_analysis</a></li>
+<li><a class="reference internal" href="#no-sanitize-memory" id="id230">no_sanitize_memory</a></li>
+<li><a class="reference internal" href="#no-sanitize-thread" id="id231">no_sanitize_thread</a></li>
+<li><a class="reference internal" href="#no-speculative-load-hardening" id="id232">no_speculative_load_hardening</a></li>
+<li><a class="reference internal" href="#no-split-stack" id="id233">no_split_stack</a></li>
+<li><a class="reference internal" href="#no-stack-protector" id="id234">no_stack_protector</a></li>
+<li><a class="reference internal" href="#noalias" id="id235">noalias</a></li>
+<li><a class="reference internal" href="#nocf-check" id="id236">nocf_check</a></li>
+<li><a class="reference internal" href="#nodiscard-warn-unused-result" id="id237">nodiscard, warn_unused_result</a></li>
+<li><a class="reference internal" href="#noduplicate" id="id238">noduplicate</a></li>
+<li><a class="reference internal" href="#nomicromips" id="id239">nomicromips</a></li>
+<li><a class="reference internal" href="#id1" id="id240">noreturn</a></li>
+<li><a class="reference internal" href="#not-tail-called" id="id241">not_tail_called</a></li>
+<li><a class="reference internal" href="#nothrow" id="id242">nothrow</a></li>
+<li><a class="reference internal" href="#ns-consumed" id="id243">ns_consumed</a></li>
+<li><a class="reference internal" href="#ns-consumes-self" id="id244">ns_consumes_self</a></li>
+<li><a class="reference internal" href="#ns-returns-autoreleased" id="id245">ns_returns_autoreleased</a></li>
+<li><a class="reference internal" href="#ns-returns-not-retained" id="id246">ns_returns_not_retained</a></li>
+<li><a class="reference internal" href="#ns-returns-retained" id="id247">ns_returns_retained</a></li>
+<li><a class="reference internal" href="#objc-method-family" id="id248">objc_method_family</a></li>
+<li><a class="reference internal" href="#objc-requires-super" id="id249">objc_requires_super</a></li>
+<li><a class="reference internal" href="#optnone" id="id250">optnone</a></li>
+<li><a class="reference internal" href="#os-consumed" id="id251">os_consumed</a></li>
+<li><a class="reference internal" href="#os-consumes-this" id="id252">os_consumes_this</a></li>
+<li><a class="reference internal" href="#os-returns-not-retained" id="id253">os_returns_not_retained</a></li>
+<li><a class="reference internal" href="#os-returns-retained" id="id254">os_returns_retained</a></li>
+<li><a class="reference internal" href="#os-returns-retained-on-non-zero" id="id255">os_returns_retained_on_non_zero</a></li>
+<li><a class="reference internal" href="#os-returns-retained-on-zero" id="id256">os_returns_retained_on_zero</a></li>
+<li><a class="reference internal" href="#overloadable" id="id257">overloadable</a></li>
+<li><a class="reference internal" href="#reinitializes" id="id258">reinitializes</a></li>
+<li><a class="reference internal" href="#release-capability-release-shared-capability" id="id259">release_capability, release_shared_capability</a></li>
+<li><a class="reference internal" href="#short-call-near" id="id260">short_call, near</a></li>
+<li><a class="reference internal" href="#signal" id="id261">signal</a></li>
+<li><a class="reference internal" href="#id2" id="id262">speculative_load_hardening</a></li>
+<li><a class="reference internal" href="#target" id="id263">target</a></li>
+<li><a class="reference internal" href="#try-acquire-capability-try-acquire-shared-capability" id="id264">try_acquire_capability, try_acquire_shared_capability</a></li>
+<li><a class="reference internal" href="#xray-always-instrument-xray-never-instrument-xray-log-args" id="id265">xray_always_instrument, xray_never_instrument, xray_log_args</a></li>
+<li><a class="reference internal" href="#id4" id="id266">xray_always_instrument, xray_never_instrument, xray_log_args</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#variable-attributes" id="id267">Variable Attributes</a><ul>
+<li><a class="reference internal" href="#always-destroy" id="id268">always_destroy</a></li>
+<li><a class="reference internal" href="#dllexport" id="id269">dllexport</a></li>
+<li><a class="reference internal" href="#dllimport" id="id270">dllimport</a></li>
+<li><a class="reference internal" href="#init-seg" id="id271">init_seg</a></li>
+<li><a class="reference internal" href="#maybe-unused-unused" id="id272">maybe_unused, unused</a></li>
+<li><a class="reference internal" href="#no-destroy" id="id273">no_destroy</a></li>
+<li><a class="reference internal" href="#nodebug" id="id274">nodebug</a></li>
+<li><a class="reference internal" href="#noescape" id="id275">noescape</a></li>
+<li><a class="reference internal" href="#nosvm" id="id276">nosvm</a></li>
+<li><a class="reference internal" href="#objc-externally-retained" id="id277">objc_externally_retained</a></li>
+<li><a class="reference internal" href="#pass-object-size-pass-dynamic-object-size" id="id278">pass_object_size, pass_dynamic_object_size</a></li>
+<li><a class="reference internal" href="#require-constant-initialization" id="id279">require_constant_initialization</a></li>
+<li><a class="reference internal" href="#section-declspec-allocate" id="id280">section, __declspec(allocate)</a></li>
+<li><a class="reference internal" href="#swift-context" id="id281">swift_context</a></li>
+<li><a class="reference internal" href="#swift-error-result" id="id282">swift_error_result</a></li>
+<li><a class="reference internal" href="#swift-indirect-result" id="id283">swift_indirect_result</a></li>
+<li><a class="reference internal" href="#swiftcall" id="id284">swiftcall</a></li>
+<li><a class="reference internal" href="#thread" id="id285">thread</a></li>
+<li><a class="reference internal" href="#tls-model" id="id286">tls_model</a></li>
+<li><a class="reference internal" href="#uninitialized" id="id287">uninitialized</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#field-attributes" id="id288">Field Attributes</a><ul>
+<li><a class="reference internal" href="#no-unique-address" id="id289">no_unique_address</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-attributes" id="id290">Type Attributes</a><ul>
+<li><a class="reference internal" href="#align-value" id="id291">align_value</a></li>
+<li><a class="reference internal" href="#hip-pinned-shadow" id="id292">hip_pinned_shadow</a></li>
+<li><a class="reference internal" href="#noderef" id="id293">noderef</a></li>
+<li><a class="reference internal" href="#objc-class-stub" id="id294">objc_class_stub</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#statement-attributes" id="id295">Statement Attributes</a><ul>
+<li><a class="reference internal" href="#pragma-clang-loop" id="id296">#pragma clang loop</a></li>
+<li><a class="reference internal" href="#pragma-unroll-pragma-nounroll" id="id297">#pragma unroll, #pragma nounroll</a></li>
+<li><a class="reference internal" href="#read-only-write-only-read-write-read-only-write-only-read-write" id="id298">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a></li>
+<li><a class="reference internal" href="#fallthrough" id="id299">fallthrough</a></li>
+<li><a class="reference internal" href="#intel-reqd-sub-group-size" id="id300">intel_reqd_sub_group_size</a></li>
+<li><a class="reference internal" href="#opencl-unroll-hint" id="id301">opencl_unroll_hint</a></li>
+<li><a class="reference internal" href="#suppress" id="id302">suppress</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#declaration-attributes" id="id303">Declaration Attributes</a><ul>
+<li><a class="reference internal" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" id="id304">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a></li>
+<li><a class="reference internal" href="#deprecated" id="id305">deprecated</a></li>
+<li><a class="reference internal" href="#empty-bases" id="id306">empty_bases</a></li>
+<li><a class="reference internal" href="#enum-extensibility" id="id307">enum_extensibility</a></li>
+<li><a class="reference internal" href="#external-source-symbol" id="id308">external_source_symbol</a></li>
+<li><a class="reference internal" href="#flag-enum" id="id309">flag_enum</a></li>
+<li><a class="reference internal" href="#layout-version" id="id310">layout_version</a></li>
+<li><a class="reference internal" href="#lto-visibility-public" id="id311">lto_visibility_public</a></li>
+<li><a class="reference internal" href="#novtable" id="id312">novtable</a></li>
+<li><a class="reference internal" href="#objc-boxable" id="id313">objc_boxable</a></li>
+<li><a class="reference internal" href="#objc-nonlazy-class" id="id314">objc_nonlazy_class</a></li>
+<li><a class="reference internal" href="#objc-runtime-name" id="id315">objc_runtime_name</a></li>
+<li><a class="reference internal" href="#objc-runtime-visible" id="id316">objc_runtime_visible</a></li>
+<li><a class="reference internal" href="#objc-subclassing-restricted" id="id317">objc_subclassing_restricted</a></li>
+<li><a class="reference internal" href="#selectany" id="id318">selectany</a></li>
+<li><a class="reference internal" href="#transparent-union" id="id319">transparent_union</a></li>
+<li><a class="reference internal" href="#trivial-abi" id="id320">trivial_abi</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-address-spaces" id="id321">OpenCL Address Spaces</a><ul>
+<li><a class="reference internal" href="#constant" id="id322">constant</a></li>
+<li><a class="reference internal" href="#generic" id="id323">generic</a></li>
+<li><a class="reference internal" href="#global" id="id324">global</a></li>
+<li><a class="reference internal" href="#local" id="id325">local</a></li>
+<li><a class="reference internal" href="#private" id="id326">private</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#amd-gpu-attributes" id="id327">AMD GPU Attributes</a><ul>
+<li><a class="reference internal" href="#amdgpu-flat-work-group-size" id="id328">amdgpu_flat_work_group_size</a></li>
+<li><a class="reference internal" href="#amdgpu-num-sgpr" id="id329">amdgpu_num_sgpr</a></li>
+<li><a class="reference internal" href="#amdgpu-num-vgpr" id="id330">amdgpu_num_vgpr</a></li>
+<li><a class="reference internal" href="#amdgpu-waves-per-eu" id="id331">amdgpu_waves_per_eu</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id332">Calling Conventions</a><ul>
+<li><a class="reference internal" href="#aarch64-vector-pcs" id="id333">aarch64_vector_pcs</a></li>
+<li><a class="reference internal" href="#fastcall" id="id334">fastcall</a></li>
+<li><a class="reference internal" href="#ms-abi" id="id335">ms_abi</a></li>
+<li><a class="reference internal" href="#pcs" id="id336">pcs</a></li>
+<li><a class="reference internal" href="#preserve-all" id="id337">preserve_all</a></li>
+<li><a class="reference internal" href="#preserve-most" id="id338">preserve_most</a></li>
+<li><a class="reference internal" href="#regcall" id="id339">regcall</a></li>
+<li><a class="reference internal" href="#regparm" id="id340">regparm</a></li>
+<li><a class="reference internal" href="#stdcall" id="id341">stdcall</a></li>
+<li><a class="reference internal" href="#thiscall" id="id342">thiscall</a></li>
+<li><a class="reference internal" href="#vectorcall" id="id343">vectorcall</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#consumed-annotation-checking" id="id344">Consumed Annotation Checking</a><ul>
+<li><a class="reference internal" href="#callable-when" id="id345">callable_when</a></li>
+<li><a class="reference internal" href="#consumable" id="id346">consumable</a></li>
+<li><a class="reference internal" href="#param-typestate" id="id347">param_typestate</a></li>
+<li><a class="reference internal" href="#return-typestate" id="id348">return_typestate</a></li>
+<li><a class="reference internal" href="#set-typestate" id="id349">set_typestate</a></li>
+<li><a class="reference internal" href="#test-typestate" id="id350">test_typestate</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-safety-checking" id="id351">Type Safety Checking</a><ul>
+<li><a class="reference internal" href="#argument-with-type-tag" id="id352">argument_with_type_tag</a></li>
+<li><a class="reference internal" href="#pointer-with-type-tag" id="id353">pointer_with_type_tag</a></li>
+<li><a class="reference internal" href="#type-tag-for-datatype" id="id354">type_tag_for_datatype</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nullability-attributes" id="id355">Nullability Attributes</a><ul>
+<li><a class="reference internal" href="#nonnull" id="id356">_Nonnull</a></li>
+<li><a class="reference internal" href="#null-unspecified" id="id357">_Null_unspecified</a></li>
+<li><a class="reference internal" href="#nullable" id="id358">_Nullable</a></li>
+<li><a class="reference internal" href="#id15" id="id359">nonnull</a></li>
+<li><a class="reference internal" href="#returns-nonnull" id="id360">returns_nonnull</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id182">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This page lists the attributes currently supported by Clang.</p>
+</div>
+<div class="section" id="function-attributes">
+<h2><a class="toc-backref" href="#id183">Function Attributes</a><a class="headerlink" href="#function-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="pragma-omp-declare-simd">
+<h3><a class="toc-backref" href="#id184">#pragma omp declare simd</a><a class="headerlink" href="#pragma-omp-declare-simd" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id16">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id16" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">omp</span> <span class="pre">declare</span> <span class="pre">simd</span></code></td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare simd</cite> construct can be applied to a function to enable the creation
+of one or more versions that can process multiple arguments using SIMD
+instructions from a single invocation in a SIMD loop. The <cite>declare simd</cite>
+directive is a declarative directive. There may be multiple <cite>declare simd</cite>
+directives for a function. The use of a <cite>declare simd</cite> construct on a function
+enables the creation of SIMD versions of the associated function that can be
+used to process multiple arguments from a single invocation from a SIMD loop
+concurrently.
+The syntax of the <cite>declare simd</cite> construct is as follows:</p>
+<blockquote>
+<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#pragma omp declare simd [clause[[,] clause] ...] new-line
+[#pragma omp declare simd [clause[[,] clause] ...] new-line]
+[...]
+function definition or declaration
+</pre></div>
+</div>
+</div></blockquote>
+<p>where clause is one of the following:</p>
+<blockquote>
+<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>simdlen(length)
+linear(argument-list[:constant-linear-step])
+aligned(argument-list[:alignment])
+uniform(argument-list)
+inbranch
+notinbranch
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="pragma-omp-declare-target">
+<h3><a class="toc-backref" href="#id185">#pragma omp declare target</a><a class="headerlink" href="#pragma-omp-declare-target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id17">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id17" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">omp</span> <span class="pre">declare</span> <span class="pre">target</span></code></td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare target</cite> directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.</p>
+<p>The syntax of the declare target directive is as follows:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma omp declare target new-line</span>
+<span class="n">declarations</span><span class="o">-</span><span class="n">definition</span><span class="o">-</span><span class="n">seq</span>
+<span class="cp">#pragma omp end declare target new-line</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="noreturn">
+<h3><a class="toc-backref" href="#id186">_Noreturn</a><a class="headerlink" href="#noreturn" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id18">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id18" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">_Noreturn</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <code class="docutils literal notranslate"><span class="pre">_Noreturn</span></code> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <code class="docutils literal notranslate"><span class="pre">_Noreturn</span></code>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="abi-tag">
+<h3><a class="toc-backref" href="#id187">abi_tag</a><a class="headerlink" href="#abi-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id19">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id19" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">abi_tag</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::abi_tag</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">abi_tag</span></code> attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+with different ABI versions supported. For example, a newer version of a class
+could have a different set of data members and thus have a different size. Using
+the <code class="docutils literal notranslate"><span class="pre">abi_tag</span></code> attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefore, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.</p>
+</div>
+<div class="section" id="acquire-capability-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id188">acquire_capability, acquire_shared_capability</a><a class="headerlink" href="#acquire-capability-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id20">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id20" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">acquire_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">acquire_shared_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">exclusive_lock_function</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">shared_lock_function</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::acquire_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::acquire_shared_capability</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as acquiring a capability.</p>
+</div>
+<div class="section" id="alloc-align">
+<h3><a class="toc-backref" href="#id189">alloc_align</a><a class="headerlink" href="#alloc-align" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id21">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id21" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">alloc_align</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::alloc_align</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((alloc_align(<alignment>))</span></code> on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter. The
+parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit <code class="docutils literal notranslate"><span class="pre">this</span></code>
+parameter.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// The returned pointer has the alignment specified by the first parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">a</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">1</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer has the alignment specified by the second parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">b</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">v</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">2</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer has the alignment specified by the second visible</span>
+<span class="c1">// parameter, however it must be adjusted for the implicit 'this' parameter.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">Foo</span><span class="o">::</span><span class="n">b</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">v</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">align</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_align</span><span class="p">(</span><span class="mi">3</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Note that this attribute merely informs the compiler that a function always
+returns a sufficiently aligned pointer. It does not cause the compiler to
+emit code to enforce that alignment.  The behavior is undefined if the returned
+poitner is not sufficiently aligned.</p>
+</div>
+<div class="section" id="alloc-size">
+<h3><a class="toc-backref" href="#id190">alloc_size</a><a class="headerlink" href="#alloc-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id22">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id22" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">alloc_size</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::alloc_size</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">alloc_size</span></code> attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned pointer. <code class="docutils literal notranslate"><span class="pre">alloc_size</span></code> takes one or two arguments.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">alloc_size(N)</span></code> implies that argument number N equals the number of
+available bytes at the returned pointer.</li>
+<li><code class="docutils literal notranslate"><span class="pre">alloc_size(N,</span> <span class="pre">M)</span></code> implies that the product of argument number N and
+argument number M equals the number of available bytes at the returned
+pointer.</li>
+</ul>
+<p>Argument numbers are 1-based.</p>
+<p>An example of how to use <code class="docutils literal notranslate"><span class="pre">alloc_size</span></code></p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">my_malloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">my_calloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="o">=</span> <span class="n">my_malloc</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">a</span> <span class="o">=</span> <span class="n">my_calloc</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">5</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This attribute works differently in clang than it does in GCC.
+Specifically, clang will only trace <code class="docutils literal notranslate"><span class="pre">const</span></code> pointers (as above); we give up
+on pointers that are not marked as <code class="docutils literal notranslate"><span class="pre">const</span></code>. In the vast majority of cases,
+this is unimportant, because LLVM has support for the <code class="docutils literal notranslate"><span class="pre">alloc_size</span></code>
+attribute. However, this may cause mildly unintuitive behavior when used with
+other attributes, such as <code class="docutils literal notranslate"><span class="pre">enable_if</span></code>.</p>
+</div>
+</div>
+<div class="section" id="allocator">
+<h3><a class="toc-backref" href="#id191">allocator</a><a class="headerlink" href="#allocator" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id23">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id23" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">allocator</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec(allocator)</span></code> attribute is applied to functions that allocate
+memory, such as operator new in C++. When CodeView debug information is emitted
+(enabled by <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-gcodeview</span></code> or <code class="docutils literal notranslate"><span class="pre">clang-cl</span> <span class="pre">/Z7</span></code>), Clang will attempt to
+record the code offset of heap allocation call sites in the debug info. It will
+also record the type being allocated using some local heuristics. The Visual
+Studio debugger uses this information to <a class="reference external" href="https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage">profile memory usage</a>.</p>
+<p>This attribute does not affect optimizations in any way, unlike GCC’s
+<code class="docutils literal notranslate"><span class="pre">__attribute__((malloc))</span></code>.</p>
+</div>
+<div class="section" id="artificial">
+<h3><a class="toc-backref" href="#id192">artificial</a><a class="headerlink" href="#artificial" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id24">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id24" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">artificial</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::artificial</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">artificial</span></code> attribute can be applied to an inline function. If such a
+function is inlined, the attribute indicates that debuggers should associate
+the resulting instructions with the call site, rather than with the
+corresponding line within the inlined callee.</p>
+</div>
+<div class="section" id="assert-capability-assert-shared-capability">
+<h3><a class="toc-backref" href="#id193">assert_capability, assert_shared_capability</a><a class="headerlink" href="#assert-capability-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id25">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id25" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">assert_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">assert_shared_capability</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::assert_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::assert_shared_capability</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.</p>
+</div>
+<div class="section" id="assume-aligned">
+<h3><a class="toc-backref" href="#id194">assume_aligned</a><a class="headerlink" href="#assume-aligned" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id26">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id26" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">assume_aligned</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::assume_aligned</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((assume_aligned(<alignment>[,<offset>]))</span></code> on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// The returned pointer value has 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">a</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer value is 4 bytes greater than an address having</span>
+<span class="c1">// 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">b</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">,</span> <span class="mi">4</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.</p>
+</div>
+<div class="section" id="availability">
+<h3><a class="toc-backref" href="#id195">availability</a><a class="headerlink" href="#availability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id27">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id27" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">availability</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::availability</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::availability</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">availability</span></code> attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions.  Consider
+the function declaration for a hypothetical function <code class="docutils literal notranslate"><span class="pre">f</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">,</span><span class="n">deprecated</span><span class="o">=</span><span class="mf">10.6</span><span class="p">,</span><span class="n">obsoleted</span><span class="o">=</span><span class="mf">10.7</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>The availability attribute states that <code class="docutils literal notranslate"><span class="pre">f</span></code> was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7.  This information
+is used by Clang to determine when it is safe to use <code class="docutils literal notranslate"><span class="pre">f</span></code>: for example, if
+Clang is instructed to compile code for macOS 10.5, a call to <code class="docutils literal notranslate"><span class="pre">f()</span></code>
+succeeds.  If Clang is instructed to compile code for macOS 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 macOS 10.7, the call
+fails because <code class="docutils literal notranslate"><span class="pre">f()</span></code> is no longer available.</p>
+<p>The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration’s lifetime (in any order) along with additional information.  Those
+clauses can be:</p>
+<dl class="docutils">
+<dt>introduced=<em>version</em></dt>
+<dd>The first version in which this declaration was introduced.</dd>
+<dt>deprecated=<em>version</em></dt>
+<dd>The first version in which this declaration was deprecated, meaning that
+users should migrate away from this API.</dd>
+<dt>obsoleted=<em>version</em></dt>
+<dd>The first version in which this declaration was obsoleted, meaning that it
+was removed completely and can no longer be used.</dd>
+<dt>unavailable</dt>
+<dd>This declaration is never available on this platform.</dd>
+<dt>message=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will provide when emitting a warning or
+error about use of a deprecated or obsoleted declaration.  Useful to direct
+users to replacement APIs.</dd>
+<dt>replacement=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will use to provide Fix-It when emitting
+a warning about use of a deprecated declaration. The Fix-It will replace
+the deprecated declaration with the new declaration specified.</dd>
+</dl>
+<p>Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. For most platforms, the availability
+attribute with the platform corresponding to the target platform will be used;
+any others will be ignored. However, the availability for <code class="docutils literal notranslate"><span class="pre">watchOS</span></code> and
+<code class="docutils literal notranslate"><span class="pre">tvOS</span></code> can be implicitly inferred from an <code class="docutils literal notranslate"><span class="pre">iOS</span></code> availability attribute.
+Any explicit availability attributes for those platforms are still prefered over
+the implicitly inferred availability attributes. If no availability attribute
+specifies availability for the current target platform, the availability
+attributes are ignored. Supported platforms are:</p>
+<dl class="docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">ios</span></code></dt>
+<dd>Apple’s iOS operating system.  The minimum deployment target is specified by
+the <code class="docutils literal notranslate"><span class="pre">-mios-version-min=*version*</span></code> or <code class="docutils literal notranslate"><span class="pre">-miphoneos-version-min=*version*</span></code>
+command-line arguments.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">macos</span></code></dt>
+<dd>Apple’s macOS operating system.  The minimum deployment target is
+specified by the <code class="docutils literal notranslate"><span class="pre">-mmacosx-version-min=*version*</span></code> command-line argument.
+<code class="docutils literal notranslate"><span class="pre">macosx</span></code> is supported for backward-compatibility reasons, but it is
+deprecated.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">tvos</span></code></dt>
+<dd>Apple’s tvOS operating system.  The minimum deployment target is specified by
+the <code class="docutils literal notranslate"><span class="pre">-mtvos-version-min=*version*</span></code> command-line argument.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">watchos</span></code></dt>
+<dd>Apple’s watchOS operating system.  The minimum deployment target is specified by
+the <code class="docutils literal notranslate"><span class="pre">-mwatchos-version-min=*version*</span></code> command-line argument.</dd>
+</dl>
+<p>A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced.  When this happens, the
+declaration is <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly linked</a>,
+as if the <code class="docutils literal notranslate"><span class="pre">weak_import</span></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>
+<p>The flag <code class="docutils literal notranslate"><span class="pre">strict</span></code> disallows using API when deploying back to a
+platform version prior to when the declaration was introduced.  An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.</p>
+<p>If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span> <span class="c1">// okay, matches</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">ios</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">4.0</span><span class="p">)));</span> <span class="c1">// okay, adds a new platform</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> <span class="c1">// okay, inherits both macos and ios availability from above.</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: mismatch</span>
+</pre></div>
+</div>
+<p>When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="nc">A</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method2</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">@end</span>
+
+<span class="k">@interface</span> <span class="nc">B</span> : <span class="nc">A</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.3</span><span class="p">)));</span> <span class="c1">// okay: method moved into base class later</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: this method was available via the base class in 10.4</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Starting with the macOS 10.12 SDK, the <code class="docutils literal notranslate"><span class="pre">API_AVAILABLE</span></code> macro from
+<code class="docutils literal notranslate"><span class="pre"><os/availability.h></span></code> can simplify the spelling:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="nc">A</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">API_AVAILABLE</span><span class="p">(</span><span class="n">macos</span><span class="p">(</span><span class="mf">10.11</span><span class="p">)));</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">otherMethod</span> <span class="n">API_AVAILABLE</span><span class="p">(</span><span class="n">macos</span><span class="p">(</span><span class="mf">10.11</span><span class="p">),</span> <span class="n">ios</span><span class="p">(</span><span class="mf">11.0</span><span class="p">));</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Availability attributes can also be applied using a <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code>.
+Any explicit availability attribute whose platform corresponds to the target
+platform is applied to a declaration regardless of the availability attributes
+specified in the pragma. For example, in the code below,
+<code class="docutils literal notranslate"><span class="pre">hasExplicitAvailabilityAttribute</span></code> will use the <code class="docutils literal notranslate"><span class="pre">macOS</span></code> availability
+attribute that is specified with the declaration, whereas
+<code class="docutils literal notranslate"><span class="pre">getsThePragmaAvailabilityAttribute</span></code> will use the <code class="docutils literal notranslate"><span class="pre">macOS</span></code> availability
+attribute that is applied by the pragma.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)</span>
+<span class="kt">void</span> <span class="nf">getsThePragmaAvailabilityAttribute</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">hasExplicitAvailabilityAttribute</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>For platforms like <code class="docutils literal notranslate"><span class="pre">watchOS</span></code> and <code class="docutils literal notranslate"><span class="pre">tvOS</span></code>, whose availability attributes can
+be implicitly inferred from an <code class="docutils literal notranslate"><span class="pre">iOS</span></code> availability attribute, the logic is
+slightly more complex. The explicit and the pragma-applied availability
+attributes whose platform corresponds to the target platform are applied as
+described in the previous paragraph. However, the implicitly inferred attributes
+are applied to a declaration only when there is no explicit or pragma-applied
+availability attribute whose platform corresponds to the target platform. For
+example, the function below will receive the <code class="docutils literal notranslate"><span class="pre">tvOS</span></code> availability from the
+pragma rather than using the inferred <code class="docutils literal notranslate"><span class="pre">iOS</span></code> availability from the declaration:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)</span>
+<span class="kt">void</span> <span class="nf">getsThePragmaTVOSAvailabilityAttribute</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">iOS</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">11.0</span><span class="p">)));</span>
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>The compiler is also able to apply implicly inferred attributes from a pragma
+as well. For example, when targeting <code class="docutils literal notranslate"><span class="pre">tvOS</span></code>, the function below will receive
+a <code class="docutils literal notranslate"><span class="pre">tvOS</span></code> availability attribute that is implicitly inferred from the <code class="docutils literal notranslate"><span class="pre">iOS</span></code>
+availability attribute applied by the pragma:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)</span>
+<span class="kt">void</span> <span class="nf">infersTVOSAvailabilityFromPragma</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>The implicit attributes that are inferred from explicitly specified attributes
+whose platform corresponds to the target platform are applied to the declaration
+even if there is an availability attribute that can be inferred from a pragma.
+For example, the function below will receive the <code class="docutils literal notranslate"><span class="pre">tvOS,</span> <span class="pre">introduced=11.0</span></code>
+availability that is inferred from the attribute on the declaration rather than
+inferring availability from the pragma:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)</span>
+<span class="kt">void</span> <span class="nf">infersTVOSAvailabilityFromAttributeNextToDeclaration</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">iOS</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">11.0</span><span class="p">)));</span>
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>Also see the documentation for <a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available">@available</a></p>
+</div>
+<div class="section" id="callback">
+<h3><a class="toc-backref" href="#id196">callback</a><a class="headerlink" href="#callback" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id28">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id28" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">callback</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::callback</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::callback</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">callback</span></code> attribute specifies that the annotated function may invoke the
+specified callback zero or more times. The callback, as well as the passed
+arguments, are identified by their parameter name or position (starting with
+1!) in the annotated function. The first position in the attribute identifies
+the callback callee, the following positions declare describe its arguments.
+The callback callee is required to be callable with the number, and order, of
+the specified arguments. The index <cite>0</cite>, or the identifier <cite>this</cite>, is used to
+represent an implicit “this” pointer in class methods. If there is no implicit
+“this” pointer it shall not be referenced. The index ‘-1’, or the name “__”,
+represents an unknown callback callee argument. This can be a value which is
+not present in the declared parameter list, or one that is, but is potentially
+inspected, captured, or modified. Parameter names and indices can be mixed in
+the callback attribute.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">callback</span></code> attribute, which is directly translated to <code class="docutils literal notranslate"><span class="pre">callback</span></code>
+metadata <<a class="reference external" href="http://llvm.org/docs/LangRef.html#callback-metadata">http://llvm.org/docs/LangRef.html#callback-metadata</a>>, make the
+connection between the call to the annotated function and the callback callee.
+This can enable interprocedural optimizations which were otherwise impossible.
+If a function parameter is mentioned in the <code class="docutils literal notranslate"><span class="pre">callback</span></code> attribute, through its
+position, it is undefined if that parameter is used for anything other than the
+actual callback. Inspected, captured, or modified parameters shall not be
+listed in the <code class="docutils literal notranslate"><span class="pre">callback</span></code> metadata.</p>
+<p>Example encodings for the callback performed by <cite>pthread_create</cite> are shown
+below. The explicit attribute annotation indicates that the third parameter
+(<cite>start_routine</cite>) is called zero or more times by the <cite>pthread_create</cite> function,
+and that the fourth parameter (<cite>arg</cite>) is passed along. Note that the callback
+behavior of <cite>pthread_create</cite> is automatically recognized by Clang. In addition,
+the declarations of <cite>__kmpc_fork_teams</cite> and <cite>__kmpc_fork_call</cite>, generated for
+<cite>#pragma omp target teams</cite> and <cite>#pragma omp parallel</cite>, respectively, are also
+automatically recognized as broker functions. Further functions might be added
+in the future.</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">callback</span> <span class="p">(</span><span class="n">start_routine</span><span class="p">,</span> <span class="n">arg</span><span class="p">)))</span>
+<span class="kt">int</span> <span class="n">pthread_create</span><span class="p">(</span><span class="n">pthread_t</span> <span class="o">*</span><span class="kr">thread</span><span class="p">,</span> <span class="k">const</span> <span class="n">pthread_attr_t</span> <span class="o">*</span><span class="n">attr</span><span class="p">,</span>
+                   <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">start_routine</span><span class="p">)</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">);</span>
+
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">callback</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)))</span>
+<span class="kt">int</span> <span class="n">pthread_create</span><span class="p">(</span><span class="n">pthread_t</span> <span class="o">*</span><span class="kr">thread</span><span class="p">,</span> <span class="k">const</span> <span class="n">pthread_attr_t</span> <span class="o">*</span><span class="n">attr</span><span class="p">,</span>
+                   <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">start_routine</span><span class="p">)</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="carries-dependency">
+<h3><a class="toc-backref" href="#id197">carries_dependency</a><a class="headerlink" href="#carries-dependency" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id29">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id29" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">carries_dependency</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">carries_dependency</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">carries_dependency</span></code> attribute specifies dependency propagation into and
+out of functions.</p>
+<p>When specified on a function or Objective-C method, the <code class="docutils literal notranslate"><span class="pre">carries_dependency</span></code>
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.</p>
+<p>Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.</p>
+</div>
+<div class="section" id="cf-consumed">
+<h3><a class="toc-backref" href="#id198">cf_consumed</a><a class="headerlink" href="#cf-consumed" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id30">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id30" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cf_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_consumed</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="cf-returns-not-retained">
+<h3><a class="toc-backref" href="#id199">cf_returns_not_retained</a><a class="headerlink" href="#cf-returns-not-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id31">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id31" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_returns_not_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="cf-returns-retained">
+<h3><a class="toc-backref" href="#id200">cf_returns_retained</a><a class="headerlink" href="#cf-returns-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id32">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id32" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cf_returns_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="code-seg">
+<h3><a class="toc-backref" href="#id201">code_seg</a><a class="headerlink" href="#code-seg" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id33">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id33" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">code_seg</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec(code_seg)</span></code> attribute enables the placement of code into separate
+named segments that can be paged or locked in memory individually. This attribute
+is used to control the placement of instantiated templates and compiler-generated
+code. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/dn636922.aspx">__declspec(code_seg)</a> on MSDN.</p>
+</div>
+<div class="section" id="convergent">
+<h3><a class="toc-backref" href="#id202">convergent</a><a class="headerlink" href="#convergent" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id34">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id34" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">convergent</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::convergent</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::convergent</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">convergent</span></code> attribute can be placed on a function declaration. It is
+translated into the LLVM <code class="docutils literal notranslate"><span class="pre">convergent</span></code> attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.</p>
+<p>In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.</p>
+<p>This attribute is different from <code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.</p>
+<p>Sample usage:
+.. code-block:: c</p>
+<blockquote>
+<div>void convfunc(void) __attribute__((convergent));
+// Setting it as a C++11 attribute is also valid in a C++ program.
+// void convfunc(void) [[clang::convergent]];</div></blockquote>
+</div>
+<div class="section" id="cpu-dispatch">
+<h3><a class="toc-backref" href="#id203">cpu_dispatch</a><a class="headerlink" href="#cpu-dispatch" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id35">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id35" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cpu_dispatch</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cpu_dispatch</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code> and <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code> attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.</p>
+<p>Function versions are defined with <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code>, which takes one or more CPU
+names as a parameter. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Declares and defines the ivybridge version of single_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Declares and defines the atom version of single_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Declares and defines both the ivybridge and atom version of multi_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">multi_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+</pre></div>
+</div>
+<p>A dispatching (or resolving) function can be declared anywhere in a project’s
+source code with <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code>. This attribute takes one or more CPU names
+as a parameter (like <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code>). Functions marked with <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code>
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Creates a resolver for single_cpu above.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_dispatch</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Creates a resolver for multi_cpu, but adds a 3rd version defined in another</span>
+<span class="c1">// translation unit.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_dispatch</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">,</span> <span class="n">sandybridge</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">multi_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+</pre></div>
+</div>
+<p>Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn’t defined in the program will result in a
+linking failure.</p>
+<p>It is also possible to specify a CPU name of <code class="docutils literal notranslate"><span class="pre">generic</span></code> which will be resolved
+if the executing processor doesn’t satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn’t satisfy
+any option of a multiversioned function is undefined.</p>
+</div>
+<div class="section" id="cpu-specific">
+<h3><a class="toc-backref" href="#id204">cpu_specific</a><a class="headerlink" href="#cpu-specific" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id36">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id36" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cpu_specific</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::cpu_specific</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code> and <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code> attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.</p>
+<p>Function versions are defined with <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code>, which takes one or more CPU
+names as a parameter. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Declares and defines the ivybridge version of single_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Declares and defines the atom version of single_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Declares and defines both the ivybridge and atom version of multi_cpu.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_specific</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">multi_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+</pre></div>
+</div>
+<p>A dispatching (or resolving) function can be declared anywhere in a project’s
+source code with <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code>. This attribute takes one or more CPU names
+as a parameter (like <code class="docutils literal notranslate"><span class="pre">cpu_specific</span></code>). Functions marked with <code class="docutils literal notranslate"><span class="pre">cpu_dispatch</span></code>
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Creates a resolver for single_cpu above.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_dispatch</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">single_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+
+<span class="c1">// Creates a resolver for multi_cpu, but adds a 3rd version defined in another</span>
+<span class="c1">// translation unit.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">cpu_dispatch</span><span class="p">(</span><span class="n">ivybridge</span><span class="p">,</span> <span class="n">atom</span><span class="p">,</span> <span class="n">sandybridge</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">multi_cpu</span><span class="p">(</span><span class="kt">void</span><span class="p">){}</span>
+</pre></div>
+</div>
+<p>Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn’t defined in the program will result in a
+linking failure.</p>
+<p>It is also possible to specify a CPU name of <code class="docutils literal notranslate"><span class="pre">generic</span></code> which will be resolved
+if the executing processor doesn’t satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn’t satisfy
+any option of a multiversioned function is undefined.</p>
+</div>
+<div class="section" id="diagnose-if">
+<h3><a class="toc-backref" href="#id205">diagnose_if</a><a class="headerlink" href="#diagnose-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id37">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id37" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">must_abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">val</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// warning: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val2</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// error: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val3</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">val4</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span> <span class="c1">// Because run-time checks are not emitted for</span>
+                          <span class="c1">// diagnose_if attributes, this executes without</span>
+                          <span class="c1">// issue.</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> is closely related to <code class="docutils literal notranslate"><span class="pre">enable_if</span></code>, with a few key differences:</p>
+<ul class="simple">
+<li>Overload resolution is not aware of <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> attributes: they’re
+considered only after we select the best candidate from a given candidate set.</li>
+<li>Function declarations that differ only in their <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> attributes are
+considered to be redeclarations of the same function (not overloads).</li>
+<li>If the condition provided to <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> cannot be evaluated, no
+diagnostic will be emitted.</li>
+</ul>
+<p>Otherwise, <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> is essentially the logical negation of <code class="docutils literal notranslate"><span class="pre">enable_if</span></code>.</p>
+<p>As a result of bullet number two, <code class="docutils literal notranslate"><span class="pre">diagnose_if</span></code> attributes will stack on the
+same function. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag1"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag2"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">bar</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span> <span class="c1">// warning: diag1</span>
+                 <span class="c1">// warning: diag2</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fooptr</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span> <span class="c1">// warning: diag1</span>
+                           <span class="c1">// warning: diag2</span>
+
+<span class="n">constexpr</span> <span class="kt">int</span> <span class="nf">supportsAPILevel</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">N</span> <span class="o"><</span> <span class="mi">5</span><span class="p">;</span> <span class="p">}</span>
+<span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">supportsAPILevel</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span>
+                             <span class="s">"Upgrade to API level 10 to use baz"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">a</span><span class="p">,</span> <span class="s">"0 is not recommended."</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">bazptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="n">baz</span><span class="p">;</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+<span class="kt">int</span> <span class="n">v</span> <span class="o">=</span> <span class="n">baz</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+</pre></div>
+</div>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_attribute(diagnose_if)</span></code>.</p>
+</div>
+<div class="section" id="disable-tail-calls">
+<h3><a class="toc-backref" href="#id206">disable_tail_calls</a><a class="headerlink" href="#disable-tail-calls" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id38">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id38" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">disable_tail_calls</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::disable_tail_calls</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::disable_tail_calls</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">disable_tail_calls</span></code> attribute instructs the backend to not perform tail call optimization inside the marked function.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">disable_tail_calls</span><span class="p">))</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">callee</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// This call is not tail-call optimized.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <code class="docutils literal notranslate"><span class="pre">disable_tail_calls</span></code> is legal.</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">disable_tail_calls</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is not tail-call optimized.</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="k">override</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is tail-call optimized.</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="enable-if">
+<h3><a class="toc-backref" href="#id207">enable_if</a><a class="headerlink" href="#enable-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id39">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id39" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">enable_if</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some features of this attribute are experimental. The meaning of
+multiple enable_if attributes on a single declaration is subject to change in
+a future version of clang. Also, the ABI is not standardized and the name
+mangling may change in future versions. To avoid that, use asm labels.</p>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">enable_if</span></code> attribute can be placed on function declarations to control
+which overload is selected based on the values of the function’s arguments.
+When combined with the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute, this feature is also
+available in C.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">c</span> <span class="o"><=</span> <span class="o">-</span><span class="mi">1</span> <span class="o">||</span> <span class="n">c</span> <span class="o">></span> <span class="mi">255</span><span class="p">,</span> <span class="s">"chosen when 'c' is out of range"</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">unavailable</span><span class="p">(</span><span class="s">"'c' must have the value of an unsigned char or EOF"</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">char</span> <span class="n">c</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">);</span>  <span class="c1">// results in a compile-time error.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.</p>
+<p>The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.</p>
+<p>Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">always_inline</span><span class="p">))</span>
+<span class="k">static</span> <span class="kr">inline</span> <span class="kt">size_t</span> <span class="n">strnlen</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">maxlen</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="o">-</span><span class="mi">1</span><span class="p">))),</span>
+                           <span class="s">"chosen when the buffer size is known but 'maxlen' is not"</span><span class="p">)))</span>
+<span class="p">{</span>
+  <span class="k">return</span> <span class="n">strnlen_chk</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">,</span> <span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #2</span>
+
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">j</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">)));</span>  <span class="c1">// #2</span>
+</pre></div>
+</div>
+<p>In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_attribute(enable_if)</span></code>.</p>
+<p>Note that functions with one or more <code class="docutils literal notranslate"><span class="pre">enable_if</span></code> attributes may not have
+their address taken, unless all of the conditions specified by said
+<code class="docutils literal notranslate"><span class="pre">enable_if</span></code> are constants that evaluate to <code class="docutils literal notranslate"><span class="pre">true</span></code>. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="kt">int</span> <span class="n">TrueConstant</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="k">const</span> <span class="kt">int</span> <span class="n">FalseConstant</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">a</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">h</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">i</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">TrueConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">j</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">FalseConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">fn</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">ptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">);</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">f</span><span class="p">;</span> <span class="c1">// error: 'a > 0' is not always true</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">g</span><span class="p">;</span> <span class="c1">// error: 'a == 0 || a != 0' is not a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">h</span><span class="p">;</span> <span class="c1">// OK: 1 is a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">i</span><span class="p">;</span> <span class="c1">// OK: 'TrueConstant' is a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">j</span><span class="p">;</span> <span class="c1">// error: 'FalseConstant' is a constant, but not truthy</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Because <code class="docutils literal notranslate"><span class="pre">enable_if</span></code> evaluation happens during overload resolution,
+<code class="docutils literal notranslate"><span class="pre">enable_if</span></code> may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for <code class="docutils literal notranslate"><span class="pre">foo</span></code> in <code class="docutils literal notranslate"><span class="pre">bar</span></code>, but not in <code class="docutils literal notranslate"><span class="pre">baz</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">double</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o"><=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">I</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">I</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">baz</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span><span class="o">::</span><span class="n">number</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">struct</span> <span class="n">WithNumber</span> <span class="p">{</span> <span class="k">constexpr</span> <span class="k">static</span> <span class="kt">int</span> <span class="n">number</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="p">};</span>
+<span class="kt">void</span> <span class="nf">callThem</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">bar</span><span class="o"><</span><span class="k">sizeof</span><span class="p">(</span><span class="n">WithNumber</span><span class="p">)</span><span class="o">></span><span class="p">();</span>
+  <span class="n">baz</span><span class="o"><</span><span class="n">WithNumber</span><span class="o">></span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is because, in <code class="docutils literal notranslate"><span class="pre">bar</span></code>, <code class="docutils literal notranslate"><span class="pre">foo</span></code> is resolved prior to template
+instantiation, so the value for <code class="docutils literal notranslate"><span class="pre">I</span></code> isn’t known (thus, both <code class="docutils literal notranslate"><span class="pre">enable_if</span></code>
+conditions for <code class="docutils literal notranslate"><span class="pre">foo</span></code> fail). However, in <code class="docutils literal notranslate"><span class="pre">baz</span></code>, <code class="docutils literal notranslate"><span class="pre">foo</span></code> is resolved during
+template instantiation, so the value for <code class="docutils literal notranslate"><span class="pre">T::number</span></code> is known.</p>
+</div>
+<div class="section" id="exclude-from-explicit-instantiation">
+<h3><a class="toc-backref" href="#id208">exclude_from_explicit_instantiation</a><a class="headerlink" href="#exclude-from-explicit-instantiation" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id40">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id40" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">exclude_from_explicit_instantiation</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::exclude_from_explicit_instantiation</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::exclude_from_explicit_instantiation</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">exclude_from_explicit_instantiation</span></code> attribute opts-out a member of a
+class template from being part of explicit template instantiations of that
+class template. This means that an explicit instantiation will not instantiate
+members of the class template marked with the attribute, but also that code
+where an extern template declaration of the enclosing class template is visible
+will not take for granted that an external instantiation of the class template
+would provide those members (which would otherwise be a link error, since the
+explicit instantiation won’t provide those members). For example, let’s say we
+don’t want the <code class="docutils literal notranslate"><span class="pre">data()</span></code> method to be part of libc++’s ABI. To make sure it
+is not exported from the dylib, we give it hidden visibility:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// in <string></span>
+<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">basic_string</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">__visibility__</span><span class="p">(</span><span class="s">"hidden"</span><span class="p">)))</span>
+  <span class="k">const</span> <span class="n">value_type</span><span class="o">*</span> <span class="n">data</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="k">class</span> <span class="nc">basic_string</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Since an explicit template instantiation declaration for <code class="docutils literal notranslate"><span class="pre">basic_string<char></span></code>
+is provided, the compiler is free to assume that <code class="docutils literal notranslate"><span class="pre">basic_string<char>::data()</span></code>
+will be provided by another translation unit, and it is free to produce an
+external call to this function. However, since <code class="docutils literal notranslate"><span class="pre">data()</span></code> has hidden visibility
+and the explicit template instantiation is provided in a shared library (as
+opposed to simply another translation unit), <code class="docutils literal notranslate"><span class="pre">basic_string<char>::data()</span></code>
+won’t be found and a link error will ensue. This happens because the compiler
+assumes that <code class="docutils literal notranslate"><span class="pre">basic_string<char>::data()</span></code> is part of the explicit template
+instantiation declaration, when it really isn’t. To tell the compiler that
+<code class="docutils literal notranslate"><span class="pre">data()</span></code> is not part of the explicit template instantiation declaration, the
+<code class="docutils literal notranslate"><span class="pre">exclude_from_explicit_instantiation</span></code> attribute can be used:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// in <string></span>
+<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">basic_string</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">__visibility__</span><span class="p">(</span><span class="s">"hidden"</span><span class="p">)))</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">exclude_from_explicit_instantiation</span><span class="p">))</span>
+  <span class="k">const</span> <span class="n">value_type</span><span class="o">*</span> <span class="n">data</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="k">class</span> <span class="nc">basic_string</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Now, the compiler won’t assume that <code class="docutils literal notranslate"><span class="pre">basic_string<char>::data()</span></code> is provided
+externally despite there being an explicit template instantiation declaration:
+the compiler will implicitly instantiate <code class="docutils literal notranslate"><span class="pre">basic_string<char>::data()</span></code> in the
+TUs where it is used.</p>
+<p>This attribute can be used on static and non-static member functions of class
+templates, static data members of class templates and member classes of class
+templates.</p>
+</div>
+<div class="section" id="flatten">
+<h3><a class="toc-backref" href="#id209">flatten</a><a class="headerlink" href="#flatten" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id41">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id41" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">flatten</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::flatten</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">flatten</span></code> attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the <code class="docutils literal notranslate"><span class="pre">noinline</span></code> attribute.</p>
+</div>
+<div class="section" id="force-align-arg-pointer">
+<h3><a class="toc-backref" href="#id210">force_align_arg_pointer</a><a class="headerlink" href="#force-align-arg-pointer" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id42">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id42" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">force_align_arg_pointer</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::force_align_arg_pointer</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use this attribute to force stack alignment.</p>
+<p>Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like ‘movaps’) that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.</p>
+<p>Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, ‘force_align_arg_pointer’ is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span> <span class="p">((</span><span class="n">force_align_arg_pointer</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">()</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="format">
+<h3><a class="toc-backref" href="#id211">format</a><a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id43">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id43" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">format</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::format</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">format</span></code> attribute, which indicates that the function
+accepts a <code class="docutils literal notranslate"><span class="pre">printf</span></code> or <code class="docutils literal notranslate"><span class="pre">scanf</span></code>-like format string and corresponding
+arguments or a <code class="docutils literal notranslate"><span class="pre">va_list</span></code> that contains these arguments.</p>
+<p>Please see <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC documentation about format attribute</a> to find details
+about attribute syntax.</p>
+<p>Clang implements two kinds of checks with this attribute.</p>
+<ol class="arabic">
+<li><p class="first">Clang checks that the function with the <code class="docutils literal notranslate"><span class="pre">format</span></code> attribute is called with
+a format string that uses format specifiers that are allowed, and that
+arguments match the format string.  This is the <code class="docutils literal notranslate"><span class="pre">-Wformat</span></code> warning, it is
+on by default.</p>
+</li>
+<li><p class="first">Clang checks that the format string argument is a literal string.  This is
+the <code class="docutils literal notranslate"><span class="pre">-Wformat-nonliteral</span></code> warning, it is off by default.</p>
+<p>Clang implements this mostly the same way as GCC, but there is a difference
+for functions that accept a <code class="docutils literal notranslate"><span class="pre">va_list</span></code> argument (for example, <code class="docutils literal notranslate"><span class="pre">vprintf</span></code>).
+GCC does not emit <code class="docutils literal notranslate"><span class="pre">-Wformat-nonliteral</span></code> warning for calls to such
+functions.  Clang does not warn if the format string comes from a function
+parameter, where the function is annotated with a compatible attribute,
+otherwise it warns.  For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__scanf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+  <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+  <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+  <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning: format string is not a string literal</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case we warn because <code class="docutils literal notranslate"><span class="pre">s</span></code> contains a format string for a
+<code class="docutils literal notranslate"><span class="pre">scanf</span></code>-like function, but it is passed to a <code class="docutils literal notranslate"><span class="pre">printf</span></code>-like function.</p>
+<p>If the attribute is removed, clang still warns, because the format string is
+not a string literal.</p>
+<p>Another example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__printf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+  <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+  <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+  <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case Clang does not warn because the format string <code class="docutils literal notranslate"><span class="pre">s</span></code> and
+the corresponding arguments are annotated.  If the arguments are
+incorrect, the caller of <code class="docutils literal notranslate"><span class="pre">foo</span></code> will receive a warning.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="gnu-inline">
+<h3><a class="toc-backref" href="#id212">gnu_inline</a><a class="headerlink" href="#gnu-inline" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id44">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id44" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">gnu_inline</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::gnu_inline</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">gnu_inline</span></code> changes the meaning of <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">inline</span></code> to use GNU inline
+semantics, meaning:</p>
+<ul class="simple">
+<li>If any declaration that is declared <code class="docutils literal notranslate"><span class="pre">inline</span></code> is not declared <code class="docutils literal notranslate"><span class="pre">extern</span></code>,
+then the <code class="docutils literal notranslate"><span class="pre">inline</span></code> keyword is just a hint. In particular, an out-of-line
+definition is still emitted for a function with external linkage, even if all
+call sites are inlined, unlike in C99 and C++ inline semantics.</li>
+<li>If all declarations that are declared <code class="docutils literal notranslate"><span class="pre">inline</span></code> are also declared
+<code class="docutils literal notranslate"><span class="pre">extern</span></code>, then the function body is present only for inlining and no
+out-of-line version is emitted.</li>
+</ul>
+<p>Some important consequences: <code class="docutils literal notranslate"><span class="pre">static</span> <span class="pre">inline</span></code> emits an out-of-line
+version if needed, a plain <code class="docutils literal notranslate"><span class="pre">inline</span></code> definition emits an out-of-line version
+always, and an <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">inline</span></code> definition (in a header) followed by a
+(non-<code class="docutils literal notranslate"><span class="pre">extern</span></code>) <code class="docutils literal notranslate"><span class="pre">inline</span></code> declaration in a source file emits an out-of-line
+version of the function in that source file but provides the function body for
+inlining to all includers of the header.</p>
+<p>Either <code class="docutils literal notranslate"><span class="pre">__GNUC_GNU_INLINE__</span></code> (GNU inline semantics) or
+<code class="docutils literal notranslate"><span class="pre">__GNUC_STDC_INLINE__</span></code> (C99 semantics) will be defined (they are mutually
+exclusive). If <code class="docutils literal notranslate"><span class="pre">__GNUC_STDC_INLINE__</span></code> is defined, then the <code class="docutils literal notranslate"><span class="pre">gnu_inline</span></code>
+function attribute can be used to get GNU inline semantics on a per function
+basis. If <code class="docutils literal notranslate"><span class="pre">__GNUC_GNU_INLINE__</span></code> is defined, then the translation unit is
+already being compiled with GNU inline semantics as the implied default. It is
+unspecified which macro is defined in a C++ compilation.</p>
+<p>GNU inline semantics are the default behavior with <code class="docutils literal notranslate"><span class="pre">-std=gnu89</span></code>,
+<code class="docutils literal notranslate"><span class="pre">-std=c89</span></code>, <code class="docutils literal notranslate"><span class="pre">-std=c94</span></code>, or <code class="docutils literal notranslate"><span class="pre">-fgnu89-inline</span></code>.</p>
+</div>
+<div class="section" id="ifunc">
+<h3><a class="toc-backref" href="#id213">ifunc</a><a class="headerlink" href="#ifunc" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id45">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id45" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ifunc</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::ifunc</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((ifunc("resolver")))</span></code> is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.</p>
+<p>The symbol name of the resolver function is given in quotes.  A function with this name (after mangling) must be defined in the current translation unit; it may be <code class="docutils literal notranslate"><span class="pre">static</span></code>.  The resolver function should return a pointer.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">ifunc</span></code> attribute may only be used on a function declaration.  A function declaration with an <code class="docutils literal notranslate"><span class="pre">ifunc</span></code> attribute is considered to be a definition of the declared entity.  The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.</p>
+<p>Not all targets support this attribute. ELF target support depends on both the linker and runtime linker, and is available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc v2.11.1 and later, and FreeBSD 9.1 and later. Non-ELF targets currently do not support this attribute.</p>
+</div>
+<div class="section" id="import-module">
+<h3><a class="toc-backref" href="#id214">import_module</a><a class="headerlink" href="#import-module" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id46">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id46" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">import_module</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::import_module</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::import_module</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((import_module(<module_name>)))</span></code>
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.</p>
+<p>WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, module names for C/C++ symbols are assigned automatically by the
+linker. This attribute can be used to override the default behavior, and
+reuqest a specific module name be used instead.</p>
+</div>
+<div class="section" id="import-name">
+<h3><a class="toc-backref" href="#id215">import_name</a><a class="headerlink" href="#import-name" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id47">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id47" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">import_name</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::import_name</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::import_name</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((import_name(<name>)))</span></code>
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.</p>
+<p>WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, field names for C/C++ symbols are the same as their C/C++ symbol
+names. This attribute can be used to override the default behavior, and
+reuqest a specific field name be used instead.</p>
+</div>
+<div class="section" id="internal-linkage">
+<h3><a class="toc-backref" href="#id216">internal_linkage</a><a class="headerlink" href="#internal-linkage" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id48">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id48" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">internal_linkage</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::internal_linkage</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::internal_linkage</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">internal_linkage</span></code> attribute changes the linkage type of the declaration to internal.
+This is similar to C-style <code class="docutils literal notranslate"><span class="pre">static</span></code>, but can be used on classes and class methods. When applied to a class definition,
+this attribute affects all methods and static data members of that class.
+This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.</p>
+</div>
+<div class="section" id="interrupt-arm">
+<h3><a class="toc-backref" href="#id217">interrupt (ARM)</a><a class="headerlink" href="#interrupt-arm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id49">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id49" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">interrupt</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::interrupt</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((interrupt("TYPE")))</span></code> attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.</p>
+<p>The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: “IRQ”,
+“FIQ”, “SWI”, “ABORT”, “UNDEF”.</p>
+<p>The semantics are as follows:</p>
+<ul>
+<li><p class="first">If the function is AAPCS, Clang instructs the backend to realign the stack to
+8 bytes on entry. This is a general requirement of the AAPCS at public
+interfaces, but may not hold when an exception is taken. Doing this allows
+other AAPCS functions to be called.</p>
+</li>
+<li><p class="first">If the CPU is M-class this is all that needs to be done since the architecture
+itself is designed in such a way that functions obeying the normal AAPCS ABI
+constraints are valid exception handlers.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the prologue and epilogue are modified to save all
+non-banked registers that are used, so that upon return the user-mode state
+will not be corrupted. Note that to avoid unnecessary overhead, only
+general-purpose (integer) registers are saved in this way. If VFP operations
+are needed, that state must be saved manually.</p>
+<p>Specifically, interrupt kinds other than “FIQ” will save all core registers
+except “lr” and “sp”. “FIQ” interrupts will save r0-r7.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the return instruction is changed to one of the
+canonical sequences permitted by the architecture for exception return. Where
+possible the function itself will make the necessary “lr” adjustments so that
+the “preferred return address” is selected.</p>
+<p>Unfortunately the compiler is unable to make this guarantee for an “UNDEF”
+handler, where the offset from “lr” to the preferred return address depends on
+the execution state of the code which generated the exception. In this case
+a sequence equivalent to “movs pc, lr” will be used.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="interrupt-avr">
+<h3><a class="toc-backref" href="#id218">interrupt (AVR)</a><a class="headerlink" href="#interrupt-avr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id50">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id50" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">interrupt</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::interrupt</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((interrupt))</span></code> attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.</p>
+</div>
+<div class="section" id="interrupt-mips">
+<h3><a class="toc-backref" href="#id219">interrupt (MIPS)</a><a class="headerlink" href="#interrupt-mips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id51">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id51" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">interrupt</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::interrupt</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((interrupt("ARGUMENT")))</span></code> attribute on
+MIPS targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>By default, the compiler will produce a function prologue and epilogue suitable for
+an interrupt service routine that handles an External Interrupt Controller (eic)
+generated interrupt. This behaviour can be explicitly requested with the “eic”
+argument.</p>
+<p>Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form “vector=LEVEL” where LEVEL is one of the following values:
+“sw0”, “sw1”, “hw0”, “hw1”, “hw2”, “hw3”, “hw4”, “hw5”. The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.</p>
+<p>The semantics are as follows:</p>
+<ul class="simple">
+<li>The prologue is modified so that the Exception Program Counter (EPC) and
+Status coprocessor registers are saved to the stack. The interrupt mask is
+set so that the function can only be interrupted by a higher priority
+interrupt. The epilogue will restore the previous values of EPC and Status.</li>
+<li>The prologue and epilogue are modified to save and restore all non-kernel
+registers as necessary.</li>
+<li>The FPU is disabled in the prologue, as the floating pointer registers are not
+spilled to the stack.</li>
+<li>The function return sequence is changed to use an exception return instruction.</li>
+<li>The parameter sets the interrupt mask for the function corresponding to the
+interrupt level specified. If no mask is specified the interrupt mask
+defaults to “eic”.</li>
+</ul>
+</div>
+<div class="section" id="interrupt-riscv">
+<h3><a class="toc-backref" href="#id220">interrupt (RISCV)</a><a class="headerlink" href="#interrupt-riscv" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id52">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id52" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">interrupt</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::interrupt</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((interrupt))</span></code> attribute on RISCV
+targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be
+used directly as an interrupt service routine.</p>
+<p>Permissible values for this parameter are <code class="docutils literal notranslate"><span class="pre">user</span></code>, <code class="docutils literal notranslate"><span class="pre">supervisor</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">machine</span></code>. If there is no parameter, then it defaults to machine.</p>
+<p>Repeated interrupt attribute on the same declaration will cause a warning
+to be emitted. In case of repeated declarations, the last one prevails.</p>
+<p>Refer to:
+<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html">https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html</a>
+<a class="reference external" href="https://riscv.org/specifications/privileged-isa/">https://riscv.org/specifications/privileged-isa/</a>
+The RISC-V Instruction Set Manual Volume II: Privileged Architecture
+Version 1.10.</p>
+</div>
+<div class="section" id="kernel">
+<h3><a class="toc-backref" href="#id221">kernel</a><a class="headerlink" href="#kernel" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id53">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id53" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">kernel</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((kernel))</span></code> is used to mark a <code class="docutils literal notranslate"><span class="pre">kernel</span></code> function in
+RenderScript.</p>
+<p>In RenderScript, <code class="docutils literal notranslate"><span class="pre">kernel</span></code> functions are used to express data-parallel
+computations.  The RenderScript runtime efficiently parallelizes <code class="docutils literal notranslate"><span class="pre">kernel</span></code>
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the <a class="reference external" href="https://developer.android.com/guide/topics/renderscript/compute.html">RenderScript</a> documentation for more information.</p>
+</div>
+<div class="section" id="lifetimebound">
+<h3><a class="toc-backref" href="#id222">lifetimebound</a><a class="headerlink" href="#lifetimebound" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id54">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id54" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">lifetimebound</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::lifetimebound</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">lifetimebound</span></code> attribute indicates that a resource owned by
+a function parameter or implicit object parameter
+is retained by the return value of the annotated function
+(or, for a parameter of a constructor, in the value of the constructed object).
+It is only supported in C++.</p>
+<p>This attribute provides an experimental implementation of the facility
+described in the C++ committee paper [<a class="reference external" href="http://wg21.link/p0936r0](P0936R0">http://wg21.link/p0936r0](P0936R0</a>),
+and is subject to change as the design of the corresponding functionality
+changes.</p>
+</div>
+<div class="section" id="long-call-far">
+<h3><a class="toc-backref" href="#id223">long_call, far</a><a class="headerlink" href="#long-call-far" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id55">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id55" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">long_call</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">far</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::long_call</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::far</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((long_call))</span></code>, <code class="docutils literal notranslate"><span class="pre">__attribute__((far))</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((near))</span></code> attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The <code class="docutils literal notranslate"><span class="pre">near</span></code> attribute
+allows calls to the function to be made using the <code class="docutils literal notranslate"><span class="pre">jal</span></code> instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller.  The <code class="docutils literal notranslate"><span class="pre">long_call</span></code> and <code class="docutils literal notranslate"><span class="pre">far</span></code> attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.</p>
+<p>These attributes have no effect for position-independent code.</p>
+<p>These attributes take priority over command line switches such
+as <code class="docutils literal notranslate"><span class="pre">-mlong-calls</span></code> and <code class="docutils literal notranslate"><span class="pre">-mno-long-calls</span></code>.</p>
+</div>
+<div class="section" id="micromips">
+<h3><a class="toc-backref" href="#id224">micromips</a><a class="headerlink" href="#micromips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id56">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id56" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">micromips</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::micromips</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((micromips))</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__attribute__((nomicromips))</span></code> attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.</p>
+<p>These attributes override the <cite>-mmicromips</cite> and <cite>-mno-micromips</cite> options
+on the command line.</p>
+</div>
+<div class="section" id="mig-server-routine">
+<h3><a class="toc-backref" href="#id225">mig_server_routine</a><a class="headerlink" href="#mig-server-routine" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id57">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id57" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">mig_server_routine</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::mig_server_routine</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::mig_server_routine</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The Mach Interface Generator release-on-success convention dictates
+functions that follow it to only release arguments passed to them when they
+return “success” (a <code class="docutils literal notranslate"><span class="pre">kern_return_t</span></code> error code that indicates that
+no errors have occured). Otherwise the release is performed by the MIG client
+that called the function. The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((mig_server_routine))</span></code>
+is applied in order to specify which functions are expected to follow the
+convention. This allows the Static Analyzer to find bugs caused by violations of
+that convention. The attribute would normally appear on the forward declaration
+of the actual server routine in the MIG server header, but it may also be
+added to arbitrary functions that need to follow the same convention - for
+example, a user can add them to auxiliary functions called by the server routine
+that have their return value of type <code class="docutils literal notranslate"><span class="pre">kern_return_t</span></code> unconditionally returned
+from the routine. The attribute can be applied to C++ methods, and in this case
+it will be automatically applied to overrides if the method is virtual. The
+attribute can also be written using C++11 syntax: <code class="docutils literal notranslate"><span class="pre">[[mig::server_routine]]</span></code>.</p>
+</div>
+<div class="section" id="min-vector-width">
+<h3><a class="toc-backref" href="#id226">min_vector_width</a><a class="headerlink" href="#min-vector-width" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id58">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id58" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">min_vector_width</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::min_vector_width</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::min_vector_width</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((min_vector_width(width)))</span></code> attribute. This
+attribute may be attached to a function and informs the backend that this
+function desires vectors of at least this width to be generated. Target-specific
+maximum vector widths still apply. This means even if you ask for something
+larger than the target supports, you will only get what the target supports.
+This attribute is meant to be a hint to control target heuristics that may
+generate narrower vectors than what the target hardware supports.</p>
+<p>This is currently used by the X86 target to allow some CPUs that support 512-bit
+vectors to be limited to using 256-bit vectors to avoid frequency penalties.
+This is currently enabled with the <code class="docutils literal notranslate"><span class="pre">-prefer-vector-width=256</span></code> command line
+option. The <code class="docutils literal notranslate"><span class="pre">min_vector_width</span></code> attribute can be used to prevent the backend
+from trying to split vector operations to match the <code class="docutils literal notranslate"><span class="pre">prefer-vector-width</span></code>. All
+X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
+use of any of the X86-specific vector builtins will implicitly set this
+attribute on the calling function. The intent is that explicitly writing vector
+code using the X86 intrinsics will prevent <code class="docutils literal notranslate"><span class="pre">prefer-vector-width</span></code> from
+affecting the code.</p>
+</div>
+<div class="section" id="no-caller-saved-registers">
+<h3><a class="toc-backref" href="#id227">no_caller_saved_registers</a><a class="headerlink" href="#no-caller-saved-registers" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id59">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id59" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_caller_saved_registers</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::no_caller_saved_registers</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.</p>
+<p>The user can call functions specified with the ‘no_caller_saved_registers’
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.</p>
+<p>Note that ‘no_caller_saved_registers’ attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span> <span class="p">((</span><span class="n">no_caller_saved_registers</span><span class="p">,</span> <span class="n">fastcall</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">(</span><span class="kt">int</span> <span class="n">arg1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">arg2</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case parameters ‘arg1’ and ‘arg2’ will be passed in registers.
+In this case, on 32-bit x86 targets, the function ‘f’ will use ECX and EDX as
+register parameters. However, it will not assume any scratch registers and
+should save and restore any modified registers except for ECX and EDX.</p>
+</div></blockquote>
+</div>
+<div class="section" id="no-sanitize">
+<h3><a class="toc-backref" href="#id228">no_sanitize</a><a class="headerlink" href="#no-sanitize" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id60">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id60" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_sanitize</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_sanitize</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_sanitize</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Use the <code class="docutils literal notranslate"><span class="pre">no_sanitize</span></code> attribute on a function or a global variable
+declaration to specify that a particular instrumentation or set of
+instrumentations should not be applied. The attribute takes a list of
+string literals, which have the same meaning as values accepted by the
+<code class="docutils literal notranslate"><span class="pre">-fno-sanitize=</span></code> flag. For example,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("address",</span> <span class="pre">"thread")))</span></code> specifies that
+AddressSanitizer and ThreadSanitizer should not be applied to the
+function or variable.</p>
+<p>See <a class="reference internal" href="UsersManual.html#controlling-code-generation"><span class="std std-ref">Controlling Code Generation</span></a> for a
+full list of supported sanitizer flags.</p>
+</div>
+<div class="section" id="no-sanitize-address-no-address-safety-analysis">
+<h3><a class="toc-backref" href="#id229">no_sanitize_address, no_address_safety_analysis</a><a class="headerlink" href="#no-sanitize-address-no-address-safety-analysis" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id61">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id61" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-address-sanitizer">Use <code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize_address))</span></code> on a function or a global
+variable declaration to specify that address safety instrumentation
+(e.g. AddressSanitizer) should not be applied.</p>
+</div>
+<div class="section" id="no-sanitize-memory">
+<h3><a class="toc-backref" href="#id230">no_sanitize_memory</a><a class="headerlink" href="#no-sanitize-memory" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id62">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id62" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-memory-sanitizer">Use <code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize_memory))</span></code> on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.</p>
+</div>
+<div class="section" id="no-sanitize-thread">
+<h3><a class="toc-backref" href="#id231">no_sanitize_thread</a><a class="headerlink" href="#no-sanitize-thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id63">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id63" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::no_address_safety_analysis</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_address</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::no_sanitize_thread</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_sanitize_memory</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p id="langext-thread-sanitizer">Use <code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize_thread))</span></code> on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.</p>
+</div>
+<div class="section" id="no-speculative-load-hardening">
+<h3><a class="toc-backref" href="#id232">no_speculative_load_hardening</a><a class="headerlink" href="#no-speculative-load-hardening" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id64">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id64" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_speculative_load_hardening</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_speculative_load_hardening</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_speculative_load_hardening</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<dl class="docutils">
+<dt>This attribute can be applied to a function declaration in order to indicate</dt>
+<dd><p class="first">that <a class="reference external" href="https://llvm.org/docs/SpeculativeLoadHardening.html">Speculative Load Hardening</a>
+is <em>not</em> needed for the function body. This can also be applied to a method
+in Objective C. This attribute will take precedence over the command line flag in
+the case where <a class="reference external" href="https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening">-mspeculative-load-hardening</a> is specified.</p>
+<p>Warning: This attribute may not prevent Speculative Load Hardening from being
+enabled for a function which inlines a function that has the
+‘speculative_load_hardening’ attribute. This is intended to provide a
+maximally conservative model where the code that is marked with the
+‘speculative_load_hardening’ attribute will always (even when inlined)
+be hardened. A user of this attribute may want to mark functions called by
+a function they do not want to be hardened with the ‘noinline’ attribute.</p>
+<p>For example:</p>
+<div class="last highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">speculative_load_hardening</span><span class="p">))</span>
+<span class="kt">int</span> <span class="n">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="c1">// Note: bar() may still have speculative load hardening enabled if</span>
+<span class="c1">// foo() is inlined into bar(). Mark foo() with __attribute__((noinline))</span>
+<span class="c1">// to avoid this situation.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">no_speculative_load_hardening</span><span class="p">))</span>
+<span class="kt">int</span> <span class="n">bar</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">i</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+</div>
+<div class="section" id="no-split-stack">
+<h3><a class="toc-backref" href="#id233">no_split_stack</a><a class="headerlink" href="#no-split-stack" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id65">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id65" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_split_stack</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::no_split_stack</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">no_split_stack</span></code> attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if <code class="docutils literal notranslate"><span class="pre">-fsplit-stack</span></code>
+is not specified.</p>
+</div>
+<div class="section" id="no-stack-protector">
+<h3><a class="toc-backref" href="#id234">no_stack_protector</a><a class="headerlink" href="#no-stack-protector" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id66">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id66" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_stack_protector</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_stack_protector</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_stack_protector</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((no_stack_protector))</span></code> attribute which disables
+the stack protector on the specified function. This attribute is useful for
+selectively disabling the stack protector on some functions when building with
+<code class="docutils literal notranslate"><span class="pre">-fstack-protector</span></code> compiler option.</p>
+<p>For example, it disables the stack protector for the function <code class="docutils literal notranslate"><span class="pre">foo</span></code> but function
+<code class="docutils literal notranslate"><span class="pre">bar</span></code> will still be built with the stack protector with the <code class="docutils literal notranslate"><span class="pre">-fstack-protector</span></code>
+option.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">no_stack_protector</span><span class="p">))</span>
+<span class="n">foo</span> <span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">);</span> <span class="c1">// stack protection will be disabled for foo.</span>
+
+<span class="kt">int</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">int</span> <span class="n">y</span><span class="p">);</span> <span class="c1">// bar can be built with the stack protector.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="noalias">
+<h3><a class="toc-backref" href="#id235">noalias</a><a class="headerlink" href="#noalias" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id67">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id67" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">noalias</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">noalias</span></code> attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.</p>
+</div>
+<div class="section" id="nocf-check">
+<h3><a class="toc-backref" href="#id236">nocf_check</a><a class="headerlink" href="#nocf-check" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id68">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id68" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nocf_check</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::nocf_check</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Jump Oriented Programming attacks rely on tampering with addresses used by
+indirect call / jmp, e.g. redirect control-flow to non-programmer
+intended bytes in the binary.
+X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
+Enforcement Technology (CET). IBT instruments ENDBR instructions used to
+specify valid targets of indirect call / jmp.
+The <code class="docutils literal notranslate"><span class="pre">nocf_check</span></code> attribute has two roles:
+1. Appertains to a function - do not add ENDBR instruction at the beginning of
+the function.
+2. Appertains to a function pointer - do not track the target function of this
+pointer (by adding nocf_check prefix to the indirect-call instruction).</p>
+</div>
+<div class="section" id="nodiscard-warn-unused-result">
+<h3><a class="toc-backref" href="#id237">nodiscard, warn_unused_result</a><a class="headerlink" href="#nodiscard-warn-unused-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id69">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id69" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">warn_unused_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">nodiscard</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::warn_unused_result</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::warn_unused_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">nodiscard</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the ability to diagnose when the results of a function call
+expression are discarded under suspicious circumstances. A diagnostic is
+generated when a function or its return type is marked with <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code>
+(or <code class="docutils literal notranslate"><span class="pre">__attribute__((warn_unused_result))</span></code>) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+<cite>void</cite>.</p>
+</div>
+<div class="section" id="noduplicate">
+<h3><a class="toc-backref" href="#id238">noduplicate</a><a class="headerlink" href="#noduplicate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id70">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id70" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">noduplicate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noduplicate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noduplicate</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL “barrier” function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+“nodupfunc” in the code below avoids that:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">nodupfunc</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">noduplicate</span><span class="p">));</span>
+<span class="c1">// Setting it as a C++11 attribute is also valid</span>
+<span class="c1">// void nodupfunc() [[clang::noduplicate]];</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+<span class="kt">void</span> <span class="nf">bar</span><span class="p">();</span>
+
+<span class="n">nodupfunc</span><span class="p">();</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>gets possibly modified by some optimizations into code similar to this:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">nodupfunc</span><span class="p">();</span>
+  <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="n">nodupfunc</span><span class="p">();</span>
+  <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>where the call to “nodupfunc” is duplicated and sunk into the two branches
+of the condition.</p>
+</div>
+<div class="section" id="nomicromips">
+<h3><a class="toc-backref" href="#id239">nomicromips</a><a class="headerlink" href="#nomicromips" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id71">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id71" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nomicromips</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::nomicromips</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((micromips))</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__attribute__((nomicromips))</span></code> attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.</p>
+<p>These attributes override the <cite>-mmicromips</cite> and <cite>-mno-micromips</cite> options
+on the command line.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id240">noreturn</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id72">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id72" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">noreturn</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <code class="docutils literal notranslate"><span class="pre">[[noreturn]]</span></code> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <code class="docutils literal notranslate"><span class="pre">[[noreturn]]</span></code>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="not-tail-called">
+<h3><a class="toc-backref" href="#id241">not_tail_called</a><a class="headerlink" href="#not-tail-called" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id73">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id73" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">not_tail_called</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::not_tail_called</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::not_tail_called</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">not_tail_called</span></code> attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as <code class="docutils literal notranslate"><span class="pre">always_inline</span></code> cannot be marked as <code class="docutils literal notranslate"><span class="pre">not_tail_called</span></code>.</p>
+<p>For example, it prevents tail-call optimization in the following case:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">foo1</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// No tail-call optimization on direct calls.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>However, it doesn’t prevent tail-call optimization in this case:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo1</span><span class="p">;</span>
+
+  <span class="c1">// not_tail_called has no effect on an indirect call even if the call can be</span>
+  <span class="c1">// resolved at compile time.</span>
+  <span class="k">return</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <code class="docutils literal notranslate"><span class="pre">not_tail_called</span></code> is an error:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="c1">// not_tail_called on a virtual function is an error.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">();</span>
+
+  <span class="k">virtual</span> <span class="kt">int</span> <span class="nf">foo2</span><span class="p">();</span>
+
+  <span class="c1">// Non-virtual functions can be marked ``not_tail_called``.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo3</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+
+  <span class="c1">// not_tail_called on a virtual function is an error.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo2</span><span class="p">()</span> <span class="k">override</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="nothrow">
+<h3><a class="toc-backref" href="#id242">nothrow</a><a class="headerlink" href="#nothrow" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id74">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id74" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nothrow</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::nothrow</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">nothrow</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((nothrow))</span></code> and Microsoft style
+<code class="docutils literal notranslate"><span class="pre">__declspec(nothrow)</span></code> attribute as an equivalent of <cite>noexcept</cite> on function
+declarations. This attribute informs the compiler that the annotated function
+does not throw an exception. This prevents exception-unwinding. This attribute
+is particularly useful on functions in the C Standard Library that are
+guaranteed to not throw an exception.</p>
+</div>
+<div class="section" id="ns-consumed">
+<h3><a class="toc-backref" href="#id243">ns_consumed</a><a class="headerlink" href="#ns-consumed" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id75">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id75" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_consumed</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="ns-consumes-self">
+<h3><a class="toc-backref" href="#id244">ns_consumes_self</a><a class="headerlink" href="#ns-consumes-self" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id76">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id76" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ns_consumes_self</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_consumes_self</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_consumes_self</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="ns-returns-autoreleased">
+<h3><a class="toc-backref" href="#id245">ns_returns_autoreleased</a><a class="headerlink" href="#ns-returns-autoreleased" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id77">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id77" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ns_returns_autoreleased</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_autoreleased</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_autoreleased</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="ns-returns-not-retained">
+<h3><a class="toc-backref" href="#id246">ns_returns_not_retained</a><a class="headerlink" href="#ns-returns-not-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id78">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id78" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ns_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_not_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="ns-returns-retained">
+<h3><a class="toc-backref" href="#id247">ns_returns_retained</a><a class="headerlink" href="#ns-returns-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id79">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id79" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::ns_returns_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="objc-method-family">
+<h3><a class="toc-backref" href="#id248">objc_method_family</a><a class="headerlink" href="#objc-method-family" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id80">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id80" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_method_family</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_method_family</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_method_family</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the “method family”
+that a method belongs to.</p>
+<p><strong>Usage</strong>: <code class="docutils literal notranslate"><span class="pre">__attribute__((objc_method_family(X)))</span></code>, where <code class="docutils literal notranslate"><span class="pre">X</span></code> is one of
+<code class="docutils literal notranslate"><span class="pre">none</span></code>, <code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">copy</span></code>, <code class="docutils literal notranslate"><span class="pre">init</span></code>, <code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code>, or <code class="docutils literal notranslate"><span class="pre">new</span></code>.  This
+attribute can only be placed at the end of a method declaration:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="p">-</span> <span class="p">(</span><span class="bp">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">initMyStringValue</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_method_family</span><span class="p">(</span><span class="n">none</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (<code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code>,
+<code class="docutils literal notranslate"><span class="pre">ns_returns_not_retained</span></code>, etc).</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_attribute(objc_method_family)</span></code>.</p>
+</div>
+<div class="section" id="objc-requires-super">
+<h3><a class="toc-backref" href="#id249">objc_requires_super</a><a class="headerlink" href="#objc-requires-super" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id81">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id81" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_requires_super</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_requires_super</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_requires_super</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a “call to <code class="docutils literal notranslate"><span class="pre">super</span></code>” in the overriding
+method in the subclass.</p>
+<p><strong>Usage</strong>: <code class="docutils literal notranslate"><span class="pre">__attribute__((objc_requires_super))</span></code>.  This attribute can only
+be placed at the end of a method declaration:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_requires_super</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute can only be applied the method declarations within a class, and
+not a protocol.  Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+<code class="docutils literal notranslate"><span class="pre">-dealloc</span></code> where the call must appear at the end).  It checks only that it
+exists.</p>
+<p>Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro <code class="docutils literal notranslate"><span class="pre">NS_REQUIRES_SUPER</span></code> that provides syntactic sugar for this
+attribute:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">NS_REQUIRES_SUPER</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This macro is conditionally defined depending on the compiler’s support for
+this attribute.  If the compiler does not support the attribute the macro
+expands to nothing.</p>
+<p>Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super.  For example:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="nl">warning</span><span class="p">:</span> <span class="n">method</span> <span class="n">possibly</span> <span class="n">missing</span> <span class="n">a</span> <span class="p">[</span><span class="nb">super</span> <span class="n">AnnotMeth</span><span class="p">]</span> <span class="n">call</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">AnnotMeth</span><span class="p">{};</span>
+                   <span class="o">^</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="optnone">
+<h3><a class="toc-backref" href="#id250">optnone</a><a class="headerlink" href="#optnone" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id82">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id82" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">optnone</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::optnone</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::optnone</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">optnone</span></code> attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole.  This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization.  Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.</p>
+<p>This attribute is incompatible with the <code class="docutils literal notranslate"><span class="pre">always_inline</span></code> and <code class="docutils literal notranslate"><span class="pre">minsize</span></code>
+attributes.</p>
+</div>
+<div class="section" id="os-consumed">
+<h3><a class="toc-backref" href="#id251">os_consumed</a><a class="headerlink" href="#os-consumed" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id83">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id83" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_consumed</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_consumed</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="os-consumes-this">
+<h3><a class="toc-backref" href="#id252">os_consumes_this</a><a class="headerlink" href="#os-consumes-this" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id84">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id84" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_consumes_this</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_consumes_this</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_consumes_this</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="os-returns-not-retained">
+<h3><a class="toc-backref" href="#id253">os_returns_not_retained</a><a class="headerlink" href="#os-returns-not-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id85">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id85" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_not_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_not_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="os-returns-retained">
+<h3><a class="toc-backref" href="#id254">os_returns_retained</a><a class="headerlink" href="#os-returns-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id86">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id86" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="os-returns-retained-on-non-zero">
+<h3><a class="toc-backref" href="#id255">os_returns_retained_on_non_zero</a><a class="headerlink" href="#os-returns-retained-on-non-zero" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id87">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id87" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_returns_retained_on_non_zero</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained_on_non_zero</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained_on_non_zero</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="os-returns-retained-on-zero">
+<h3><a class="toc-backref" href="#id256">os_returns_retained_on_zero</a><a class="headerlink" href="#os-returns-retained-on-zero" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id88">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id88" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">os_returns_retained_on_zero</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained_on_zero</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::os_returns_retained_on_zero</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with “get” are assumed to return at
+<code class="docutils literal notranslate"><span class="pre">+0</span></code>).</p>
+<p>It can be overriden using a family of the following attributes.  In
+Objective-C, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code> applied to
+a function communicates that the object is returned at <code class="docutils literal notranslate"><span class="pre">+1</span></code>, and the caller
+is responsible for freeing it.
+Similiarly, the annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>
+specifies that the object is returned at <code class="docutils literal notranslate"><span class="pre">+0</span></code> and the ownership remains with
+the callee.
+The annotation <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> specifies that
+the Objective-C method call consumes the reference to <code class="docutils literal notranslate"><span class="pre">self</span></code>, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumed))</span></code>, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>In C programs using CoreFoundation, a similar set of attributes:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((cf_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((cf_consumed))</span></code>
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.</p>
+<p>Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code> and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumed))</span></code>,
+with the same respective semantics.
+Similar to <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((os_consumes_this))</span></code> specifies that the method call consumes
+the reference to “this” (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained))</span></code>
+or <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_not_retained))</span></code> which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_zero))</span></code>
+and <code class="docutils literal notranslate"><span class="pre">__attribute__((os_returns_retained_on_non_zero))</span></code> specify that
+an out parameter at <code class="docutils literal notranslate"><span class="pre">+1</span></code> is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.</p>
+<p>The family of attributes <code class="docutils literal notranslate"><span class="pre">X_returns_X_retained</span></code> can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes <code class="docutils literal notranslate"><span class="pre">X_consumed</span></code> can be added to parameters of methods, functions,
+and Objective-C methods.</p>
+</div>
+<div class="section" id="overloadable">
+<h3><a class="toc-backref" href="#id257">overloadable</a><a class="headerlink" href="#overloadable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id89">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id89" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">overloadable</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::overloadable</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::overloadable</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang provides support for C++ function overloading in C.  Function overloading
+in C is introduced using the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute.  For example, one
+might provide several overloaded versions of a <code class="docutils literal notranslate"><span class="pre">tgsin</span></code> function that invokes
+the appropriate standard function computing the sine of a value with <code class="docutils literal notranslate"><span class="pre">float</span></code>,
+<code class="docutils literal notranslate"><span class="pre">double</span></code>, or <code class="docutils literal notranslate"><span class="pre">long</span> <span class="pre">double</span></code> precision:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><math.h></span><span class="cp"></span>
+<span class="kt">float</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinf</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">long</span> <span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">long</span> <span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinl</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Given these declarations, one can call <code class="docutils literal notranslate"><span class="pre">tgsin</span></code> with a <code class="docutils literal notranslate"><span class="pre">float</span></code> value to
+receive a <code class="docutils literal notranslate"><span class="pre">float</span></code> result, with a <code class="docutils literal notranslate"><span class="pre">double</span></code> to receive a <code class="docutils literal notranslate"><span class="pre">double</span></code> result,
+etc.  Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:</p>
+<ul class="simple">
+<li>Conversion from <code class="docutils literal notranslate"><span class="pre">float</span></code> or <code class="docutils literal notranslate"><span class="pre">double</span></code> to <code class="docutils literal notranslate"><span class="pre">long</span> <span class="pre">double</span></code> 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 <code class="docutils literal notranslate"><span class="pre">T*</span></code> to a pointer of type <code class="docutils literal notranslate"><span class="pre">U*</span></code> is
+considered a pointer conversion (with conversion rank) if <code class="docutils literal notranslate"><span class="pre">T</span></code> and <code class="docutils literal notranslate"><span class="pre">U</span></code> are
+compatible types.</li>
+<li>A conversion from type <code class="docutils literal notranslate"><span class="pre">T</span></code> to a value of type <code class="docutils literal notranslate"><span class="pre">U</span></code> is permitted if <code class="docutils literal notranslate"><span class="pre">T</span></code>
+and <code class="docutils literal notranslate"><span class="pre">U</span></code> are compatible types.  This conversion is given “conversion” rank.</li>
+<li>If no viable candidates are otherwise available, we allow a conversion from a
+pointer of type <code class="docutils literal notranslate"><span class="pre">T*</span></code> to a pointer of type <code class="docutils literal notranslate"><span class="pre">U*</span></code>, where <code class="docutils literal notranslate"><span class="pre">T</span></code> and <code class="docutils literal notranslate"><span class="pre">U</span></code> are
+incompatible. This conversion is ranked below all other types of conversions.
+Please note: <code class="docutils literal notranslate"><span class="pre">U</span></code> lacking qualifiers that are present on <code class="docutils literal notranslate"><span class="pre">T</span></code> is sufficient
+for <code class="docutils literal notranslate"><span class="pre">T</span></code> and <code class="docutils literal notranslate"><span class="pre">U</span></code> to be incompatible.</li>
+</ul>
+<p>The declaration of <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> functions is restricted to function
+declarations and definitions.  If a function is marked with the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code>
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute.  In addition, redeclarations of a function with
+the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute must have the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute, and
+redeclarations of a function without the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute must <em>not</em>
+have the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute. e.g.,</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">float</span> <span class="nf">f</span><span class="p">(</span><span class="kt">float</span><span class="p">);</span> <span class="c1">// error: declaration of "f" must have the "overloadable" attribute</span>
+<span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span> <span class="c1">// error: redeclaration of "f" must have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="c1">// error: redeclaration of "g" must also have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="nf">h</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">h</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: declaration of "h" must not</span>
+                                          <span class="c1">// have the "overloadable" attribute</span>
+</pre></div>
+</div>
+<p>Functions marked <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> must have prototypes.  Therefore, the
+following code is ill-formed:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">h</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: h does not have a prototype</span>
+</pre></div>
+</div>
+<p>However, <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> 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 <code class="docutils literal notranslate"><span class="pre">unavailable</span></code> attribute:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">honeypot</span><span class="p">(...)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">,</span> <span class="n">unavailable</span><span class="p">));</span> <span class="c1">// calling me is an error</span>
+</pre></div>
+</div>
+<p>Functions declared with the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute have their names mangled
+according to the same rules as C++ function names.  For example, the three
+<code class="docutils literal notranslate"><span class="pre">tgsin</span></code> functions in our motivating example get the mangled names
+<code class="docutils literal notranslate"><span class="pre">_Z5tgsinf</span></code>, <code class="docutils literal notranslate"><span class="pre">_Z5tgsind</span></code>, and <code class="docutils literal notranslate"><span class="pre">_Z5tgsine</span></code>, respectively.  There are two
+caveats to this use of name mangling:</p>
+<ul class="simple">
+<li>Future versions of Clang may change the name mangling of functions overloaded
+in C, so you should not depend on an specific mangling.  To be completely
+safe, we strongly urge the use of <code class="docutils literal notranslate"><span class="pre">static</span> <span class="pre">inline</span></code> with <code class="docutils literal notranslate"><span class="pre">overloadable</span></code>
+functions.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute has almost no meaning when used in C++,
+because names will already be mangled and functions are already overloadable.
+However, when an <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> function occurs within an <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">"C"</span></code>
+linkage specification, it’s name <em>will</em> be mangled in the same way as it
+would in C.</li>
+</ul>
+<p>For the purpose of backwards compatibility, at most one function with the same
+name as other <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> functions may omit the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code>
+attribute. In this case, the function without the <code class="docutils literal notranslate"><span class="pre">overloadable</span></code> attribute
+will not have its name mangled.</p>
+<p>For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Notes with mangled names assume Itanium mangling.</span>
+<span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">f</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> <span class="c1">// Emits a call to f (not _Z1fi, as it would with an overload that</span>
+        <span class="c1">// was marked with overloadable).</span>
+  <span class="n">f</span><span class="p">(</span><span class="mf">1.0</span><span class="p">);</span> <span class="c1">// Emits a call to _Z1fd.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Support for unmarked overloads is not present in some versions of clang. You may
+query for it using <code class="docutils literal notranslate"><span class="pre">__has_extension(overloadable_unmarked)</span></code>.</p>
+<p>Query for this attribute with <code class="docutils literal notranslate"><span class="pre">__has_attribute(overloadable)</span></code>.</p>
+</div>
+<div class="section" id="reinitializes">
+<h3><a class="toc-backref" href="#id258">reinitializes</a><a class="headerlink" href="#reinitializes" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id90">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id90" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">reinitializes</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::reinitializes</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">reinitializes</span></code> attribute can be applied to a non-static, non-const C++
+member function to indicate that this member function reinitializes the entire
+object to a known state, independent of the previous state of the object.</p>
+<p>This attribute can be interpreted by static analyzers that warn about uses of an
+object that has been left in an indeterminate state by a move operation. If a
+member function marked with the <code class="docutils literal notranslate"><span class="pre">reinitializes</span></code> attribute is called on a
+moved-from object, the analyzer can conclude that the object is no longer in an
+indeterminate state.</p>
+<p>A typical example where this attribute would be used is on functions that clear
+a container class:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">Container</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+  <span class="p">...</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">reinitializes</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">Clear</span><span class="p">();</span>
+  <span class="p">...</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="release-capability-release-shared-capability">
+<h3><a class="toc-backref" href="#id259">release_capability, release_shared_capability</a><a class="headerlink" href="#release-capability-release-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id91">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id91" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">release_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">release_shared_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">release_generic_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">unlock_function</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::release_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::release_shared_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::release_generic_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::unlock_function</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as releasing a capability.</p>
+</div>
+<div class="section" id="short-call-near">
+<h3><a class="toc-backref" href="#id260">short_call, near</a><a class="headerlink" href="#short-call-near" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id92">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id92" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">short_call</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">near</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::short_call</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::near</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((long_call))</span></code>, <code class="docutils literal notranslate"><span class="pre">__attribute__((far))</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__attribute__((short__call))</span></code>, and <code class="docutils literal notranslate"><span class="pre">__attribute__((near))</span></code> attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The <code class="docutils literal notranslate"><span class="pre">short_call</span></code> and <code class="docutils literal notranslate"><span class="pre">near</span></code> attributes are synonyms and
+allow calls to the function to be made using the <code class="docutils literal notranslate"><span class="pre">jal</span></code> instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller.  The <code class="docutils literal notranslate"><span class="pre">long_call</span></code> and <code class="docutils literal notranslate"><span class="pre">far</span></code> attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.</p>
+<p>These attributes have no effect for position-independent code.</p>
+<p>These attributes take priority over command line switches such
+as <code class="docutils literal notranslate"><span class="pre">-mlong-calls</span></code> and <code class="docutils literal notranslate"><span class="pre">-mno-long-calls</span></code>.</p>
+</div>
+<div class="section" id="signal">
+<h3><a class="toc-backref" href="#id261">signal</a><a class="headerlink" href="#signal" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id93">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id93" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">signal</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::signal</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((signal))</span></code> attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>Interrupt handler functions defined with the signal attribute do not re-enable interrupts.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id262">speculative_load_hardening</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id94">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id94" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">speculative_load_hardening</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::speculative_load_hardening</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::speculative_load_hardening</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<dl class="docutils">
+<dt>This attribute can be applied to a function declaration in order to indicate</dt>
+<dd><p class="first">that <a class="reference external" href="https://llvm.org/docs/SpeculativeLoadHardening.html">Speculative Load Hardening</a>
+should be enabled for the function body. This can also be applied to a method
+in Objective C. This attribute will take precedence over the command line flag in
+the case where <a class="reference external" href="https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening">-mno-speculative-load-hardening</a> is specified.</p>
+<p>Speculative Load Hardening is a best-effort mitigation against
+information leak attacks that make use of control flow
+miss-speculation - specifically miss-speculation of whether a branch
+is taken or not. Typically vulnerabilities enabling such attacks are
+classified as “Spectre variant #1”. Notably, this does not attempt to
+mitigate against miss-speculation of branch target, classified as
+“Spectre variant #2” vulnerabilities.</p>
+<p class="last">When inlining, the attribute is sticky. Inlining a function that
+carries this attribute will cause the caller to gain the
+attribute. This is intended to provide a maximally conservative model
+where the code in a function annotated with this attribute will always
+(even after inlining) end up hardened.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="target">
+<h3><a class="toc-backref" href="#id263">target</a><a class="headerlink" href="#target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id95">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id95" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">target</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::target</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <code class="docutils literal notranslate"><span class="pre">__attribute__((target("OPTIONS")))</span></code> attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.</p>
+<p>The current set of options correspond to the existing “subtarget features” for
+the target with or without a “-mno-” in front corresponding to the absence
+of the feature, as well as <code class="docutils literal notranslate"><span class="pre">arch="CPU"</span></code> which will change the default “CPU”
+for the function.</p>
+<p>Example “subtarget features” from the x86 backend include: “mmx”, “sse”, “sse4.2”,
+“avx”, “xop” and largely correspond to the machine specific options handled by
+the front end.</p>
+<p>Additionally, this attribute supports function multiversioning for ELF based
+x86/x86-64 targets, which can be used to create multiple implementations of the
+same function that will be resolved at runtime based on the priority of their
+<code class="docutils literal notranslate"><span class="pre">target</span></code> attribute strings. A function is considered a multiversioned function
+if either two declarations of the function have different <code class="docutils literal notranslate"><span class="pre">target</span></code> attribute
+strings, or if it has a <code class="docutils literal notranslate"><span class="pre">target</span></code> attribute string of <code class="docutils literal notranslate"><span class="pre">default</span></code>.  For
+example:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">target</span><span class="p">(</span><span class="s">"arch=atom"</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span> <span class="c1">// will be called on 'atom' processors.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">target</span><span class="p">(</span><span class="s">"default"</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span> <span class="c1">// will be called on any other processors.</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>All multiversioned functions must contain a <code class="docutils literal notranslate"><span class="pre">default</span></code> (fallback)
+implementation, otherwise usages of the function are considered invalid.
+Additionally, a function may not become multiversioned after its first use.</p>
+</div>
+<div class="section" id="try-acquire-capability-try-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id264">try_acquire_capability, try_acquire_shared_capability</a><a class="headerlink" href="#try-acquire-capability-try-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id96">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id96" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">try_acquire_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">try_acquire_shared_capability</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::try_acquire_capability</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::try_acquire_shared_capability</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).</p>
+</div>
+<div class="section" id="xray-always-instrument-xray-never-instrument-xray-log-args">
+<h3><a class="toc-backref" href="#id265">xray_always_instrument, xray_never_instrument, xray_log_args</a><a class="headerlink" href="#xray-always-instrument-xray-never-instrument-xray-log-args" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id97">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id97" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">xray_always_instrument</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">xray_never_instrument</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::xray_always_instrument</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::xray_never_instrument</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::xray_always_instrument</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::xray_never_instrument</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((xray_always_instrument))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_always_instrument]]</span></code> is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.</p>
+<p>Conversely, <code class="docutils literal notranslate"><span class="pre">__attribute__((xray_never_instrument))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_never_instrument]]</span></code> will inhibit the insertion of these instrumentation points.</p>
+<p>If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.</p>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((xray_log_args(N)))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_log_args(N)]]</span></code> is used to preserve N function arguments for the logging function.  Currently, only N==1 is supported.</p>
+</div>
+<div class="section" id="id4">
+<h3><a class="toc-backref" href="#id266">xray_always_instrument, xray_never_instrument, xray_log_args</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id98">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id98" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">xray_log_args</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::xray_log_args</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::xray_log_args</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((xray_always_instrument))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_always_instrument]]</span></code> is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.</p>
+<p>Conversely, <code class="docutils literal notranslate"><span class="pre">__attribute__((xray_never_instrument))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_never_instrument]]</span></code> will inhibit the insertion of these instrumentation points.</p>
+<p>If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.</p>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((xray_log_args(N)))</span></code> or <code class="docutils literal notranslate"><span class="pre">[[clang::xray_log_args(N)]]</span></code> is used to preserve N function arguments for the logging function.  Currently, only N==1 is supported.</p>
+</div>
+</div>
+<div class="section" id="variable-attributes">
+<h2><a class="toc-backref" href="#id267">Variable Attributes</a><a class="headerlink" href="#variable-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="always-destroy">
+<h3><a class="toc-backref" href="#id268">always_destroy</a><a class="headerlink" href="#always-destroy" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id99">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id99" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">always_destroy</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::always_destroy</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">always_destroy</span></code> attribute specifies that a variable with static or thread
+storage duration should have its exit-time destructor run. This attribute is the
+default unless clang was invoked with -fno-c++-static-destructors.</p>
+</div>
+<div class="section" id="dllexport">
+<h3><a class="toc-backref" href="#id269">dllexport</a><a class="headerlink" href="#dllexport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id100">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id100" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">dllexport</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::dllexport</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">dllexport</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec(dllexport)</span></code> attribute declares a variable, function, or
+Objective-C interface to be exported from the module.  It is available under the
+<code class="docutils literal notranslate"><span class="pre">-fdeclspec</span></code> flag for compatibility with various compilers.  The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use.  See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllexport</a> documentation on MSDN for more
+information.</p>
+</div>
+<div class="section" id="dllimport">
+<h3><a class="toc-backref" href="#id270">dllimport</a><a class="headerlink" href="#dllimport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id101">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id101" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">dllimport</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::dllimport</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">dllimport</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec(dllimport)</span></code> attribute declares a variable, function, or
+Objective-C interface to be imported from an external module.  It is available
+under the <code class="docutils literal notranslate"><span class="pre">-fdeclspec</span></code> flag for compatibility with various compilers.  The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules.  See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllimport</a> documentation on MSDN
+for more information.</p>
+</div>
+<div class="section" id="init-seg">
+<h3><a class="toc-backref" href="#id271">init_seg</a><a class="headerlink" href="#init-seg" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id102">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id102" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">init_seg</span></code></td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The attribute applied by <code class="docutils literal notranslate"><span class="pre">pragma</span> <span class="pre">init_seg()</span></code> controls the section into
+which global initialization function pointers are emitted.  It is only
+available with <code class="docutils literal notranslate"><span class="pre">-fms-extensions</span></code>.  Typically, this function pointer is
+emitted into <code class="docutils literal notranslate"><span class="pre">.CRT$XCU</span></code> on Windows.  The user can change the order of
+initialization by using a different section name with the same
+<code class="docutils literal notranslate"><span class="pre">.CRT$XC</span></code> prefix and a suffix that sorts lexicographically before or
+after the standard <code class="docutils literal notranslate"><span class="pre">.CRT$XCU</span></code> sections.  See the <a class="reference external" href="http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx">init_seg</a>
+documentation on MSDN for more information.</p>
+</div>
+<div class="section" id="maybe-unused-unused">
+<h3><a class="toc-backref" href="#id272">maybe_unused, unused</a><a class="headerlink" href="#maybe-unused-unused" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id103">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id103" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">unused</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">maybe_unused</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">gnu::unused</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">maybe_unused</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When passing the <code class="docutils literal notranslate"><span class="pre">-Wunused</span></code> flag to Clang, entities that are unused by the
+program may be diagnosed. The <code class="docutils literal notranslate"><span class="pre">[[maybe_unused]]</span></code> (or
+<code class="docutils literal notranslate"><span class="pre">__attribute__((unused))</span></code>) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an <code class="docutils literal notranslate"><span class="pre">assert()</span></code> statement, which makes the local variable
+unused when <code class="docutils literal notranslate"><span class="pre">NDEBUG</span></code> is defined.</p>
+<p>The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.</p>
+</div>
+<div class="section" id="no-destroy">
+<h3><a class="toc-backref" href="#id273">no_destroy</a><a class="headerlink" href="#no-destroy" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id104">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id104" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">no_destroy</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::no_destroy</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">no_destroy</span></code> attribute specifies that a variable with static or thread
+storage duration shouldn’t have its exit-time destructor run. Annotating every
+static and thread duration variable with this attribute is equivalent to
+invoking clang with -fno-c++-static-destructors.</p>
+<p>If a variable is declared with this attribute, clang doesn’t access check or
+generate the type’s destructor. If you have a type that you only want to be
+annotated with <code class="docutils literal notranslate"><span class="pre">no_destroy</span></code>, you can therefore declare the destructor private:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">only_no_destroy</span> <span class="p">{</span>
+  <span class="n">only_no_destroy</span><span class="p">();</span>
+<span class="k">private</span><span class="o">:</span>
+  <span class="o">~</span><span class="n">only_no_destroy</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">no_destroy</span><span class="p">]]</span> <span class="n">only_no_destroy</span> <span class="n">global</span><span class="p">;</span> <span class="c1">// fine!</span>
+</pre></div>
+</div>
+<p>Note that destructors are still required for subobjects of aggregates annotated
+with this attribute. This is because previously constructed subobjects need to
+be destroyed if an exception gets thrown before the initialization of the
+complete object is complete. For instance:</p>
+<p>Here, if the construction of <cite>array[9]</cite> fails with an exception, <cite>array[0..8]</cite>
+will be destroyed, so the element’s destructor needs to be accessible.</p>
+</div>
+<div class="section" id="nodebug">
+<h3><a class="toc-backref" href="#id274">nodebug</a><a class="headerlink" href="#nodebug" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id105">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id105" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nodebug</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::nodebug</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">nodebug</span></code> attribute allows you to suppress debugging information for a
+function or method, or for a variable that is not a parameter or a non-static
+data member.</p>
+</div>
+<div class="section" id="noescape">
+<h3><a class="toc-backref" href="#id275">noescape</a><a class="headerlink" href="#noescape" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id106">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id106" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">noescape</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noescape</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noescape</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p><code class="docutils literal notranslate"><span class="pre">noescape</span></code> placed on a function parameter of a pointer type is used to inform
+the compiler that the pointer cannot escape: that is, no reference to the object
+the pointer points to that is derived from the parameter value will survive
+after the function returns. Users are responsible for making sure parameters
+annotated with <code class="docutils literal notranslate"><span class="pre">noescape</span></code> do not actuallly escape.</p>
+<p>For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="o">*</span><span class="n">gp</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">nonescapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">*</span><span class="n">p</span> <span class="o">+=</span> <span class="mi">100</span><span class="p">;</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">escapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">gp</span> <span class="o">=</span> <span class="n">p</span><span class="p">;</span> <span class="c1">// Not OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Additionally, when the parameter is a <cite>block pointer
+<https://clang.llvm.org/docs/BlockLanguageSpec.html></cite>, the same restriction
+applies to copies of the block. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">^</span><span class="n">BlockTy</span><span class="p">)();</span>
+<span class="n">BlockTy</span> <span class="n">g0</span><span class="p">,</span> <span class="n">g1</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">nonescapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="n">BlockTy</span> <span class="n">block</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">block</span><span class="p">();</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">escapingFunc</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">noescape</span><span class="p">))</span> <span class="n">BlockTy</span> <span class="n">block</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">g0</span> <span class="o">=</span> <span class="n">block</span><span class="p">;</span> <span class="c1">// Not OK.</span>
+  <span class="n">g1</span> <span class="o">=</span> <span class="n">Block_copy</span><span class="p">(</span><span class="n">block</span><span class="p">);</span> <span class="c1">// Not OK either.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nosvm">
+<h3><a class="toc-backref" href="#id276">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id107">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id107" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nosvm</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>OpenCL 2.0 supports the optional <code class="docutils literal notranslate"><span class="pre">__attribute__((nosvm))</span></code> qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.</p>
+<p>Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.</p>
+</div>
+<div class="section" id="objc-externally-retained">
+<h3><a class="toc-backref" href="#id277">objc_externally_retained</a><a class="headerlink" href="#objc-externally-retained" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id108">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id108" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_externally_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_externally_retained</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_externally_retained</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">objc_externally_retained</span></code> attribute can be applied to strong local
+variables, functions, methods, or blocks to opt into
+<a class="reference external" href="https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables">externally-retained semantics</a>.</p>
+<p>When applied to the definition of a function, method, or block, every parameter
+of the function with implicit strong retainable object pointer type is
+considered externally-retained, and becomes <code class="docutils literal notranslate"><span class="pre">const</span></code>. By explicitly annotating
+a parameter with <code class="docutils literal notranslate"><span class="pre">__strong</span></code>, you can opt back into the default
+non-externally-retained behaviour for that parameter. For instance,
+<code class="docutils literal notranslate"><span class="pre">first_param</span></code> is externally-retained below, but not <code class="docutils literal notranslate"><span class="pre">second_param</span></code>:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_externally_retained</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="bp">NSArray</span> <span class="o">*</span><span class="n">first_param</span><span class="p">,</span> <span class="k">__strong</span> <span class="bp">NSArray</span> <span class="o">*</span><span class="n">second_param</span><span class="p">)</span> <span class="p">{</span>
+  <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Likewise, when applied to a strong local variable, that variable becomes
+<code class="docutils literal notranslate"><span class="pre">const</span></code> and is considered externally-retained.</p>
+<p>When compiled without <code class="docutils literal notranslate"><span class="pre">-fobjc-arc</span></code>, this attribute is ignored.</p>
+</div>
+<div class="section" id="pass-object-size-pass-dynamic-object-size">
+<h3><a class="toc-backref" href="#id278">pass_object_size, pass_dynamic_object_size</a><a class="headerlink" href="#pass-object-size-pass-dynamic-object-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id109">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id109" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">pass_dynamic_object_size</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::pass_object_size</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pass_dynamic_object_size</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::pass_object_size</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pass_dynamic_object_size</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The mangling of functions with parameters that are annotated with
+<code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> is subject to change. You can get around this by
+using <code class="docutils literal notranslate"><span class="pre">__asm__("foo")</span></code> to explicitly name your functions, thus preserving
+your ABI; also, non-overloadable C functions with <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> are
+not mangled.</p>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">pass_object_size(Type)</span></code> attribute can be placed on function parameters to
+instruct clang to call <code class="docutils literal notranslate"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></code> at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type <code class="docutils literal notranslate"><span class="pre">size_t</span></code> directly after the parameter annotated with
+<code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code>. Clang will also replace any calls to
+<code class="docutils literal notranslate"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></code> in the function by said implicit
+parameter.</p>
+<p>Example usage:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">bzero1</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">pass_object_size</span><span class="p">(</span><span class="mi">0</span><span class="p">))))</span>
+    <span class="n">__attribute__</span><span class="p">((</span><span class="n">noinline</span><span class="p">))</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="k">for</span> <span class="p">(</span><span class="cm">/**/</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">p</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="k">return</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">char</span> <span class="n">chars</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span>
+  <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="o">&</span><span class="n">chars</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">chars</span><span class="p">));</span>
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If successfully evaluating <code class="docutils literal notranslate"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></code> at the
+callsite is not possible, then the “failed” value is passed in. So, using the
+definition of <code class="docutils literal notranslate"><span class="pre">bzero1</span></code> from above, the following code would exit cleanly:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">main2</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="n">argv</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">);</span>
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> is preferred. This implies that the choice
+between two identical overloads both with <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#define PS(N) __attribute__((pass_object_size(N)))</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span> <span class="c1">// Overload A</span>
+<span class="c1">// OK -- overload A has no parameters with pass_object_size.</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload B</span>
+<span class="c1">// Error -- Same signature (sans pass_object_size) as overload B, and both</span>
+<span class="c1">// overloads have one or more parameters with the pass_object_size attribute.</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span>
+
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Bar</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload C</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Bar</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">c</span> <span class="n">PS</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span> <span class="c1">// Overload D</span>
+
+<span class="kt">void</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">char</span> <span class="n">known</span><span class="p">[</span><span class="mi">10</span><span class="p">],</span> <span class="o">*</span><span class="n">unknown</span><span class="p">;</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+
+  <span class="n">Bar</span><span class="p">(</span><span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+  <span class="n">Bar</span><span class="p">(</span><span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Currently, <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> is a bit restricted in terms of its usage:</p>
+<ul class="simple">
+<li>Only one use of <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> is allowed per parameter.</li>
+<li>It is an error to take the address of a function with <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> on
+any of its parameters. If you wish to do this, you can create an overload
+without <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> on any parameters.</li>
+<li>It is an error to apply the <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> attribute to parameters that
+are not pointers. Additionally, any parameter that <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code> is
+applied to must be marked <code class="docutils literal notranslate"><span class="pre">const</span></code> at its function’s definition.</li>
+</ul>
+<p>Clang also supports the <code class="docutils literal notranslate"><span class="pre">pass_dynamic_object_size</span></code> attribute, which behaves
+identically to <code class="docutils literal notranslate"><span class="pre">pass_object_size</span></code>, but evaluates a call to
+<code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> at the callee instead of
+<code class="docutils literal notranslate"><span class="pre">__builtin_object_size</span></code>. <code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> provides some extra
+runtime checks when the object size can’t be determined at compile-time. You can
+read more about <code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> <a class="reference external" href="https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically">here</a>.</p>
+</div>
+<div class="section" id="require-constant-initialization">
+<h3><a class="toc-backref" href="#id279">require_constant_initialization</a><a class="headerlink" href="#require-constant-initialization" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id110">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id110" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">require_constant_initialization</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::require_constant_initialization</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the variable to which it is attached is intended
+to have a <a class="reference external" href="http://en.cppreference.com/w/cpp/language/constant_initialization">constant initializer</a>
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.</p>
+<p>Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it’s
+not technically a ‘constant initializer’. This behavior is non-portable.</p>
+<p>Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.</p>
+<p>This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it’s important to fail fast instead
+of silently falling back on dynamic initialization.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// -std=c++14</span>
+<span class="cp">#define SAFE_STATIC [[clang::require_constant_initialization]]</span>
+<span class="k">struct</span> <span class="n">T</span> <span class="p">{</span>
+  <span class="k">constexpr</span> <span class="n">T</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+  <span class="o">~</span><span class="n">T</span><span class="p">();</span> <span class="c1">// non-trivial</span>
+<span class="p">};</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">x</span> <span class="o">=</span> <span class="p">{</span><span class="mi">42</span><span class="p">};</span> <span class="c1">// Initialization OK. Doesn't check destructor.</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// error: variable does not have a constant initializer</span>
+<span class="c1">// copy initialization is not a constant expression on a non-literal type.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-declspec-allocate">
+<h3><a class="toc-backref" href="#id280">section, __declspec(allocate)</a><a class="headerlink" href="#section-declspec-allocate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id111">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id111" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">section</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::section</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">allocate</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">section</span></code> attribute allows you to specify a specific section a
+global variable or function should be in after translation.</p>
+</div>
+<div class="section" id="swift-context">
+<h3><a class="toc-backref" href="#id281">swift_context</a><a class="headerlink" href="#swift-context" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id112">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id112" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">swift_context</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_context</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_context</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">swift_context</span></code> attribute marks a parameter of a <code class="docutils literal notranslate"><span class="pre">swiftcall</span></code>
+function as having the special context-parameter ABI treatment.</p>
+<p>This treatment generally passes the context value in a special register
+which is normally callee-preserved.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">swift_context</span></code> parameter must either be the last parameter or must be
+followed by a <code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code> parameter (which itself must always be
+the last parameter).</p>
+<p>A context parameter must have pointer or reference type.</p>
+</div>
+<div class="section" id="swift-error-result">
+<h3><a class="toc-backref" href="#id282">swift_error_result</a><a class="headerlink" href="#swift-error-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id113">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id113" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_error_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_error_result</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code> attribute marks a parameter of a <code class="docutils literal notranslate"><span class="pre">swiftcall</span></code>
+function as having the special error-result ABI treatment.</p>
+<p>This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:</p>
+<ul class="simple">
+<li>The caller appears to pass the address of a variable of pointer type.
+The current value of this variable is copied into the register before
+the call; if the call returns normally, the value is copied back into the
+variable.</li>
+<li>The callee appears to receive the address of a variable.  This address
+is actually a hidden location in its own stack, initialized with the
+value of the register upon entry.  When the function returns normally,
+the value in that hidden location is written back to the register.</li>
+</ul>
+<p>A <code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code> parameter must be the last parameter, and it must be
+preceded by a <code class="docutils literal notranslate"><span class="pre">swift_context</span></code> parameter.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code> parameter must have type <code class="docutils literal notranslate"><span class="pre">T**</span></code> or <code class="docutils literal notranslate"><span class="pre">T*&</span></code> for some
+type T.  Note that no qualifiers are permitted on the intermediate level.</p>
+<p>It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.</p>
+<p>The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.</p>
+</div>
+<div class="section" id="swift-indirect-result">
+<h3><a class="toc-backref" href="#id283">swift_indirect_result</a><a class="headerlink" href="#swift-indirect-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id114">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id114" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_indirect_result</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swift_indirect_result</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> attribute marks a parameter of a <code class="docutils literal notranslate"><span class="pre">swiftcall</span></code>
+function as having the special indirect-result ABI treatment.</p>
+<p>This treatment gives the parameter the target’s normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter.  However, only the first indirect result will receive this
+treatment.  Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+<code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> parameters.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> parameter must either be the first parameter or
+follow another <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> parameter.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> parameter must have type <code class="docutils literal notranslate"><span class="pre">T*</span></code> or <code class="docutils literal notranslate"><span class="pre">T&</span></code> for
+some object type <code class="docutils literal notranslate"><span class="pre">T</span></code>.  If <code class="docutils literal notranslate"><span class="pre">T</span></code> is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type <code class="docutils literal notranslate"><span class="pre">T</span></code>.</p>
+<p>Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++’s named return value optimization (NRVO).</p>
+</div>
+<div class="section" id="swiftcall">
+<h3><a class="toc-backref" href="#id284">swiftcall</a><a class="headerlink" href="#swiftcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id115">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id115" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">swiftcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swiftcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::swiftcall</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">swiftcall</span></code> attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.</p>
+<p>The lowering for the Swift calling convention, as described by the Swift
+ABI documentation, occurs in multiple phases.  The first, “high-level”
+phase breaks down the formal parameters and results into innately direct
+and indirect components, adds implicit paraameters for the generic
+signature, and assigns the context and error ABI treatments to parameters
+where applicable.  The second phase breaks down the direct parameters
+and results from the first phase and assigns them to registers or the
+stack.  The <code class="docutils literal notranslate"><span class="pre">swiftcall</span></code> convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:</p>
+<ul class="simple">
+<li>Results classified as indirect by high-level lowering should be
+represented as parameters with the <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code> attribute.</li>
+<li>Results classified as direct by high-level lowering should be represented
+as follows:<ul>
+<li>First, remove any empty direct results.</li>
+<li>If there are no direct results, the C result type should be <code class="docutils literal notranslate"><span class="pre">void</span></code>.</li>
+<li>If there is one direct result, the C result type should be a type with
+the exact layout of that result type.</li>
+<li>If there are a multiple direct results, the C result type should be
+a struct type with the exact layout of a tuple of those results.</li>
+</ul>
+</li>
+<li>Parameters classified as indirect by high-level lowering should be
+represented as parameters of pointer type.</li>
+<li>Parameters classified as direct by high-level lowering should be
+omitted if they are empty types; otherwise, they should be represented
+as a parameter type with a layout exactly matching the layout of the
+Swift parameter type.</li>
+<li>The context parameter, if present, should be represented as a trailing
+parameter with the <code class="docutils literal notranslate"><span class="pre">swift_context</span></code> attribute.</li>
+<li>The error result parameter, if present, should be represented as a
+trailing parameter (always following a context parameter) with the
+<code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code> attribute.</li>
+</ul>
+<p><code class="docutils literal notranslate"><span class="pre">swiftcall</span></code> does not support variadic arguments or unprototyped functions.</p>
+<p>The parameter ABI treatment attributes are aspects of the function type.
+A function type which which applies an ABI treatment attribute to a
+parameter is a different type from an otherwise-identical function type
+that does not.  A single parameter may not have multiple ABI treatment
+attributes.</p>
+<p>Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports.  Query for this support
+with <code class="docutils literal notranslate"><span class="pre">__has_attribute(swiftcall)</span></code>.  This implies support for the
+<code class="docutils literal notranslate"><span class="pre">swift_context</span></code>, <code class="docutils literal notranslate"><span class="pre">swift_error_result</span></code>, and <code class="docutils literal notranslate"><span class="pre">swift_indirect_result</span></code>
+attributes.</p>
+</div>
+<div class="section" id="thread">
+<h3><a class="toc-backref" href="#id285">thread</a><a class="headerlink" href="#thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id116">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id116" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">thread</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec(thread)</span></code> attribute declares a variable with thread local
+storage.  It is available under the <code class="docutils literal notranslate"><span class="pre">-fms-extensions</span></code> flag for MSVC
+compatibility.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx">__declspec(thread)</a> on MSDN.</p>
+<p>In Clang, <code class="docutils literal notranslate"><span class="pre">__declspec(thread)</span></code> is generally equivalent in functionality to the
+GNU <code class="docutils literal notranslate"><span class="pre">__thread</span></code> keyword.  The variable must not have a destructor and must have
+a constant initializer, if any.  The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.</p>
+</div>
+<div class="section" id="tls-model">
+<h3><a class="toc-backref" href="#id286">tls_model</a><a class="headerlink" href="#tls-model" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id117">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id117" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">tls_model</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::tls_model</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">tls_model</span></code> attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:</p>
+<ul class="simple">
+<li>global-dynamic</li>
+<li>local-dynamic</li>
+<li>initial-exec</li>
+<li>local-exec</li>
+</ul>
+<p>TLS models are mutually exclusive.</p>
+</div>
+<div class="section" id="uninitialized">
+<h3><a class="toc-backref" href="#id287">uninitialized</a><a class="headerlink" href="#uninitialized" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id118">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id118" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">uninitialized</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::uninitialized</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The command-line parameter <code class="docutils literal notranslate"><span class="pre">-ftrivial-auto-var-init=*</span></code> can be used to
+initialize trivial automatic stack variables. By default, trivial automatic
+stack variables are uninitialized. This attribute is used to override the
+command-line parameter, forcing variables to remain uninitialized. It has no
+semantic meaning in that using uninitialized values is undefined behavior,
+it rather documents the programmer’s intent.</p>
+</div>
+</div>
+<div class="section" id="field-attributes">
+<h2><a class="toc-backref" href="#id288">Field Attributes</a><a class="headerlink" href="#field-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="no-unique-address">
+<h3><a class="toc-backref" href="#id289">no_unique_address</a><a class="headerlink" href="#no-unique-address" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id119">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id119" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">no_unique_address</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">no_unique_address</span></code> attribute allows tail padding in a non-static data
+member to overlap other members of the enclosing class (and in the special
+case when the type is empty, permits it to fully overlap other members).
+The field is laid out as if a base class were encountered at the corresponding
+point within the class (except that it does not share a vptr with the enclosing
+object).</p>
+<p>Example usage:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">></span> <span class="k">struct</span> <span class="n">my_vector</span> <span class="p">{</span>
+  <span class="n">T</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
+  <span class="p">[[</span><span class="n">no_unique_address</span><span class="p">]]</span> <span class="n">Alloc</span> <span class="n">alloc</span><span class="p">;</span>
+  <span class="c1">// ...</span>
+<span class="p">};</span>
+<span class="k">static_assert</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">my_vector</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o"><</span><span class="kt">int</span><span class="o">>></span><span class="p">)</span> <span class="o">==</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">int</span><span class="o">*</span><span class="p">));</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">[[no_unique_address]]</span></code> is a standard C++20 attribute. Clang supports its use
+in C++11 onwards.</p>
+</div>
+</div>
+<div class="section" id="type-attributes">
+<h2><a class="toc-backref" href="#id290">Type Attributes</a><a class="headerlink" href="#type-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="align-value">
+<h3><a class="toc-backref" href="#id291">align_value</a><a class="headerlink" href="#align-value" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id120">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id120" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">align_value</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">double</span> <span class="o">*</span> <span class="n">aligned_double_ptr</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">64</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">double</span> <span class="o">&</span> <span class="n">x</span>  <span class="n">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">128</span><span class="p">)),</span>
+         <span class="n">aligned_double_ptr</span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.</p>
+</div>
+<div class="section" id="hip-pinned-shadow">
+<h3><a class="toc-backref" href="#id292">hip_pinned_shadow</a><a class="headerlink" href="#hip-pinned-shadow" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id121">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id121" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">hip_pinned_shadow</span></code></td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__hip_pinned_shadow__</span></code></td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The GNU style attribute __attribute__((hip_pinned_shadow)) or MSVC style attribute
+__declspec(hip_pinned_shadow) can be added to the definition of a global variable
+to indicate it is a HIP pinned shadow variable. A HIP pinned shadow variable can
+be accessed on both device side and host side. It has external linkage and is
+not initialized on device side. It has internal linkage and is initialized by
+the initializer on host side.</p>
+</div>
+<div class="section" id="noderef">
+<h3><a class="toc-backref" href="#id293">noderef</a><a class="headerlink" href="#noderef" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id122">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id122" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">noderef</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noderef</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::noderef</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">noderef</span></code> attribute causes clang to diagnose dereferences of annotated pointer types.
+This is ideally used with pointers that point to special memory which cannot be read
+from or written to, but allowing for the pointer to be used in pointer arithmetic.
+The following are examples of valid expressions where dereferences are diagnosed:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>  <span class="c1">// warning</span>
+
+<span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">**</span><span class="n">p2</span><span class="p">;</span>
+<span class="n">x</span> <span class="o">=</span> <span class="o">**</span><span class="n">p2</span><span class="p">;</span>  <span class="c1">// warning</span>
+
+<span class="kt">int</span> <span class="o">*</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">*</span><span class="n">p3</span><span class="p">;</span>
+<span class="n">p</span> <span class="o">=</span> <span class="o">*</span><span class="n">p3</span><span class="p">;</span>  <span class="c1">// warning</span>
+
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">*</span><span class="n">s</span><span class="p">;</span>
+<span class="n">x</span> <span class="o">=</span> <span class="n">s</span><span class="o">-></span><span class="n">a</span><span class="p">;</span>    <span class="c1">// warning</span>
+<span class="n">x</span> <span class="o">=</span> <span class="p">(</span><span class="o">*</span><span class="n">s</span><span class="p">).</span><span class="n">a</span><span class="p">;</span>  <span class="c1">// warning</span>
+</pre></div>
+</div>
+<p>Not all dereferences may diagnose a warning if the value directed by the pointer may not be
+accessed. The following are examples of valid expressions where may not be diagnosed:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="o">*</span><span class="n">q</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
+<span class="n">q</span> <span class="o">=</span> <span class="o">&*</span><span class="n">p</span><span class="p">;</span>
+<span class="n">q</span> <span class="o">=</span> <span class="o">*&</span><span class="n">p</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">noderef</span><span class="p">))</span> <span class="o">*</span><span class="n">s</span><span class="p">;</span>
+<span class="n">p</span> <span class="o">=</span> <span class="o">&</span><span class="n">s</span><span class="o">-></span><span class="n">a</span><span class="p">;</span>
+<span class="n">p</span> <span class="o">=</span> <span class="o">&</span><span class="p">(</span><span class="o">*</span><span class="n">s</span><span class="p">).</span><span class="n">a</span><span class="p">;</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">noderef</span></code> is currently only supported for pointers and arrays and not usable for
+references or Objective-C object pointers.</p>
+</div>
+<div class="section" id="objc-class-stub">
+<h3><a class="toc-backref" href="#id294">objc_class_stub</a><a class="headerlink" href="#objc-class-stub" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id123">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id123" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_class_stub</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_class_stub</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_class_stub</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the Objective-C class to which it applies is
+instantiated at runtime.</p>
+<p>Unlike <code class="docutils literal notranslate"><span class="pre">__attribute__((objc_runtime_visible))</span></code>, a class having this attribute
+still has a “class stub” that is visible to the linker. This allows categories
+to be defined. Static message sends with the class as a receiver use a special
+access pattern to ensure the class is lazily instantiated from the class stub.</p>
+<p>Classes annotated with this attribute cannot be subclassed and cannot have
+implementations defined for them. This attribute is intended for use in
+Swift-generated headers for classes defined in Swift.</p>
+<p>Adding or removing this attribute to a class is an ABI-breaking change.</p>
+</div>
+</div>
+<div class="section" id="statement-attributes">
+<h2><a class="toc-backref" href="#id295">Statement Attributes</a><a class="headerlink" href="#statement-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="pragma-clang-loop">
+<h3><a class="toc-backref" href="#id296">#pragma clang loop</a><a class="headerlink" href="#pragma-clang-loop" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id124">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id124" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">loop</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">unroll</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">nounroll</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">unroll_and_jam</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">nounroll_and_jam</span></code></td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></code> directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows pipelining to be
+disabled, or vectorization, interleaving, and unrolling to be enabled or disabled.
+Vector width, interleave count, unrolling count, and the initiation interval
+for pipelining can be explicitly specified. See <a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for details.</p>
+</div>
+<div class="section" id="pragma-unroll-pragma-nounroll">
+<h3><a class="toc-backref" href="#id297">#pragma unroll, #pragma nounroll</a><a class="headerlink" href="#pragma-unroll-pragma-nounroll" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id125">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id125" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">loop</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">unroll</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">nounroll</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">unroll_and_jam</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">nounroll_and_jam</span></code></td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Loop unrolling optimization hints can be specified with <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">unroll</span></code> and
+<code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">nounroll</span></code>. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.</p>
+<p>Specifying <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">unroll</span></code> without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time and
+attempt to partially unroll the loop if the trip count is not known at compile
+time:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma unroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying the optional parameter, <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></code>, directs the
+unroller to unroll the loop <code class="docutils literal notranslate"><span class="pre">_value_</span></code> times.  The parameter may optionally be
+enclosed in parentheses:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma unroll 16</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="cp">#pragma unroll(16)</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">nounroll</span></code> indicates that the loop should not be unrolled:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma nounroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">unroll</span></code> and <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></code> have identical semantics to
+<code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(full)</span></code> and
+<code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll_count(_value_)</span></code> respectively. <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">nounroll</span></code>
+is equivalent to <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(disable)</span></code>.  See
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for further details including limitations of the unroll hints.</p>
+</div>
+<div class="section" id="read-only-write-only-read-write-read-only-write-only-read-write">
+<h3><a class="toc-backref" href="#id298">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a><a class="headerlink" href="#read-only-write-only-read-write-read-only-write-only-read-write" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id126">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id126" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__read_only</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">read_only</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">__write_only</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">write_only</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">__read_write</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">read_write</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.</p>
+<p>The read_only/__read_only, write_only/__write_only and read_write/__read_write
+names are reserved for use as access qualifiers and shall not be used otherwise.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">kernel</span> <span class="kt">void</span>
+<span class="nf">foo</span> <span class="p">(</span><span class="n">read_only</span> <span class="n">image2d_t</span> <span class="n">imageA</span><span class="p">,</span>
+     <span class="n">write_only</span> <span class="n">image2d_t</span> <span class="n">imageB</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.</p>
+<p>The read_write (or __read_write) qualifier can not be used with pipe.</p>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.6.</p>
+</div>
+<div class="section" id="fallthrough">
+<h3><a class="toc-backref" href="#id299">fallthrough</a><a class="headerlink" href="#fallthrough" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id127">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id127" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">fallthrough</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::fallthrough</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">fallthrough</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">fallthrough</span></code> (or <code class="docutils literal notranslate"><span class="pre">clang::fallthrough</span></code>) attribute is used
+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 <code class="docutils literal notranslate"><span class="pre">break;</span></code>, so it can be placed in most places
+where <code class="docutils literal notranslate"><span class="pre">break;</span></code> can, but only if there are no statements on the execution path
+between it and the next switch label.</p>
+<p>By default, Clang does not warn on unannotated fallthrough from one <code class="docutils literal notranslate"><span class="pre">switch</span></code>
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the <code class="docutils literal notranslate"><span class="pre">-Wimplicit-fallthrough</span></code> argument.</p>
+<p>Here is an example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// compile with -Wimplicit-fallthrough</span>
+<span class="k">switch</span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="mi">22</span><span class="o">:</span>
+<span class="k">case</span> <span class="mi">33</span><span class="o">:</span>  <span class="c1">// no warning: no statements between case labels</span>
+  <span class="n">f</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">44</span><span class="o">:</span>  <span class="c1">// warning: unannotated fall-through</span>
+  <span class="n">g</span><span class="p">();</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+<span class="k">case</span> <span class="mi">55</span><span class="o">:</span>  <span class="c1">// no warning</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">h</span><span class="p">();</span>
+    <span class="k">break</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="k">else</span> <span class="p">{</span>
+    <span class="n">i</span><span class="p">();</span>
+    <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+  <span class="p">}</span>
+<span class="k">case</span> <span class="mi">66</span><span class="o">:</span>  <span class="c1">// no warning</span>
+  <span class="n">p</span><span class="p">();</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span> <span class="c1">// warning: fallthrough annotation does not</span>
+                          <span class="c1">//          directly precede case label</span>
+  <span class="n">q</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">77</span><span class="o">:</span>  <span class="c1">// warning: unannotated fall-through</span>
+  <span class="n">r</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="intel-reqd-sub-group-size">
+<h3><a class="toc-backref" href="#id300">intel_reqd_sub_group_size</a><a class="headerlink" href="#intel-reqd-sub-group-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id128">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id128" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">intel_reqd_sub_group_size</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See <cite>cl_intel_required_subgroup_size
+<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt></cite>
+for details.</p>
+</div>
+<div class="section" id="opencl-unroll-hint">
+<h3><a class="toc-backref" href="#id301">opencl_unroll_hint</a><a class="headerlink" href="#opencl-unroll-hint" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id129">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id129" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">opencl_unroll_hint</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The opencl_unroll_hint attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf">OpenCL v2.0</a>
+s6.11.5 for details.</p>
+</div>
+<div class="section" id="suppress">
+<h3><a class="toc-backref" href="#id302">suppress</a><a class="headerlink" href="#suppress" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id130">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id130" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">gsl::suppress</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">[[gsl::suppress]]</span></code> attribute suppresses specific
+clang-tidy diagnostics for rules of the <a class="reference external" href="https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement">C++ Core Guidelines</a> in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">gsl</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"Rh-public"</span><span class="p">)]]</span>
+<span class="kt">void</span> <span class="n">f_</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
+  <span class="p">[[</span><span class="n">gsl</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"type"</span><span class="p">)]]</span> <span class="p">{</span>
+    <span class="n">p</span> <span class="o">=</span> <span class="k">reinterpret_cast</span><span class="o"><</span><span class="kt">int</span><span class="o">*></span><span class="p">(</span><span class="mi">7</span><span class="p">);</span>
+  <span class="p">}</span>
+<span class="p">}</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">suppress</span><span class="p">(</span><span class="s">"type"</span><span class="p">,</span> <span class="s">"bounds"</span><span class="p">)]];</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="declaration-attributes">
+<h2><a class="toc-backref" href="#id303">Declaration Attributes</a><a class="headerlink" href="#declaration-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="single-inhertiance-multiple-inheritance-virtual-inheritance">
+<h3><a class="toc-backref" href="#id304">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a><a class="headerlink" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id131">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id131" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__single_inheritance</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">__multiple_inheritance</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">__virtual_inheritance</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">__unspecified_inheritance</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This collection of keywords is enabled under <code class="docutils literal notranslate"><span class="pre">-fms-extensions</span></code> and controls
+the pointer-to-member representation used on <code class="docutils literal notranslate"><span class="pre">*-*-win32</span></code> targets.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">*-*-win32</span></code> targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.</p>
+<p>However, this is problematic when a forward declaration is only available and
+no definition has been made yet.  In such cases, Clang is forced to utilize the
+most general representation that is available to it.</p>
+<p>These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.</p>
+<p>This family of keywords belong between the <code class="docutils literal notranslate"><span class="pre">class-key</span></code> and <code class="docutils literal notranslate"><span class="pre">class-name</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">S</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+<p>This keyword can be applied to class templates but only has an effect when used
+on full specializations:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="p">,</span> <span class="k">typename</span> <span class="n">U</span><span class="o">></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on primary template</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="o">></span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on partial specialization</span>
+<span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">float</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Note that choosing an inheritance model less general than strictly necessary is
+an error:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">S</span><span class="p">;</span> <span class="c1">// error: inheritance model does not match definition</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="deprecated">
+<h3><a class="toc-backref" href="#id305">deprecated</a><a class="headerlink" href="#deprecated" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id132">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id132" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">deprecated</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::deprecated</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">deprecated</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">deprecated</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">deprecated</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.</p>
+<p>Consider the function declaration for a hypothetical function <code class="docutils literal notranslate"><span class="pre">f</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">(</span><span class="s">"message"</span><span class="p">,</span> <span class="s">"replacement"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>When spelled as <cite>__attribute__((deprecated))</cite>, the deprecated attribute can have
+two optional string arguments. The first one is the message to display when
+emitting the warning; the second one enables the compiler to provide a Fix-It
+to replace the deprecated name with a new name. Otherwise, when spelled as
+<cite>[[gnu::deprecated]] or [[deprecated]]</cite>, the attribute can have one optional
+string argument which is the message to display when emitting the warning.</p>
+</div>
+<div class="section" id="empty-bases">
+<h3><a class="toc-backref" href="#id306">empty_bases</a><a class="headerlink" href="#empty-bases" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id133">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id133" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">empty_bases</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="enum-extensibility">
+<h3><a class="toc-backref" href="#id307">enum_extensibility</a><a class="headerlink" href="#enum-extensibility" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id134">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id134" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">enum_extensibility</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::enum_extensibility</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::enum_extensibility</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Attribute <code class="docutils literal notranslate"><span class="pre">enum_extensibility</span></code> is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+<code class="docutils literal notranslate"><span class="pre">closed</span></code> or <code class="docutils literal notranslate"><span class="pre">open</span></code> as an argument. <code class="docutils literal notranslate"><span class="pre">closed</span></code> indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with <code class="docutils literal notranslate"><span class="pre">flag_enum</span></code>, a value that
+can be constructed using values corresponding to the enumerators. <code class="docutils literal notranslate"><span class="pre">open</span></code>
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">closed</span><span class="p">)))</span> <span class="n">ClosedEnum</span> <span class="p">{</span>
+  <span class="n">A0</span><span class="p">,</span> <span class="n">A1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">open</span><span class="p">)))</span> <span class="n">OpenEnum</span> <span class="p">{</span>
+  <span class="n">B0</span><span class="p">,</span> <span class="n">B1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">closed</span><span class="p">),</span><span class="n">flag_enum</span><span class="p">))</span> <span class="n">ClosedFlagEnum</span> <span class="p">{</span>
+  <span class="n">C0</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> <span class="n">C1</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">enum_extensibility</span><span class="p">(</span><span class="n">open</span><span class="p">),</span><span class="n">flag_enum</span><span class="p">))</span> <span class="n">OpenFlagEnum</span> <span class="p">{</span>
+  <span class="n">D0</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> <span class="n">D1</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">foo1</span><span class="p">()</span> <span class="p">{</span>
+  <span class="k">enum</span> <span class="n">ClosedEnum</span> <span class="n">ce</span><span class="p">;</span>
+  <span class="k">enum</span> <span class="n">OpenEnum</span> <span class="n">oe</span><span class="p">;</span>
+  <span class="k">enum</span> <span class="n">ClosedFlagEnum</span> <span class="n">cfe</span><span class="p">;</span>
+  <span class="k">enum</span> <span class="n">OpenFlagEnum</span> <span class="n">ofe</span><span class="p">;</span>
+
+  <span class="n">ce</span> <span class="o">=</span> <span class="n">A1</span><span class="p">;</span>           <span class="c1">// no warnings</span>
+  <span class="n">ce</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>          <span class="c1">// warning issued</span>
+  <span class="n">oe</span> <span class="o">=</span> <span class="n">B1</span><span class="p">;</span>           <span class="c1">// no warnings</span>
+  <span class="n">oe</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>          <span class="c1">// no warnings</span>
+  <span class="n">cfe</span> <span class="o">=</span> <span class="n">C0</span> <span class="o">|</span> <span class="n">C1</span><span class="p">;</span>     <span class="c1">// no warnings</span>
+  <span class="n">cfe</span> <span class="o">=</span> <span class="n">C0</span> <span class="o">|</span> <span class="n">C1</span> <span class="o">|</span> <span class="mi">4</span><span class="p">;</span> <span class="c1">// warning issued</span>
+  <span class="n">ofe</span> <span class="o">=</span> <span class="n">D0</span> <span class="o">|</span> <span class="n">D1</span><span class="p">;</span>     <span class="c1">// no warnings</span>
+  <span class="n">ofe</span> <span class="o">=</span> <span class="n">D0</span> <span class="o">|</span> <span class="n">D1</span> <span class="o">|</span> <span class="mi">4</span><span class="p">;</span> <span class="c1">// no warnings</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="external-source-symbol">
+<h3><a class="toc-backref" href="#id308">external_source_symbol</a><a class="headerlink" href="#external-source-symbol" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id135">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id135" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">external_source_symbol</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::external_source_symbol</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::external_source_symbol</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">external_source_symbol</span></code> attribute specifies that a declaration originates
+from an external source and describes the nature of that source.</p>
+<p>The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct ‘jump-to-definition’ feature. For a concrete example,
+consider a protocol that’s defined in a Swift file:</p>
+<div class="highlight-swift notranslate"><div class="highlight"><pre><span></span><span class="kr">@objc</span> <span class="kd">public</span> <span class="kd">protocol</span> <span class="nc">SwiftProtocol</span> <span class="p">{</span>
+  <span class="kd">func</span> <span class="nf">method</span><span class="p">()</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the <code class="docutils literal notranslate"><span class="pre">external_source_symbol</span></code> attribute to make Clang aware of the fact
+that <code class="docutils literal notranslate"><span class="pre">SwiftProtocol</span></code> actually originates from a Swift module:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">external_source_symbol</span><span class="p">(</span><span class="n">language</span><span class="o">=</span><span class="s">"Swift"</span><span class="p">,</span><span class="n">defined_in</span><span class="o">=</span><span class="s">"module"</span><span class="p">)))</span>
+<span class="k">@protocol</span> <span class="nc">SwiftProtocol</span>
+<span class="k">@required</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">method</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Consequently, when ‘jump-to-definition’ is performed at a location that
+references <code class="docutils literal notranslate"><span class="pre">SwiftProtocol</span></code>, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">external_source_symbol</span></code> attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:</p>
+<dl class="docutils">
+<dt>language=<em>string-literal</em></dt>
+<dd>The name of the source language in which this declaration was defined.</dd>
+<dt>defined_in=<em>string-literal</em></dt>
+<dd>The name of the source container in which the declaration was defined. The
+exact definition of source container is language-specific, e.g. Swift’s
+source containers are modules, so <code class="docutils literal notranslate"><span class="pre">defined_in</span></code> should specify the Swift
+module name.</dd>
+<dt>generated_declaration</dt>
+<dd>This declaration was automatically generated by some tool.</dd>
+</dl>
+<p>The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.</p>
+</div>
+<div class="section" id="flag-enum">
+<h3><a class="toc-backref" href="#id309">flag_enum</a><a class="headerlink" href="#flag-enum" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id136">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id136" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">flag_enum</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::flag_enum</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::flag_enum</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.</p>
+</div>
+<div class="section" id="layout-version">
+<h3><a class="toc-backref" href="#id310">layout_version</a><a class="headerlink" href="#layout-version" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id137">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id137" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">layout_version</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="lto-visibility-public">
+<h3><a class="toc-backref" href="#id311">lto_visibility_public</a><a class="headerlink" href="#lto-visibility-public" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id138">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id138" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">lto_visibility_public</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::lto_visibility_public</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::lto_visibility_public</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>See <a class="reference internal" href="LTOVisibility.html"><span class="doc">LTO Visibility</span></a>.</p>
+</div>
+<div class="section" id="novtable">
+<h3><a class="toc-backref" href="#id312">novtable</a><a class="headerlink" href="#novtable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id139">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id139" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">novtable</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table. It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="objc-boxable">
+<h3><a class="toc-backref" href="#id313">objc_boxable</a><a class="headerlink" href="#objc-boxable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id140">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id140" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_boxable</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_boxable</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_boxable</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Structs and unions marked with the <code class="docutils literal notranslate"><span class="pre">objc_boxable</span></code> attribute can be used
+with the Objective-C boxed expression syntax, <code class="docutils literal notranslate"><span class="pre">@(...)</span></code>.</p>
+<p><strong>Usage</strong>: <code class="docutils literal notranslate"><span class="pre">__attribute__((objc_boxable))</span></code>. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">some_struct</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="k">union</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">some_union</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
+  <span class="kt">float</span> <span class="n">f</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="k">typedef</span> <span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">_some_struct</span> <span class="n">some_struct</span><span class="p">;</span>
+
+<span class="c1">// ...</span>
+
+<span class="n">some_struct</span> <span class="n">ss</span><span class="p">;</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">boxed</span> <span class="o">=</span> <span class="l">@(</span><span class="n">ss</span><span class="l">)</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-nonlazy-class">
+<h3><a class="toc-backref" href="#id314">objc_nonlazy_class</a><a class="headerlink" href="#objc-nonlazy-class" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id141">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id141" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_nonlazy_class</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_nonlazy_class</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_nonlazy_class</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an Objective-C <code class="docutils literal notranslate"><span class="pre">@interface</span></code> or
+<code class="docutils literal notranslate"><span class="pre">@implementation</span></code> declaration to add the class to the list of non-lazily
+initialized classes. A non-lazy class will be initialized eagerly when the
+Objective-C runtime is loaded. This is required for certain system classes which
+have instances allocated in non-standard ways, such as the classes for blocks
+and constant strings. Adding this attribute is essentially equivalent to
+providing a trivial <cite>+load</cite> method but avoids the (fairly small) load-time
+overheads associated with defining and calling such a method.</p>
+</div>
+<div class="section" id="objc-runtime-name">
+<h3><a class="toc-backref" href="#id315">objc_runtime_name</a><a class="headerlink" href="#objc-runtime-name" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id142">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id142" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_runtime_name</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_runtime_name</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_runtime_name</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The <cite>objc_runtime_name</cite>
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object’s metadata name instead of the
+default name.</p>
+<p><strong>Usage</strong>: <code class="docutils literal notranslate"><span class="pre">__attribute__((objc_runtime_name("MyLocalName")))</span></code>.  This attribute
+can only be placed before an @protocol or @interface declaration:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_runtime_name</span><span class="p">(</span><span class="s">"MyLocalName"</span><span class="p">)))</span>
+<span class="k">@interface</span> <span class="nc">Message</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-runtime-visible">
+<h3><a class="toc-backref" href="#id316">objc_runtime_visible</a><a class="headerlink" href="#objc-runtime-visible" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id143">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id143" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_runtime_visible</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_runtime_visible</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_runtime_visible</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the Objective-C class to which it applies is
+visible to the Objective-C runtime but not to the linker. Classes annotated
+with this attribute cannot be subclassed and cannot have categories defined for
+them.</p>
+</div>
+<div class="section" id="objc-subclassing-restricted">
+<h3><a class="toc-backref" href="#id317">objc_subclassing_restricted</a><a class="headerlink" href="#objc-subclassing-restricted" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id144">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id144" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">objc_subclassing_restricted</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_subclassing_restricted</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::objc_subclassing_restricted</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an Objective-C <code class="docutils literal notranslate"><span class="pre">@interface</span></code> declaration to
+ensure that this class cannot be subclassed.</p>
+</div>
+<div class="section" id="selectany">
+<h3><a class="toc-backref" href="#id318">selectany</a><a class="headerlink" href="#selectany" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id145">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id145" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">selectany</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::selectany</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">selectany</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute appertains to a global symbol, causing it to have a weak
+definition (
+<a class="reference external" href="https://llvm.org/docs/LangRef.html#linkage-types">linkonce</a>
+), allowing the linker to select any definition.</p>
+<p>For more information see
+<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html">gcc documentation</a>
+or <a class="reference external" href="https://docs.microsoft.com/pl-pl/cpp/cpp/selectany">msvc documentation</a>.</p>
+</div>
+<div class="section" id="transparent-union">
+<h3><a class="toc-backref" href="#id319">transparent_union</a><a class="headerlink" href="#transparent-union" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id146">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id146" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">transparent_union</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::transparent_union</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:</p>
+<ul class="simple">
+<li>A value whose type is any member of the transparent union can be passed as an
+argument without the need to cast that value.</li>
+<li>The argument is passed to the function using the calling convention of the
+first member of the transparent union. Consequently, all the members of the
+transparent union should have the same calling convention as its first member.</li>
+</ul>
+<p>Transparent unions are not supported in C++.</p>
+</div>
+<div class="section" id="trivial-abi">
+<h3><a class="toc-backref" href="#id320">trivial_abi</a><a class="headerlink" href="#trivial-abi" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id147">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id147" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">trivial_abi</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::trivial_abi</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">trivial_abi</span></code> attribute can be applied to a C++ class, struct, or union.
+It instructs the compiler to pass and return the type using the C ABI for the
+underlying type when the type would otherwise be considered non-trivial for the
+purpose of calls.
+A class annotated with <cite>trivial_abi</cite> can have non-trivial destructors or copy/move constructors without automatically becoming non-trivial for the purposes of calls. For example:</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// A is trivial for the purposes of calls because `trivial_abi` makes the</span>
+<span class="c1">// user-provided special functions trivial.</span>
+<span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">trivial_abi</span><span class="p">))</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="o">~</span><span class="n">A</span><span class="p">();</span>
+  <span class="n">A</span><span class="p">(</span><span class="k">const</span> <span class="n">A</span> <span class="o">&</span><span class="p">);</span>
+  <span class="n">A</span><span class="p">(</span><span class="n">A</span> <span class="o">&&</span><span class="p">);</span>
+  <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="c1">// B's destructor and copy/move constructor are considered trivial for the</span>
+<span class="c1">// purpose of calls because A is trivial.</span>
+<span class="k">struct</span> <span class="n">B</span> <span class="p">{</span>
+  <span class="n">A</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If a type is trivial for the purposes of calls, has a non-trivial destructor,
+and is passed as an argument by value, the convention is that the callee will
+destroy the object before returning.</p>
+<p>Attribute <code class="docutils literal notranslate"><span class="pre">trivial_abi</span></code> has no effect in the following cases:</p>
+<ul class="simple">
+<li>The class directly declares a virtual base or virtual methods.</li>
+<li>The class has a base class that is non-trivial for the purposes of calls.</li>
+<li>The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes:<ul>
+<li>classes that are non-trivial for the purposes of calls</li>
+<li>__weak-qualified types in Objective-C++</li>
+<li>arrays of any of the above</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-address-spaces">
+<h2><a class="toc-backref" href="#id321">OpenCL Address Spaces</a><a class="headerlink" href="#opencl-address-spaces" title="Permalink to this headline">¶</a></h2>
+<p>The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+__generic(generic), __global(global), __local(local), __private(private),
+__constant(constant).</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__constant</span> <span class="kt">int</span> <span class="n">c</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="n">__generic</span> <span class="kt">int</span><span class="o">*</span> <span class="nf">foo</span><span class="p">(</span><span class="n">global</span> <span class="kt">int</span><span class="o">*</span> <span class="n">g</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">__local</span> <span class="kt">int</span><span class="o">*</span> <span class="n">l</span><span class="p">;</span>
+  <span class="n">private</span> <span class="kt">int</span> <span class="n">p</span><span class="p">;</span>
+  <span class="p">...</span>
+  <span class="k">return</span> <span class="n">l</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.5.</p>
+<div class="section" id="constant">
+<h3><a class="toc-backref" href="#id322">constant</a><a class="headerlink" href="#constant" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id148">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id148" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__constant</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">constant</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.</p>
+</div>
+<div class="section" id="generic">
+<h3><a class="toc-backref" href="#id323">generic</a><a class="headerlink" href="#generic" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id149">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id149" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__generic</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">generic</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for ‘__constant’ in OpenCL code which can be used with multiple address
+spaces.</p>
+</div>
+<div class="section" id="global">
+<h3><a class="toc-backref" href="#id324">global</a><a class="headerlink" href="#global" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id150">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id150" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__global</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">global</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.</p>
+</div>
+<div class="section" id="local">
+<h3><a class="toc-backref" href="#id325">local</a><a class="headerlink" href="#local" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id151">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id151" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__local</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">local</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.</p>
+</div>
+<div class="section" id="private">
+<h3><a class="toc-backref" href="#id326">private</a><a class="headerlink" href="#private" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id152">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id152" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__private</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">private</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.</p>
+</div>
+</div>
+<div class="section" id="amd-gpu-attributes">
+<h2><a class="toc-backref" href="#id327">AMD GPU Attributes</a><a class="headerlink" href="#amd-gpu-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="amdgpu-flat-work-group-size">
+<h3><a class="toc-backref" href="#id328">amdgpu_flat_work_group_size</a><a class="headerlink" href="#amdgpu-flat-work-group-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id153">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id153" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">amdgpu_flat_work_group_size</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::amdgpu_flat_work_group_size</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.</p>
+<p>Clang supports the
+<code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_flat_work_group_size(<min>,</span> <span class="pre"><max>)))</span></code> attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.</p>
+<p><code class="docutils literal notranslate"><span class="pre"><min></span></code> parameter specifies the minimum flat work-group size, and <code class="docutils literal notranslate"><span class="pre"><max></span></code>
+parameter specifies the maximum flat work-group size (must be greater than
+<code class="docutils literal notranslate"><span class="pre"><min></span></code>) to which all dispatches of the kernel will conform. Passing <code class="docutils literal notranslate"><span class="pre">0,</span> <span class="pre">0</span></code>
+as <code class="docutils literal notranslate"><span class="pre"><min>,</span> <span class="pre"><max></span></code> implies the default behavior (<code class="docutils literal notranslate"><span class="pre">128,</span> <span class="pre">256</span></code>).</p>
+<p>If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-sgpr">
+<h3><a class="toc-backref" href="#id329">amdgpu_num_sgpr</a><a class="headerlink" href="#amdgpu-num-sgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id154">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id154" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">amdgpu_num_sgpr</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::amdgpu_num_sgpr</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></code> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <code class="docutils literal notranslate"><span class="pre">0</span></code> as
+<code class="docutils literal notranslate"><span class="pre">num_sgpr</span></code> and/or <code class="docutils literal notranslate"><span class="pre">num_vgpr</span></code> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <code class="docutils literal notranslate"><span class="pre">amdgpu_waves_per_eu</span></code> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-vgpr">
+<h3><a class="toc-backref" href="#id330">amdgpu_num_vgpr</a><a class="headerlink" href="#amdgpu-num-vgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id155">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id155" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">amdgpu_num_vgpr</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::amdgpu_num_vgpr</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></code> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <code class="docutils literal notranslate"><span class="pre">0</span></code> as
+<code class="docutils literal notranslate"><span class="pre">num_sgpr</span></code> and/or <code class="docutils literal notranslate"><span class="pre">num_vgpr</span></code> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <code class="docutils literal notranslate"><span class="pre">amdgpu_waves_per_eu</span></code> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-waves-per-eu">
+<h3><a class="toc-backref" href="#id331">amdgpu_waves_per_eu</a><a class="headerlink" href="#amdgpu-waves-per-eu" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id156">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id156" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">amdgpu_waves_per_eu</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::amdgpu_waves_per_eu</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.</p>
+<p>Clang supports the <code class="docutils literal notranslate"><span class="pre">__attribute__((amdgpu_waves_per_eu(<min>[,</span> <span class="pre"><max>])))</span></code>
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.</p>
+<p><code class="docutils literal notranslate"><span class="pre"><min></span></code> parameter specifies the requested minimum number of waves per EU, and
+<em>optional</em> <code class="docutils literal notranslate"><span class="pre"><max></span></code> parameter specifies the requested maximum number of waves
+per EU (must be greater than <code class="docutils literal notranslate"><span class="pre"><min></span></code> if specified). If <code class="docutils literal notranslate"><span class="pre"><max></span></code> is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+<code class="docutils literal notranslate"><span class="pre">0,</span> <span class="pre">0</span></code> as <code class="docutils literal notranslate"><span class="pre"><min>,</span> <span class="pre"><max></span></code> implies the default behavior (no limits).</p>
+<p>If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least <code class="docutils literal notranslate"><span class="pre"><min></span></code> wavefronts and at most
+<code class="docutils literal notranslate"><span class="pre"><max></span></code> wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.</p>
+<p>This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h2><a class="toc-backref" href="#id332">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.</p>
+<div class="section" id="aarch64-vector-pcs">
+<h3><a class="toc-backref" href="#id333">aarch64_vector_pcs</a><a class="headerlink" href="#aarch64-vector-pcs" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id157">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id157" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">aarch64_vector_pcs</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::aarch64_vector_pcs</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::aarch64_vector_pcs</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On AArch64 targets, this attribute changes the calling convention of a
+function to preserve additional floating-point and Advanced SIMD registers
+relative to the default calling convention used for AArch64.</p>
+<p>This means it is more efficient to call such functions from code that performs
+extensive floating-point and vector calculations, because fewer live SIMD and FP
+registers need to be saved. This property makes it well-suited for e.g.
+floating-point or vector math library functions, which are typically leaf
+functions that require a small number of registers.</p>
+<p>However, using this attribute also means that it is more expensive to call
+a function that adheres to the default calling convention from within such
+a function. Therefore, it is recommended that this attribute is only used
+for leaf functions.</p>
+<p>For more information, see the documentation for <a class="reference external" href="https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi">aarch64_vector_pcs</a> on
+the Arm Developer website.</p>
+</div>
+<div class="section" id="fastcall">
+<h3><a class="toc-backref" href="#id334">fastcall</a><a class="headerlink" href="#fastcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id158">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id158" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">fastcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::fastcall</span></code></td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__fastcall</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">_fastcall</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the <code class="docutils literal notranslate"><span class="pre">regparm</span></code> attribute, which does
+not require callee-cleanup.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/6xa169sk.aspx">__fastcall</a> on MSDN.</p>
+</div>
+<div class="section" id="ms-abi">
+<h3><a class="toc-backref" href="#id335">ms_abi</a><a class="headerlink" href="#ms-abi" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id159">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id159" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">ms_abi</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::ms_abi</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On non-Windows x86_64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows x86_64. This
+attribute has no effect on Windows targets or non-x86_64 targets.</p>
+</div>
+<div class="section" id="pcs">
+<h3><a class="toc-backref" href="#id336">pcs</a><a class="headerlink" href="#pcs" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id160">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id160" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">pcs</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::pcs</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On ARM targets, this attribute can be used to select calling conventions
+similar to <code class="docutils literal notranslate"><span class="pre">stdcall</span></code> on x86. Valid parameter values are “aapcs” and
+“aapcs-vfp”.</p>
+</div>
+<div class="section" id="preserve-all">
+<h3><a class="toc-backref" href="#id337">preserve_all</a><a class="headerlink" href="#preserve-all" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id161">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id161" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">preserve_all</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::preserve_all</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::preserve_all</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <code class="docutils literal notranslate"><span class="pre">preserve_all</span></code> calling convention attempts to make the code
+in the caller even less intrusive than the <code class="docutils literal notranslate"><span class="pre">preserve_most</span></code> calling convention.
+This calling convention also behaves identical to the <code class="docutils literal notranslate"><span class="pre">C</span></code> calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn’t apply for values
+returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Furthermore it also preserves
+all floating-point registers (XMMs/YMMs).</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that don’t need to call out to any other functions.</p>
+<p>This calling convention, like the <code class="docutils literal notranslate"><span class="pre">preserve_most</span></code> calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.</p>
+</div>
+<div class="section" id="preserve-most">
+<h3><a class="toc-backref" href="#id338">preserve_most</a><a class="headerlink" href="#preserve-most" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id162">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id162" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">preserve_most</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::preserve_most</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::preserve_most</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <code class="docutils literal notranslate"><span class="pre">preserve_most</span></code> calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the <code class="docutils literal notranslate"><span class="pre">C</span></code> calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn’t
+apply for values returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Floating-point registers
+(XMMs/YMMs) are not preserved and need to be saved by the caller.</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that have a hot path and a cold path. The hot path is usually a small piece
+of code that doesn’t use many registers. The cold path might need to call out to
+another function and therefore only needs to preserve the caller-saved
+registers, which haven’t already been saved by the caller. The
+<cite>preserve_most</cite> calling convention is very similar to the <code class="docutils literal notranslate"><span class="pre">cold</span></code> calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. <code class="docutils literal notranslate"><span class="pre">coldcc</span></code> is for function calls that are
+rarely executed, whereas <cite>preserve_most</cite> function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore <code class="docutils literal notranslate"><span class="pre">preserve_most</span></code>
+doesn’t prevent the inliner from inlining the function call.</p>
+<p>This calling convention will be used by a future version of the Objective-C
+runtime and should therefore still be considered experimental at this time.
+Although this convention was created to optimize certain runtime calls to
+the Objective-C runtime, it is not limited to this runtime and might be used
+by other runtimes in the future too. The current implementation only
+supports X86-64 and AArch64, but the intention is to support more architectures
+in the future.</p>
+</div>
+<div class="section" id="regcall">
+<h3><a class="toc-backref" href="#id339">regcall</a><a class="headerlink" href="#regcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id163">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id163" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">regcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::regcall</span></code></td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__regcall</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On x86 targets, this attribute changes the calling convention to
+<a class="reference external" href="https://software.intel.com/en-us/node/693069">__regcall</a> convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.</p>
+</div>
+<div class="section" id="regparm">
+<h3><a class="toc-backref" href="#id340">regparm</a><a class="headerlink" href="#regparm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id164">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id164" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">regparm</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::regparm</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.</p>
+</div>
+<div class="section" id="stdcall">
+<h3><a class="toc-backref" href="#id341">stdcall</a><a class="headerlink" href="#stdcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id165">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id165" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">stdcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::stdcall</span></code></td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__stdcall</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">_stdcall</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx">__stdcall</a> on MSDN.</p>
+</div>
+<div class="section" id="thiscall">
+<h3><a class="toc-backref" href="#id342">thiscall</a><a class="headerlink" href="#thiscall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id166">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id166" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">thiscall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::thiscall</span></code></td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__thiscall</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">_thiscall</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit <code class="docutils literal notranslate"><span class="pre">this</span></code>
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx">__thiscall</a> on
+MSDN.</p>
+</div>
+<div class="section" id="vectorcall">
+<h3><a class="toc-backref" href="#id343">vectorcall</a><a class="headerlink" href="#vectorcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id167">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id167" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">vectorcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::vectorcall</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::vectorcall</span></code></td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">__vectorcall</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">_vectorcall</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 <em>and</em> x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.</p>
+<p>On 32-bit x86 targets, this calling convention is similar to <code class="docutils literal notranslate"><span class="pre">__fastcall</span></code>.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack.  On x86_64
+targets, the callee does <em>not</em> clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.</p>
+<p>On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.</p>
+<p>See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/dn375768.aspx">__vectorcall</a> on MSDN for more details.</p>
+</div>
+</div>
+<div class="section" id="consumed-annotation-checking">
+<h2><a class="toc-backref" href="#id344">Consumed Annotation Checking</a><a class="headerlink" href="#consumed-annotation-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although <strong>the implementation
+for these annotations is currently in development and are subject to change.</strong></p>
+<div class="section" id="callable-when">
+<h3><a class="toc-backref" href="#id345">callable_when</a><a class="headerlink" href="#callable-when" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id168">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id168" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">callable_when</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::callable_when</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((callable_when(...)))</span></code> to indicate what states a method
+may be called in.  Valid states are unconsumed, consumed, or unknown.  Each
+argument to this attribute must be a quoted string.  E.g.:</p>
+<p><code class="docutils literal notranslate"><span class="pre">__attribute__((callable_when("unconsumed",</span> <span class="pre">"unknown")))</span></code></p>
+</div>
+<div class="section" id="consumable">
+<h3><a class="toc-backref" href="#id346">consumable</a><a class="headerlink" href="#consumable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id169">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id169" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">consumable</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::consumable</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Each <code class="docutils literal notranslate"><span class="pre">class</span></code> that uses any of the typestate annotations must first be marked
+using the <code class="docutils literal notranslate"><span class="pre">consumable</span></code> attribute.  Failure to do so will result in a warning.</p>
+<p>This attribute accepts a single parameter that must be one of the following:
+<code class="docutils literal notranslate"><span class="pre">unknown</span></code>, <code class="docutils literal notranslate"><span class="pre">consumed</span></code>, or <code class="docutils literal notranslate"><span class="pre">unconsumed</span></code>.</p>
+</div>
+<div class="section" id="param-typestate">
+<h3><a class="toc-backref" href="#id347">param_typestate</a><a class="headerlink" href="#param-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id170">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id170" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">param_typestate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::param_typestate</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies expectations about function parameters.  Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn’t in the expected state.  The attribute is also used to set the
+initial state of the parameter when analyzing the function’s body.</p>
+</div>
+<div class="section" id="return-typestate">
+<h3><a class="toc-backref" href="#id348">return_typestate</a><a class="headerlink" href="#return-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id171">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id171" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">return_typestate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::return_typestate</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">return_typestate</span></code> attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value.  The function’s body is checked to ensure that it always returns a value
+in the specified state.  On the caller side, values returned by the annotated
+function are initialized to the given state.</p>
+<p>When applied to a function parameter it modifies the state of an argument after
+a call to the function returns.  The function’s body is checked to ensure that
+the parameter is in the expected state before returning.</p>
+</div>
+<div class="section" id="set-typestate">
+<h3><a class="toc-backref" href="#id349">set_typestate</a><a class="headerlink" href="#set-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id172">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id172" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">set_typestate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::set_typestate</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Annotate methods that transition an object into a new state with
+<code class="docutils literal notranslate"><span class="pre">__attribute__((set_typestate(new_state)))</span></code>.  The new state must be
+unconsumed, consumed, or unknown.</p>
+</div>
+<div class="section" id="test-typestate">
+<h3><a class="toc-backref" href="#id350">test_typestate</a><a class="headerlink" href="#test-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id173">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id173" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">test_typestate</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::test_typestate</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((test_typestate(tested_state)))</span></code> to indicate that a method
+returns true if the object is in the specified state..</p>
+</div>
+</div>
+<div class="section" id="type-safety-checking">
+<h2><a class="toc-backref" href="#id351">Type Safety Checking</a><a class="headerlink" href="#type-safety-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes to enable checking type safety properties
+that can’t be enforced by the C type system. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:</p>
+<ul class="simple">
+<li>MPI library implementations, where these attributes enable checking that
+the buffer type matches the passed <code class="docutils literal notranslate"><span class="pre">MPI_Datatype</span></code>;</li>
+<li>for HDF5 library there is a similar use case to MPI;</li>
+<li>checking types of variadic functions’ arguments for functions like
+<code class="docutils literal notranslate"><span class="pre">fcntl()</span></code> and <code class="docutils literal notranslate"><span class="pre">ioctl()</span></code>.</li>
+</ul>
+<p>You can detect support for these attributes with <code class="docutils literal notranslate"><span class="pre">__has_attribute()</span></code>.  For
+example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#if defined(__has_attribute)</span>
+<span class="cp">#  if __has_attribute(argument_with_type_tag) && \</span>
+<span class="cp">      __has_attribute(pointer_with_type_tag) && \</span>
+<span class="cp">      __has_attribute(type_tag_for_datatype)</span>
+<span class="cp">#    define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))</span>
+<span class="cm">/* ... other macros ...  */</span>
+<span class="cp">#  endif</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if !defined(ATTR_MPI_PWT)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx)</span>
+<span class="cp">#endif</span>
+
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+    <span class="n">ATTR_MPI_PWT</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="section" id="argument-with-type-tag">
+<h3><a class="toc-backref" href="#id352">argument_with_type_tag</a><a class="headerlink" href="#argument-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id174">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id174" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">pointer_with_type_tag</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pointer_with_type_tag</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pointer_with_type_tag</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((argument_with_type_tag(arg_kind,</span> <span class="pre">arg_idx,</span>
+<span class="pre">type_tag_idx)))</span></code> on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.</p>
+<p>This attribute is primarily useful for checking arguments of variadic functions
+(<code class="docutils literal notranslate"><span class="pre">pointer_with_type_tag</span></code> can be used in most non-variadic cases).</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><code class="docutils literal notranslate"><span class="pre">arg_kind</span></code> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><code class="docutils literal notranslate"><span class="pre">arg_idx</span></code> provides the position of a function argument. The expected type of
+this function argument will be determined by the function argument specified
+by <code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code>. In the code example below, “3” means that the type of the
+function’s third argument will be determined by <code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code> provides the position of a function argument. This function
+argument will be a type tag. The type tag will determine the expected type of
+the argument specified by <code class="docutils literal notranslate"><span class="pre">arg_idx</span></code>. In the code example below, “2” means
+that the type tag associated with the function’s second argument should agree
+with the type of the argument specified by <code class="docutils literal notranslate"><span class="pre">arg_idx</span></code>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">fcntl</span><span class="p">(</span><span class="kt">int</span> <span class="n">fd</span><span class="p">,</span> <span class="kt">int</span> <span class="n">cmd</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">argument_with_type_tag</span><span class="p">(</span><span class="n">fcntl</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's second argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected type of the function's third argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-with-type-tag">
+<h3><a class="toc-backref" href="#id353">pointer_with_type_tag</a><a class="headerlink" href="#pointer-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id175">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id175" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">pointer_with_type_tag</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pointer_with_type_tag</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::argument_with_type_tag</span></code> <br/> <code class="docutils literal notranslate"><span class="pre">clang::pointer_with_type_tag</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__attribute__((pointer_with_type_tag(ptr_kind,</span> <span class="pre">ptr_idx,</span> <span class="pre">type_tag_idx)))</span></code>
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><code class="docutils literal notranslate"><span class="pre">ptr_kind</span></code> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code> provides the position of a function argument; this function
+argument will have a pointer type. The expected pointee type of this pointer
+type will be determined by the function argument specified by
+<code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code>. In the code example below, “1” means that the pointee type
+of the function’s first argument will be determined by <code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">type_tag_idx</span></code> provides the position of a function argument; this function
+argument will be a type tag. The type tag will determine the expected pointee
+type of the pointer argument specified by <code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code>. In the code example
+below, “3” means that the type tag associated with the function’s third
+argument should agree with the pointee type of the pointer argument specified
+by <code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's 3rd argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected pointee type of the function's 1st argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="type-tag-for-datatype">
+<h3><a class="toc-backref" href="#id354">type_tag_for_datatype</a><a class="headerlink" href="#type-tag-for-datatype" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id176">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id176" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">type_tag_for_datatype</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::type_tag_for_datatype</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">clang::type_tag_for_datatype</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When declaring a variable, use
+<code class="docutils literal notranslate"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></code> to create a type tag that
+is tied to the <code class="docutils literal notranslate"><span class="pre">type</span></code> argument given to the attribute.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><code class="docutils literal notranslate"><span class="pre">kind</span></code> is an identifier that should be used when annotating all applicable
+type tags.</li>
+<li><code class="docutils literal notranslate"><span class="pre">type</span></code> indicates the name of the type.</li>
+</ul>
+</dd>
+</dl>
+<p>Clang supports annotating type tags of two forms.</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><strong>Type tag that is a reference to a declared identifier.</strong>
+Use <code class="docutils literal notranslate"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></code> when declaring that
+identifier:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_int</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">));</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)</span>
+<span class="c1">// &mpi_datatype_int is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><strong>Type tag that is an integral literal.</strong>
+Declare a <code class="docutils literal notranslate"><span class="pre">static</span> <span class="pre">const</span></code> variable with an initializer value and attach
+<code class="docutils literal notranslate"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></code> on that declaration:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MPI_Datatype</span> <span class="n">mpi_datatype_int</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">))</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) 42)</span>
+<span class="c1">// The number 42 is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+<p>The <code class="docutils literal notranslate"><span class="pre">type_tag_for_datatype</span></code> attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+<code class="docutils literal notranslate"><span class="pre">arg_idx</span></code> or <code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code> is compared against the type associated with the type
+tag. (Recall that for the <code class="docutils literal notranslate"><span class="pre">argument_with_type_tag</span></code> attribute, the type of the
+function argument specified by <code class="docutils literal notranslate"><span class="pre">arg_idx</span></code> is compared against the type
+associated with the type tag. Also recall that for the <code class="docutils literal notranslate"><span class="pre">pointer_with_type_tag</span></code>
+attribute, the pointee type of the function argument specified by <code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code> is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">layout_compatible</span></code> will cause types to be compared according to
+layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+layout-compatibility rules for two standard-layout struct types and for two
+standard-layout union types). This is useful when creating a type tag
+associated with a struct or union type. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">internal_mpi_double_int</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">d</span><span class="p">;</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_double_int</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span>
+                    <span class="k">struct</span> <span class="n">internal_mpi_double_int</span><span class="p">,</span> <span class="n">layout_compatible</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)</span>
+
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// no warning because the</span>
+                                                 <span class="c1">// layout of my_pair is</span>
+                                                 <span class="c1">// compatible with that of</span>
+                                                 <span class="c1">// internal_mpi_double_int</span>
+
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">}</span>
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="o">*</span><span class="n">buffer2</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// warning because the</span>
+                                                  <span class="c1">// layout of my_int_pair</span>
+                                                  <span class="c1">// does not match that of</span>
+                                                  <span class="c1">// internal_mpi_double_int</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">must_be_null</span></code> specifies that the function argument specified by either
+<code class="docutils literal notranslate"><span class="pre">arg_idx</span></code> (for the <code class="docutils literal notranslate"><span class="pre">argument_with_type_tag</span></code> attribute) or <code class="docutils literal notranslate"><span class="pre">ptr_idx</span></code> (for
+the <code class="docutils literal notranslate"><span class="pre">pointer_with_type_tag</span></code> attribute) should be a null pointer constant.
+The second argument to the <code class="docutils literal notranslate"><span class="pre">type_tag_for_datatype</span></code> attribute is ignored. For
+example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_null</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span> <span class="kt">void</span><span class="p">,</span> <span class="n">must_be_null</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)</span>
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DATATYPE_NULL</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// warning: MPI_DATATYPE_NULL</span>
+                                                    <span class="c1">// was specified but buffer</span>
+                                                    <span class="c1">// is not a null pointer</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="nullability-attributes">
+<h2><a class="toc-backref" href="#id355">Nullability Attributes</a><a class="headerlink" href="#nullability-attributes" title="Permalink to this headline">¶</a></h2>
+<p>Whether a particular pointer may be “null” is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> and <code class="docutils literal notranslate"><span class="pre">returns_nonnull</span></code> attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (<code class="docutils literal notranslate"><span class="pre">_Nullable</span></code>) or cannot be null (<code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code>).</p>
+<p>The nullability (type) qualifiers express whether a value of a given pointer type can be null (the <code class="docutils literal notranslate"><span class="pre">_Nullable</span></code> qualifier), doesn’t have a defined meaning for null (the <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> qualifier), or for which the purpose of null is unclear (the <code class="docutils literal notranslate"><span class="pre">_Null_unspecified</span></code> qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> and <code class="docutils literal notranslate"><span class="pre">returns_nonnull</span></code> attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).</span>
+<span class="kt">int</span> <span class="nf">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">*</span><span class="n">ptr</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="c1">// 'ptr' may be null.</span>
+<span class="kt">int</span> <span class="nf">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">ptr</span> <span class="o">?</span> <span class="o">*</span><span class="nl">ptr</span> <span class="p">:</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="c1">// A nullable pointer to non-null pointers to const characters.</span>
+<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="nf">join_strings</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">strings</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">n</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:</p>
+<blockquote>
+<div><div class="highlight-objective-c notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="nc">NSView</span> : <span class="nc">NSResponder</span>
+  <span class="o">-</span> <span class="p">(</span><span class="n">nullable</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="nl">ancestorSharedWithView</span><span class="p">:(</span><span class="n">nonnull</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="n">aView</span><span class="p">;</span>
+  <span class="k">@property</span> <span class="p">(</span><span class="k">assign</span><span class="p">,</span> <span class="n">nullable</span><span class="p">)</span> <span class="n">NSView</span> <span class="o">*</span><span class="n">superview</span><span class="p">;</span>
+  <span class="k">@property</span> <span class="p">(</span><span class="k">readonly</span><span class="p">,</span> <span class="n">nonnull</span><span class="p">)</span> <span class="bp">NSArray</span> <span class="o">*</span><span class="n">subviews</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="nonnull">
+<h3><a class="toc-backref" href="#id356">_Nonnull</a><a class="headerlink" href="#nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id177">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id177" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> nullability qualifier indicates that null is not a meaningful value for a value of the <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> pointer type. For example, given a declaration such as:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <code class="docutils literal notranslate"><span class="pre">fetch</span></code> should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to <code class="docutils literal notranslate"><span class="pre">fetch</span></code>. Note that, unlike the declaration attribute <code class="docutils literal notranslate"><span class="pre">nonnull</span></code>, the presence of <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> does not imply that passing null is undefined behavior: <code class="docutils literal notranslate"><span class="pre">fetch</span></code> is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.</p>
+</div>
+<div class="section" id="null-unspecified">
+<h3><a class="toc-backref" href="#id357">_Null_unspecified</a><a class="headerlink" href="#null-unspecified" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id178">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id178" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">_Null_unspecified</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">_Null_unspecified</span></code> nullability qualifier indicates that neither the <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> nor <code class="docutils literal notranslate"><span class="pre">_Nullable</span></code> qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.</p>
+</div>
+<div class="section" id="nullable">
+<h3><a class="toc-backref" href="#id358">_Nullable</a><a class="headerlink" href="#nullable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id179">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id179" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><code class="docutils literal notranslate"><span class="pre">_Nullable</span></code></td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">_Nullable</span></code> nullability qualifier indicates that a value of the <code class="docutils literal notranslate"><span class="pre">_Nullable</span></code> pointer type can be null. For example, given:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <code class="docutils literal notranslate"><span class="pre">fetch_or_zero</span></code> can provide null.</p>
+</div>
+<div class="section" id="id15">
+<h3><a class="toc-backref" href="#id359">nonnull</a><a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id180">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id180" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">nonnull</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::nonnull</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> attribute indicates that some function parameters must not be null, and can be used in several different ways. It’s original usage (<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes">from GCC</a>) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+                <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Here, the <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+                <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Clang also allows the <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span>
+                         <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Note that the <code class="docutils literal notranslate"><span class="pre">nonnull</span></code> attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.</p>
+</div>
+<div class="section" id="returns-nonnull">
+<h3><a class="toc-backref" href="#id360">returns_nonnull</a><a class="headerlink" href="#returns-nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="id181">
+<caption><span class="caption-text">Supported Syntaxes</span><a class="headerlink" href="#id181" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">C2x</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">__declspec</span></code></th>
+<th class="head">Keyword</th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span></code></th>
+<th class="head"><code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">returns_nonnull</span></code></td>
+<td><code class="docutils literal notranslate"><span class="pre">gnu::returns_nonnull</span></code></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+<p>The <code class="docutils literal notranslate"><span class="pre">returns_nonnull</span></code> attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system <code class="docutils literal notranslate"><span class="pre">malloc</span></code> might be defined to terminate a process when memory is not available rather than returning a null pointer:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">malloc</span> <span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">returns_nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>The <code class="docutils literal notranslate"><span class="pre">returns_nonnull</span></code> attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+      
+        <p>
+        «  <a href="ClangCommandLineReference.html">Clang command line argument reference</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer" role="contentinfo">
+        © Copyright 2007-2019, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/9.0.0/tools/clang/docs/AutomaticReferenceCounting.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/AutomaticReferenceCounting.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/AutomaticReferenceCounting.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/AutomaticReferenceCounting.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,2161 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Objective-C Automatic Reference Counting (ARC) — Clang 9 documentation</title>
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Clang command line argument reference" href="ClangCommandLineReference.html" />
+    <link rel="prev" title="Block Implementation Specification" href="Block-ABI-Apple.html" /> 
+  </head><body>
+      <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+          <span>Clang 9 documentation</span></a></h1>
+        <h2 class="heading"><span>Objective-C Automatic Reference Counting (ARC)</span></h2>
+      </div>
+      <div class="topnav" role="navigation" aria-label="top navigation">
+      
+        <p>
+        «  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCommandLineReference.html">Clang command line argument reference</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <style>
+  .arc-term { font-style: italic; font-weight: bold; }
+  .revision { font-style: italic; }
+  .when-revised { font-weight: bold; font-style: normal; }
+
+  /*
+   * Automatic numbering is described in this article:
+   * https://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+   */
+  /*
+   * Automatic numbering for the TOC.
+   * This is wrong from the semantics point of view, since it is an ordered
+   * list, but uses "ul" tag.
+   */
+  div#contents.contents.local ul {
+    counter-reset: toc-section;
+    list-style-type: none;
+  }
+  div#contents.contents.local ul li {
+    counter-increment: toc-section;
+    background: none; // Remove bullets
+  }
+  div#contents.contents.local ul li a.reference:before {
+    content: counters(toc-section, ".") " ";
+  }
+
+  /* Automatic numbering for the body. */
+  body {
+    counter-reset: section subsection subsubsection;
+  }
+  .section h2 {
+    counter-reset: subsection subsubsection;
+    counter-increment: section;
+  }
+  .section h2 a.toc-backref:before {
+    content: counter(section) " ";
+  }
+  .section h3 {
+    counter-reset: subsubsection;
+    counter-increment: subsection;
+  }
+  .section h3 a.toc-backref:before {
+    content: counter(section) "." counter(subsection) " ";
+  }
+  .section h4 {
+    counter-increment: subsubsection;
+  }
+  .section h4 a.toc-backref:before {
+    content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+  }
+</style><div class="section" id="objective-c-automatic-reference-counting-arc">
+<h1>Objective-C Automatic Reference Counting (ARC)<a class="headerlink" href="#objective-c-automatic-reference-counting-arc" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#about-this-document" id="id4">About this document</a><ul>
+<li><a class="reference internal" href="#purpose" id="id5">Purpose</a></li>
+<li><a class="reference internal" href="#background" id="id6">Background</a></li>
+<li><a class="reference internal" href="#evolution" id="id7">Evolution</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#general" id="id8">General</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers" id="id9">Retainable object pointers</a><ul>
+<li><a class="reference internal" href="#retain-count-semantics" id="id10">Retain count semantics</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers-as-operands-and-arguments" id="id11">Retainable object pointers as operands and arguments</a><ul>
+<li><a class="reference internal" href="#consumed-parameters" id="id12">Consumed parameters</a></li>
+<li><a class="reference internal" href="#retained-return-values" id="id13">Retained return values</a></li>
+<li><a class="reference internal" href="#unretained-return-values" id="id14">Unretained return values</a></li>
+<li><a class="reference internal" href="#bridged-casts" id="id15">Bridged casts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#restrictions" id="id16">Restrictions</a><ul>
+<li><a class="reference internal" href="#conversion-of-retainable-object-pointers" id="id17">Conversion of retainable object pointers</a></li>
+<li><a class="reference internal" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" id="id18">Conversion to retainable object pointer type of expressions with known semantics</a></li>
+<li><a class="reference internal" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" id="id19">Conversion from retainable object pointer type in certain contexts</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-qualification" id="id20">Ownership qualification</a><ul>
+<li><a class="reference internal" href="#spelling" id="id21">Spelling</a><ul>
+<li><a class="reference internal" href="#property-declarations" id="id22">Property declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#semantics" id="id23">Semantics</a></li>
+<li><a class="reference internal" href="#arc-ownership-restrictions" id="id24">Restrictions</a><ul>
+<li><a class="reference internal" href="#weak-unavailable-types" id="id25">Weak-unavailable types</a></li>
+<li><a class="reference internal" href="#storage-duration-of-autoreleasing-objects" id="id26">Storage duration of <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> objects</a></li>
+<li><a class="reference internal" href="#conversion-of-pointers-to-ownership-qualified-types" id="id27">Conversion of pointers to ownership-qualified types</a></li>
+<li><a class="reference internal" href="#passing-to-an-out-parameter-by-writeback" id="id28">Passing to an out parameter by writeback</a></li>
+<li><a class="reference internal" href="#ownership-qualified-fields-of-structs-and-unions" id="id29">Ownership-qualified fields of structs and unions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-inference" id="id30">Ownership inference</a><ul>
+<li><a class="reference internal" href="#objects" id="id31">Objects</a></li>
+<li><a class="reference internal" href="#indirect-parameters" id="id32">Indirect parameters</a></li>
+<li><a class="reference internal" href="#template-arguments" id="id33">Template arguments</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#method-families" id="id34">Method families</a><ul>
+<li><a class="reference internal" href="#explicit-method-family-control" id="id35">Explicit method family control</a></li>
+<li><a class="reference internal" href="#semantics-of-method-families" id="id36">Semantics of method families</a><ul>
+<li><a class="reference internal" href="#semantics-of-init" id="id37">Semantics of <code class="docutils literal notranslate"><span class="pre">init</span></code></a></li>
+<li><a class="reference internal" href="#related-result-types" id="id38">Related result types</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimization" id="id39">Optimization</a><ul>
+<li><a class="reference internal" href="#object-liveness" id="id40">Object liveness</a></li>
+<li><a class="reference internal" href="#no-object-lifetime-extension" id="id41">No object lifetime extension</a></li>
+<li><a class="reference internal" href="#precise-lifetime-semantics" id="id42">Precise lifetime semantics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#miscellaneous" id="id43">Miscellaneous</a><ul>
+<li><a class="reference internal" href="#special-methods" id="id44">Special methods</a><ul>
+<li><a class="reference internal" href="#memory-management-methods" id="id45">Memory management methods</a></li>
+<li><a class="reference internal" href="#dealloc" id="id46"><code class="docutils literal notranslate"><span class="pre">dealloc</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#autoreleasepool" id="id47"><code class="docutils literal notranslate"><span class="pre">@autoreleasepool</span></code></a></li>
+<li><a class="reference internal" href="#externally-retained-variables" id="id48">Externally-Retained Variables</a></li>
+<li><a class="reference internal" href="#self" id="id49"><code class="docutils literal notranslate"><span class="pre">self</span></code></a></li>
+<li><a class="reference internal" href="#fast-enumeration-iteration-variables" id="id50">Fast enumeration iteration variables</a></li>
+<li><a class="reference internal" href="#blocks" id="id51">Blocks</a></li>
+<li><a class="reference internal" href="#exceptions" id="id52">Exceptions</a></li>
+<li><a class="reference internal" href="#interior-pointers" id="id53">Interior pointers</a></li>
+<li><a class="reference internal" href="#c-retainable-pointer-types" id="id54">C retainable pointer types</a><ul>
+<li><a class="reference internal" href="#auditing-of-c-retainable-pointer-interfaces" id="id55">Auditing of C retainable pointer interfaces</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-support" id="id56">Runtime support</a><ul>
+<li><a class="reference internal" href="#arc-runtime-objc-autorelease" id="id57"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpop-void-pool" id="id58"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpush-void" id="id59"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue" id="id60"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-copyweak-id-dest-id-src" id="id61"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-destroyweak-id-object" id="id62"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-initweak" id="id63"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweak" id="id64"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweakretained" id="id65"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-moveweak-id-dest-id-src" id="id66"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-release-id-value" id="id67"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retain" id="id68"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautorelease" id="id69"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasereturnvalue" id="id70"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue" id="id71"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainblock" id="id72"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#void-objc-storestrong-id-object-id-value" id="id73"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storeweak" id="id74"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="about-this-document">
+<span id="arc-meta"></span><h2><a class="toc-backref" href="#id4">About this document</a><a class="headerlink" href="#about-this-document" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="purpose">
+<span id="arc-meta-purpose"></span><h3><a class="toc-backref" href="#id5">Purpose</a><a class="headerlink" href="#purpose" title="Permalink to this headline">¶</a></h3>
+<p>The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting.  Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.</p>
+<p>The secondary purpose is to act as a rationale for why ARC was designed in this
+way.  This should remain tightly focused on the technical design and should not
+stray into marketing speculation.</p>
+</div>
+<div class="section" id="background">
+<span id="arc-meta-background"></span><h3><a class="toc-backref" href="#id6">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3>
+<p>This document assumes a basic familiarity with C.</p>
+<p><span class="arc-term">Blocks</span> are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using <span class="arc-term">block
+pointers</span>, which are represented like a normal pointer.  A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated.  The initial allocation is done on the stack, but the runtime
+provides a <code class="docutils literal notranslate"><span class="pre">Block_copy</span></code> function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1.  The paired function is
+<code class="docutils literal notranslate"><span class="pre">Block_release</span></code>, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.</p>
+<p>Objective-C is a set of language extensions, significant enough to be
+considered a different language.  It is a strict superset of C.  The extensions
+can also be imposed on C++, producing a language called Objective-C++.  The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.</p>
+<p>Objective-C defines a new type kind, collectively called the <span class="arc-term">object
+pointer types</span>.  This kind has two notable builtin members, <code class="docutils literal notranslate"><span class="pre">id</span></code> and
+<code class="docutils literal notranslate"><span class="pre">Class</span></code>; <code class="docutils literal notranslate"><span class="pre">id</span></code> is the final supertype of all object pointers.  The validity
+of conversions between object pointer types is not checked at runtime.  Users
+may define <span class="arc-term">classes</span>; each class is a type, and the pointer to that
+type is an object pointer type.  A class may have a superclass; its pointer
+type is a subtype of its superclass’s pointer type.  A class has a set of
+<span class="arc-term">ivars</span>, fields which appear on all instances of that class.  For
+every class <em>T</em> there’s an associated metaclass; it has no fields, its
+superclass is the metaclass of <em>T</em>’s superclass, and its metaclass is a global
+class.  Every class has a global object whose class is the class’s metaclass;
+metaclasses have no associated type, so pointers to this object have type
+<code class="docutils literal notranslate"><span class="pre">Class</span></code>.</p>
+<p>A class declaration (<code class="docutils literal notranslate"><span class="pre">@interface</span></code>) declares a set of <span class="arc-term">methods</span>.  A
+method has a return type, a list of argument types, and a <span class="arc-term">selector</span>:
+a name like <code class="docutils literal notranslate"><span class="pre">foo:bar:baz:</span></code>, where the number of colons corresponds to the
+number of formal arguments.  A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass.  A method may be invoked by
+providing an object (called the <span class="arc-term">receiver</span>) and a list of formal
+arguments interspersed with the selector, like so:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">receiver</span> <span class="nl">foo</span><span class="p">:</span> <span class="n">fooArg</span> <span class="nl">bar</span><span class="p">:</span> <span class="n">barArg</span> <span class="nl">baz</span><span class="p">:</span> <span class="n">bazArg</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>This looks in the dynamic class of the receiver for a method with this name,
+then in that class’s superclass, etc., until it finds something it can execute.
+The receiver “expression” may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be <code class="docutils literal notranslate"><span class="pre">super</span></code>, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class.  The actual methods
+dynamically found in a class are not those declared in the <code class="docutils literal notranslate"><span class="pre">@interface</span></code>, but
+those defined in a separate <code class="docutils literal notranslate"><span class="pre">@implementation</span></code> declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+<code class="docutils literal notranslate"><span class="pre">@interface</span></code>.</p>
+<p>Method declarations may also be grouped into <span class="arc-term">protocols</span>, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.</p>
+<p><span class="arc-term">Class extensions</span> are collections of ivars and methods, designed to
+allow a class’s <code class="docutils literal notranslate"><span class="pre">@interface</span></code> to be split across multiple files; however,
+there is still a primary implementation file which must see the
+<code class="docutils literal notranslate"><span class="pre">@interface</span></code>s of all class extensions.  <span class="arc-term">Categories</span> allow
+methods (but not ivars) to be declared <em>post hoc</em> on an arbitrary class; the
+methods in the category’s <code class="docutils literal notranslate"><span class="pre">@implementation</span></code> will be dynamically added to that
+class’s method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.</p>
+<p>In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count.  This is done using two
+instance methods which all classes are expected to implement: <code class="docutils literal notranslate"><span class="pre">retain</span></code>
+increases the object’s reference count by 1, whereas <code class="docutils literal notranslate"><span class="pre">release</span></code> decreases it
+by 1 and calls the instance method <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> if the count reaches 0.  To
+simplify certain operations, there is also an <span class="arc-term">autorelease pool</span>, a
+thread-local list of objects to call <code class="docutils literal notranslate"><span class="pre">release</span></code> on later; an object can be
+added to this pool by calling <code class="docutils literal notranslate"><span class="pre">autorelease</span></code> on it.</p>
+<p>Block pointers may be converted to type <code class="docutils literal notranslate"><span class="pre">id</span></code>; block objects are laid out in a
+way that makes them compatible with Objective-C objects.  There is a builtin
+class that all block objects are considered to be objects of; this class
+implements <code class="docutils literal notranslate"><span class="pre">retain</span></code> by adjusting the reference count, not by calling
+<code class="docutils literal notranslate"><span class="pre">Block_copy</span></code>.</p>
+</div>
+<div class="section" id="evolution">
+<span id="arc-meta-evolution"></span><h3><a class="toc-backref" href="#id7">Evolution</a><a class="headerlink" href="#evolution" title="Permalink to this headline">¶</a></h3>
+<p>ARC is under continual evolution, and this document must be updated as the
+language progresses.</p>
+<p>If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:</p>
+<blockquote>
+<div>ARC applies to Objective-C pointer types, block pointer types, and
+<span class="when-revised">[beginning Apple 8.0, LLVM 3.8]</span> <span class="revision">BPTRs declared
+within</span> <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">"BCPL"</span></code> blocks.</div></blockquote>
+<p>For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang.  “LLVM X.Y” refers to an
+open-source release of clang from the LLVM project.  “Apple X.Y” refers to an
+Apple-provided release of the Apple LLVM Compiler.  Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.</p>
+<p>If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions.  Such
+changes are generally to be avoided.</p>
+</div>
+</div>
+<div class="section" id="general">
+<span id="arc-general"></span><h2><a class="toc-backref" href="#id8">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
+<p>Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases.  It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.</p>
+<p>ARC may be explicitly enabled with the compiler flag <code class="docutils literal notranslate"><span class="pre">-fobjc-arc</span></code>.  It may
+also be explicitly disabled with the compiler flag <code class="docutils literal notranslate"><span class="pre">-fno-objc-arc</span></code>.  The last
+of these two flags appearing on the compile line “wins”.</p>
+<p>If ARC is enabled, <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_arc)</span></code> will expand to 1 in the
+preprocessor.  For more information about <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code>, see the
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><span class="std std-ref">language extensions</span></a> document.</p>
+</div>
+<div class="section" id="retainable-object-pointers">
+<span id="arc-objects"></span><h2><a class="toc-backref" href="#id9">Retainable object pointers</a><a class="headerlink" href="#retainable-object-pointers" title="Permalink to this headline">¶</a></h2>
+<p>This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC.  Note in particular that it
+covers the rules for pointer <em>values</em> (patterns of bits indicating the location
+of a pointed-to object), not pointer <em>objects</em> (locations in memory which store
+pointer values).  The rules for objects are covered in the next section.</p>
+<p>A <span class="arc-term">retainable object pointer</span> (or “retainable pointer”) is a value of
+a <span class="arc-term">retainable object pointer type</span> (“retainable type”).  There are
+three kinds of retainable object pointer types:</p>
+<ul class="simple">
+<li>block pointers (formed by applying the caret (<code class="docutils literal notranslate"><span class="pre">^</span></code>) declarator sigil to a
+function type)</li>
+<li>Objective-C object pointers (<code class="docutils literal notranslate"><span class="pre">id</span></code>, <code class="docutils literal notranslate"><span class="pre">Class</span></code>, <code class="docutils literal notranslate"><span class="pre">NSFoo*</span></code>, etc.)</li>
+<li>typedefs marked with <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code></li>
+</ul>
+<p>Other pointer types, such as <code class="docutils literal notranslate"><span class="pre">int*</span></code> and <code class="docutils literal notranslate"><span class="pre">CFStringRef</span></code>, are not subject to
+ARC’s semantics and restrictions.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>We are not at liberty to require all code to be recompiled with ARC;
+therefore, ARC must interoperate with Objective-C code which manages retains
+and releases manually.  In general, there are three requirements in order for
+a compiler-supported reference-count system to provide reliable
+interoperation:</p>
+<ul class="last simple">
+<li>The type system must reliably identify which objects are to be managed.  An
+<code class="docutils literal notranslate"><span class="pre">int*</span></code> might be a pointer to a <code class="docutils literal notranslate"><span class="pre">malloc</span></code>’ed array, or it might be an
+interior pointer to such an array, or it might point to some field or local
+variable.  In contrast, values of the retainable object pointer types are
+never interior.</li>
+<li>The type system must reliably indicate how to manage objects of a type.
+This usually means that the type must imply a procedure for incrementing
+and decrementing retain counts.  Supporting single-ownership objects
+requires a lot more explicit mediation in the language.</li>
+<li>There must be reliable conventions for whether and when “ownership” is
+passed between caller and callee, for both arguments and return values.
+Objective-C methods follow such a convention very reliably, at least for
+system libraries on macOS, and functions always pass objects at +0.  The
+C-based APIs for Core Foundation objects, on the other hand, have much more
+varied transfer semantics.</li>
+</ul>
+</div>
+<p>The use of <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> typedefs is not recommended.  If it’s
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+<code class="docutils literal notranslate"><span class="pre">__typeof</span></code> and C++ template argument substitution.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Any compiler operation which incidentally strips type “sugar” from a type
+will yield a type without the attribute, which may result in unexpected
+behavior.</p>
+</div>
+<div class="section" id="retain-count-semantics">
+<span id="arc-objects-retains"></span><h3><a class="toc-backref" href="#id10">Retain count semantics</a><a class="headerlink" href="#retain-count-semantics" title="Permalink to this headline">¶</a></h3>
+<p>A retainable object pointer is either a <span class="arc-term">null pointer</span> or a pointer
+to a valid object.  Furthermore, if it has block pointer type and is not
+<code class="docutils literal notranslate"><span class="pre">null</span></code> then it must actually be a pointer to a block object, and if it has
+<code class="docutils literal notranslate"><span class="pre">Class</span></code> type (possibly protocol-qualified) then it must actually be a pointer
+to a class object.  Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.</p>
+<p>For ARC’s purposes, a valid object is one with “well-behaved” retaining
+operations.  Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">retain</span></code>, taking no arguments and returning a pointer to the object.</li>
+<li><code class="docutils literal notranslate"><span class="pre">release</span></code>, taking no arguments and returning <code class="docutils literal notranslate"><span class="pre">void</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">autorelease</span></code>, taking no arguments and returning a pointer to the object.</li>
+</ul>
+<p>The behavior of these methods is constrained in the following ways.  The term
+<span class="arc-term">high-level semantics</span> is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements.  For example, if the user puts logging statements
+in <code class="docutils literal notranslate"><span class="pre">retain</span></code>, they should not be surprised if those statements are executed
+more or less often depending on optimization settings.  These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.</p>
+<p>It is undefined behavior if a computation history featuring a send of
+<code class="docutils literal notranslate"><span class="pre">retain</span></code> followed by a send of <code class="docutils literal notranslate"><span class="pre">release</span></code> to the same object, with no
+intervening <code class="docutils literal notranslate"><span class="pre">release</span></code> on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed.  Note that
+this implies that these methods may not raise exceptions.</p>
+<p>It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of <code class="docutils literal notranslate"><span class="pre">release</span></code> that is not
+preceded by a send of <code class="docutils literal notranslate"><span class="pre">retain</span></code> to the same object.</p>
+<p>The behavior of <code class="docutils literal notranslate"><span class="pre">autorelease</span></code> must be equivalent to sending <code class="docutils literal notranslate"><span class="pre">release</span></code> when
+one of the autorelease pools currently in scope is popped.  It may not throw an
+exception.</p>
+<p>When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is <code class="docutils literal notranslate"><span class="pre">null</span></code> then the effect is a no-op.</p>
+<p>All of the semantics described in this document are subject to additional
+<a class="reference internal" href="#arc-optimization"><span class="std std-ref">optimization rules</span></a> which permit the removal or
+optimization of operations based on local knowledge of data flow.  The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.</p>
+</div>
+<div class="section" id="retainable-object-pointers-as-operands-and-arguments">
+<span id="arc-objects-operands"></span><h3><a class="toc-backref" href="#id11">Retainable object pointers as operands and arguments</a><a class="headerlink" href="#retainable-object-pointers-as-operands-and-arguments" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression.  This includes:</p>
+<ul class="simple">
+<li>loading a retainable pointer from an object with non-weak <a class="reference internal" href="#arc-ownership"><span class="std std-ref">ownership</span></a>,</li>
+<li>passing a retainable pointer as an argument to a function or method, and</li>
+<li>receiving a retainable pointer as the result of a function or method call.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While this might seem uncontroversial, it is actually unsafe when multiple
+expressions are evaluated in “parallel”, as with binary operators and calls,
+because (for example) one expression might load from an object while another
+writes to it.  However, C and C++ already call this undefined behavior
+because the evaluations are unsequenced, and ARC simply exploits that here to
+avoid needing to retain arguments across a large number of calls.</p>
+</div>
+<p>The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.</p>
+<div class="section" id="consumed-parameters">
+<span id="arc-objects-operands-consumed"></span><h4><a class="toc-backref" href="#id12">Consumed parameters</a><a class="headerlink" href="#consumed-parameters" title="Permalink to this headline">¶</a></h4>
+<p>A function or method parameter of retainable object pointer type may be marked
+as <span class="arc-term">consumed</span>, signifying that the callee expects to take ownership
+of a +1 retain count.  This is done by adding the <code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code> attribute to
+the parameter declaration, like so:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="kt">id</span> <span class="n">x</span><span class="p">);</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">foo:</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nv">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="nv">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method, not the type of
+the parameter.  It controls only how the argument is passed and received.</p>
+<p>When passing such an argument, ARC retains the argument prior to making the
+call.</p>
+<p>When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a caller to a callee.  The
+most common scenario here is passing the <code class="docutils literal notranslate"><span class="pre">self</span></code> parameter to <code class="docutils literal notranslate"><span class="pre">init</span></code>, but
+it is useful to generalize.  Typically, local optimization will remove any
+extra retains and releases: on the caller side the retain will be merged with
+a +1 source, and on the callee side the release will be rolled into the
+initialization of the parameter.</p>
+</div>
+<p>The implicit <code class="docutils literal notranslate"><span class="pre">self</span></code> parameter of a method may be marked as consumed by adding
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_consumes_self))</span></code> to the method declaration.  Methods in
+the <code class="docutils literal notranslate"><span class="pre">init</span></code> <a class="reference internal" href="#arc-method-families"><span class="std std-ref">family</span></a> are treated as if they were
+implicitly marked with this attribute.</p>
+<p>It is undefined behavior if an Objective-C message send to a method with
+<code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code> parameters (other than self) is made with a null receiver.  It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of <code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code> parameters than
+the method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with a different set of
+<code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code> parameters than the implementation of the called block or
+function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters with null receiver are a guaranteed leak.  Mismatches
+with consumed parameters will cause over-retains or over-releases, depending
+on the direction.  The rule about function calls is really just an
+application of the existing C/C++ rule about calling functions through an
+incompatible function type, but it’s useful to state it explicitly.</p>
+</div>
+</div>
+<div class="section" id="retained-return-values">
+<span id="arc-object-operands-retained-return-values"></span><h4><a class="toc-backref" href="#id13">Retained return values</a><a class="headerlink" href="#retained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count.  This is done by adding the
+<code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code> attribute to the function or method declaration, like
+so:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nf">foo</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.</p>
+<p>When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a callee to a caller.  The
+most common scenario this models is the retained return from <code class="docutils literal notranslate"><span class="pre">init</span></code>,
+<code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">new</span></code>, and <code class="docutils literal notranslate"><span class="pre">copy</span></code> methods, but there are other cases in the
+frameworks.  After optimization there are typically no extra retains and
+releases required.</p>
+</div>
+<p>Methods in the <code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">copy</span></code>, <code class="docutils literal notranslate"><span class="pre">init</span></code>, <code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal notranslate"><span class="pre">new</span></code>
+<a class="reference internal" href="#arc-method-families"><span class="std std-ref">families</span></a> are implicitly marked
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_retained))</span></code>.  This may be suppressed by explicitly
+marking the method <code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>.</p>
+<p>It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Mismatches with returned results will cause over-retains or over-releases,
+depending on the direction.  Again, the rule about function calls is really
+just an application of the existing C/C++ rule about calling functions
+through an incompatible function type.</p>
+</div>
+</div>
+<div class="section" id="unretained-return-values">
+<span id="arc-objects-operands-unretained-returns"></span><h4><a class="toc-backref" href="#id14">Unretained return values</a><a class="headerlink" href="#unretained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary.  In the worst case, this may involve an <code class="docutils literal notranslate"><span class="pre">autorelease</span></code>, but
+callers must not assume that the value is actually in the autorelease pool.</p>
+<p>ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">It is common in non-ARC code to not return an autoreleased value; therefore
+the convention does not force either path.  It is convenient to not be
+required to do unnecessary retains and autoreleases; this permits
+optimizations such as eliding retain/autoreleases when it can be shown that
+the original pointer will still be valid at the point of return.</p>
+</div>
+<p>A method or function may be marked with
+<code class="docutils literal notranslate"><span class="pre">__attribute__((ns_returns_autoreleased))</span></code> to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool.  There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.</p>
+</div>
+<div class="section" id="bridged-casts">
+<span id="arc-objects-operands-casts"></span><h4><a class="toc-backref" href="#id15">Bridged casts</a><a class="headerlink" href="#bridged-casts" title="Permalink to this headline">¶</a></h4>
+<p>A <span class="arc-term">bridged cast</span> is a C-style cast annotated with one of three
+keywords:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">(__bridge</span> <span class="pre">T)</span> <span class="pre">op</span></code> casts the operand to the destination type <code class="docutils literal notranslate"><span class="pre">T</span></code>.  If
+<code class="docutils literal notranslate"><span class="pre">T</span></code> is a retainable object pointer type, then <code class="docutils literal notranslate"><span class="pre">op</span></code> must have a
+non-retainable pointer type.  If <code class="docutils literal notranslate"><span class="pre">T</span></code> is a non-retainable pointer type,
+then <code class="docutils literal notranslate"><span class="pre">op</span></code> must have a retainable object pointer type.  Otherwise the cast
+is ill-formed.  There is no transfer of ownership, and ARC inserts no retain
+operations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">(__bridge_retained</span> <span class="pre">T)</span> <span class="pre">op</span></code> casts the operand, which must have retainable
+object pointer type, to the destination type, which must be a non-retainable
+pointer type.  ARC retains the value, subject to the usual optimizations on
+local values, and the recipient is responsible for balancing that +1.</li>
+<li><code class="docutils literal notranslate"><span class="pre">(__bridge_transfer</span> <span class="pre">T)</span> <span class="pre">op</span></code> casts the operand, which must have
+non-retainable pointer type, to the destination type, which must be a
+retainable object pointer type.  ARC will release the value at the end of
+the enclosing full-expression, subject to the usual optimizations on local
+values.</li>
+</ul>
+<p>These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on <a class="reference internal" href="#arc-objects-restrictions-conversion"><span class="std std-ref">conversion of retainable
+object pointers</span></a>.</p>
+<p>Using a <code class="docutils literal notranslate"><span class="pre">__bridge_retained</span></code> or <code class="docutils literal notranslate"><span class="pre">__bridge_transfer</span></code> cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.</p>
+</div>
+</div>
+<div class="section" id="restrictions">
+<span id="arc-objects-restrictions"></span><h3><a class="toc-backref" href="#id16">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="conversion-of-retainable-object-pointers">
+<span id="arc-objects-restrictions-conversion"></span><h4><a class="toc-backref" href="#id17">Conversion of retainable object pointers</a><a class="headerlink" href="#conversion-of-retainable-object-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed.  For example, an Objective-C object pointer shall
+not be converted to <code class="docutils literal notranslate"><span class="pre">void*</span></code>.  As an exception, cast to <code class="docutils literal notranslate"><span class="pre">intptr_t</span></code> is
+allowed because such casts are not transferring ownership.  The <a class="reference internal" href="#arc-objects-operands-casts"><span class="std std-ref">bridged
+casts</span></a> may be used to perform these conversions
+where necessary.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">We cannot ensure the correct management of the lifetime of objects if they
+may be freely passed around as unmanaged types.  The bridged casts are
+provided so that the programmer may explicitly describe whether the cast
+transfers control into or out of ARC.</p>
+</div>
+<p>However, the following exceptions apply.</p>
+</div>
+<div class="section" id="conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics">
+<span id="arc-objects-restrictions-conversion-with-known-semantics"></span><h4><a class="toc-backref" href="#id18">Conversion to retainable object pointer type of expressions with known semantics</a><a class="headerlink" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span>
+<span class="revision">These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.</span></p>
+<p>An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.</p>
+<p>An expression is <span class="arc-term">known retain-agnostic</span> if it is:</p>
+<ul class="simple">
+<li>an Objective-C string literal,</li>
+<li>a load from a <code class="docutils literal notranslate"><span class="pre">const</span></code> system global variable of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer
+type</span></a>, or</li>
+<li>a null pointer constant.</li>
+</ul>
+<p>An expression is <span class="arc-term">known unretained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C
+retainable pointer type</span></a> and it is:</p>
+<ul class="simple">
+<li>a direct call to a function, and either that function has the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code> attribute or it is an <a class="reference internal" href="#arc-misc-c-retainable-audit"><span class="std std-ref">audited</span></a> function that does not have the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code> attribute and does not follow the create/copy naming
+convention,</li>
+<li>a message send, and the declared method either has the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code> attribute or it has neither the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code> attribute nor a <a class="reference internal" href="#arc-method-families"><span class="std std-ref">selector family</span></a> that implies a retained result, or</li>
+<li><span class="when-revised">[beginning LLVM 3.6]</span> <span class="revision">a load from a</span> <code class="docutils literal notranslate"><span class="pre">const</span></code>
+<span class="revision">non-system global variable.</span></li>
+</ul>
+<p>An expression is <span class="arc-term">known retained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C
+retainable pointer type</span></a> and it is:</p>
+<ul class="simple">
+<li>a message send, and the declared method either has the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code> attribute, or it does not have the
+<code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code> attribute but it does have a <a class="reference internal" href="#arc-method-families"><span class="std std-ref">selector
+family</span></a> that implies a retained result.</li>
+</ul>
+<p>Furthermore:</p>
+<ul class="simple">
+<li>a comma expression is classified according to its right-hand side,</li>
+<li>a statement expression is classified according to its result expression, if
+it has one,</li>
+<li>an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+classified according to the underlying message send, and</li>
+<li>a conditional operator is classified according to its second and third
+operands, if they agree in classification, or else the other if one is known
+retain-agnostic.</li>
+</ul>
+<p>If the cast operand is known retained, the conversion is treated as a
+<code class="docutils literal notranslate"><span class="pre">__bridge_transfer</span></code> cast.  If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a <code class="docutils literal notranslate"><span class="pre">__bridge</span></code> cast.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Bridging casts are annoying.  Absent the ability to completely automate the
+management of CF objects, however, we are left with relatively poor attempts
+to reduce the need for a glut of explicit bridges.  Hence these rules.</p>
+<p>We’ve so far consciously refrained from implicitly turning retained CF
+results from function calls into <code class="docutils literal notranslate"><span class="pre">__bridge_transfer</span></code> casts.  The worry is
+that some code patterns  —  for example, creating a CF value, assigning it
+to an ObjC-typed local, and then calling <code class="docutils literal notranslate"><span class="pre">CFRelease</span></code> when done  —  are a
+bit too likely to be accidentally accepted, leading to mysterious behavior.</p>
+<p class="last">For loads from <code class="docutils literal notranslate"><span class="pre">const</span></code> global variables of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer type</span></a>, it is reasonable to assume that global system
+constants were initialitzed with true constants (e.g. string literals), but
+user constants might have been initialized with something dynamically
+allocated, using a global initializer.</p>
+</div>
+</div>
+<div class="section" id="conversion-from-retainable-object-pointer-type-in-certain-contexts">
+<span id="arc-objects-restrictions-conversion-exception-contextual"></span><h4><a class="toc-backref" href="#id19">Conversion from retainable object pointer type in certain contexts</a><a class="headerlink" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>If an expression of retainable object pointer type is explicitly cast to a
+<a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer type</span></a>, the program is
+ill-formed as discussed above unless the result is immediately used:</p>
+<ul class="simple">
+<li>to initialize a parameter in an Objective-C message send where the parameter
+is not marked with the <code class="docutils literal notranslate"><span class="pre">cf_consumed</span></code> attribute, or</li>
+<li>to initialize a parameter in a direct call to an
+<a class="reference internal" href="#arc-misc-c-retainable-audit"><span class="std std-ref">audited</span></a> function where the parameter is
+not marked with the <code class="docutils literal notranslate"><span class="pre">cf_consumed</span></code> attribute.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters are left out because ARC would naturally balance them
+with a retain, which was judged too treacherous.  This is in part because
+several of the most common consuming functions are in the <code class="docutils literal notranslate"><span class="pre">Release</span></code> family,
+and it would be quite unfortunate for explicit releases to be silently
+balanced out in this way.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-qualification">
+<span id="arc-ownership"></span><h2><a class="toc-backref" href="#id20">Ownership qualification</a><a class="headerlink" href="#ownership-qualification" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the behavior of <em>objects</em> of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.</p>
+<p>A type is a <span class="arc-term">retainable object owner type</span> if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.</p>
+<p>An <span class="arc-term">ownership qualifier</span> is a type qualifier which applies only to
+retainable object owner types.  An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.</p>
+<p>A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.</p>
+<p>When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.</p>
+<p>Except as described under the <a class="reference internal" href="#arc-ownership-inference"><span class="std std-ref">inference rules</span></a>,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules, together with the inference rules, ensure that all objects and
+lvalues of retainable object pointer type have an ownership qualifier.  The
+ability to override an ownership qualifier during template substitution is
+required to counteract the <a class="reference internal" href="#arc-ownership-inference-template-arguments"><span class="std std-ref">inference of __strong for template type
+arguments</span></a>.  Ownership qualifiers
+on return types are dropped because they serve no purpose there except to
+cause spurious problems with overloading and templates.</p>
+</div>
+<p>There are four ownership qualifiers:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__strong</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__weak</span></code></li>
+</ul>
+<p>A type is <span class="arc-term">nontrivially ownership-qualified</span> if it is qualified with
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code>, <code class="docutils literal notranslate"><span class="pre">__strong</span></code>, or <code class="docutils literal notranslate"><span class="pre">__weak</span></code>.</p>
+<div class="section" id="spelling">
+<span id="arc-ownership-spelling"></span><h3><a class="toc-backref" href="#id21">Spelling</a><a class="headerlink" href="#spelling" title="Permalink to this headline">¶</a></h3>
+<p>The names of the ownership qualifiers are reserved for the implementation.  A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.</p>
+<p>An ownership qualifier may be written anywhere that any other type qualifier
+may be written.</p>
+<p>If an ownership qualifier appears in the <em>declaration-specifiers</em>, the
+following rules apply:</p>
+<ul class="simple">
+<li>if the type specifier is a retainable object owner type, the qualifier
+initially applies to that type;</li>
+<li>otherwise, if the outermost non-array declarator is a pointer
+or block pointer declarator, the qualifier initially applies to
+that type;</li>
+<li>otherwise the program is ill-formed.</li>
+<li>If the qualifier is so applied at a position in the declaration
+where the next-innermost declarator is a function declarator, and
+there is an block declarator within that function declarator, then
+the qualifier applies instead to that block declarator and this rule
+is considered afresh beginning from the new position.</li>
+</ul>
+<p>If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.</p>
+<p>If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Ownership qualifiers are like <code class="docutils literal notranslate"><span class="pre">const</span></code> and <code class="docutils literal notranslate"><span class="pre">volatile</span></code> in the sense
+that they may sensibly apply at multiple distinct positions within a
+declarator.  However, unlike those qualifiers, there are many
+situations where they are not meaningful, and so we make an effort
+to “move” the qualifier to a place where it will be meaningful.  The
+general goal is to allow the programmer to write, say, <code class="docutils literal notranslate"><span class="pre">__strong</span></code>
+before the entire declaration and have it apply in the leftmost
+sensible place.</p>
+</div>
+<div class="section" id="property-declarations">
+<span id="arc-ownership-spelling-property"></span><h4><a class="toc-backref" href="#id22">Property declarations</a><a class="headerlink" href="#property-declarations" title="Permalink to this headline">¶</a></h4>
+<p>A property of retainable object pointer type may have ownership.  If the
+property’s type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership.  A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> ownership.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">assign</span></code> implies <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> ownership.</li>
+<li><code class="docutils literal notranslate"><span class="pre">copy</span></code> implies <code class="docutils literal notranslate"><span class="pre">__strong</span></code> ownership, as well as the usual behavior of
+copy semantics on the setter.</li>
+<li><code class="docutils literal notranslate"><span class="pre">retain</span></code> implies <code class="docutils literal notranslate"><span class="pre">__strong</span></code> ownership.</li>
+<li><code class="docutils literal notranslate"><span class="pre">strong</span></code> implies <code class="docutils literal notranslate"><span class="pre">__strong</span></code> ownership.</li>
+<li><code class="docutils literal notranslate"><span class="pre">unsafe_unretained</span></code> implies <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> ownership.</li>
+<li><code class="docutils literal notranslate"><span class="pre">weak</span></code> implies <code class="docutils literal notranslate"><span class="pre">__weak</span></code> ownership.</li>
+</ul>
+<p>With the exception of <code class="docutils literal notranslate"><span class="pre">weak</span></code>, these modifiers are available in non-ARC
+modes.</p>
+<p>A property’s specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized.  If a
+property is synthesized, then the <span class="arc-term">associated instance variable</span> is
+the instance variable which is named, possibly implicitly, by the
+<code class="docutils literal notranslate"><span class="pre">@synthesize</span></code> declaration.  If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.</p>
+<p>A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, <span class="when-revised">[beginning Apple 3.1, LLVM 3.1]</span>
+<span class="revision">its ownership is implicitly</span> <code class="docutils literal notranslate"><span class="pre">strong</span></code>.  Prior to this revision, it
+was ill-formed to synthesize such a property.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Using <code class="docutils literal notranslate"><span class="pre">strong</span></code> by default is safe and consistent with the generic ARC rule
+about <a class="reference internal" href="#arc-ownership-inference-variables"><span class="std std-ref">inferring ownership</span></a>.  It is,
+unfortunately, inconsistent with the non-ARC rule which states that such
+properties are implicitly <code class="docutils literal notranslate"><span class="pre">assign</span></code>.  However, that rule is clearly
+untenable in ARC, since it leads to default-unsafe code.  The main merit to
+banning the properties is to avoid confusion with non-ARC practice, which did
+not ultimately strike us as sufficient to justify requiring extra syntax and
+(more importantly) forcing novices to understand ownership rules just to
+declare a property when the default is so reasonable.  Changing the rule away
+from non-ARC practice was acceptable because we had conservatively banned the
+synthesis in order to give ourselves exactly this leeway.</p>
+</div>
+<p>Applying <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than <code class="docutils literal notranslate"><span class="pre">assign</span></code>.  These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.</p>
+</div>
+</div>
+<div class="section" id="semantics">
+<span id="arc-ownership-semantics"></span><h3><a class="toc-backref" href="#id23">Semantics</a><a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h3>
+<p>There are five <span class="arc-term">managed operations</span> which may be performed on an
+object of retainable object pointer type.  Each qualifier specifies different
+semantics for each of these operations.  It is still undefined behavior to
+access an object outside of its lifetime.</p>
+<p>A load or store with “primitive semantics” has the same semantics as the
+respective operation would have on an <code class="docutils literal notranslate"><span class="pre">void*</span></code> lvalue with the same alignment
+and non-ownership qualification.</p>
+<p><span class="arc-term">Reading</span> occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.</p>
+<ul class="simple">
+<li>For <code class="docutils literal notranslate"><span class="pre">__weak</span></code> objects, the current pointee is retained and then released at
+the end of the current full-expression.  This must execute atomically with
+respect to assignments and to the final release of the pointee.</li>
+<li>For all other objects, the lvalue is loaded with primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Assignment</span> occurs when evaluating an assignment operator.  The
+semantics vary based on the qualification:</p>
+<ul class="simple">
+<li>For <code class="docutils literal notranslate"><span class="pre">__strong</span></code> objects, the new pointee is first retained; second, the
+lvalue is loaded with primitive semantics; third, the new pointee is stored
+into the lvalue with primitive semantics; and finally, the old pointee is
+released.  This is not performed atomically; external synchronization must be
+used to make this safe in the face of concurrent loads and stores.</li>
+<li>For <code class="docutils literal notranslate"><span class="pre">__weak</span></code> objects, the lvalue is updated to point to the new pointee,
+unless the new pointee is an object currently undergoing deallocation, in
+which case the lvalue is updated to a null pointer.  This must execute
+atomically with respect to other assignments to the object, to reads from the
+object, and to the final release of the new pointee.</li>
+<li>For <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> objects, the new pointee is stored into the
+lvalue using primitive semantics.</li>
+<li>For <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> objects, the new pointee is retained, autoreleased,
+and stored into the lvalue using primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Initialization</span> occurs when an object’s lifetime begins, which
+depends on its storage duration.  Initialization proceeds in two stages:</p>
+<ol class="arabic simple">
+<li>First, a null pointer is stored into the lvalue using primitive semantics.
+This step is skipped if the object is <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>.</li>
+<li>Second, if the object has an initializer, that expression is evaluated and
+then assigned into the object using the usual assignment semantics.</li>
+</ol>
+<p><span class="arc-term">Destruction</span> occurs when an object’s lifetime ends.  In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object’s
+lifetime ends.</p>
+<p><span class="arc-term">Moving</span> occurs in specific situations where an lvalue is “moved
+from”, meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state.  This arises with <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables
+and rvalue references in C++.  For <code class="docutils literal notranslate"><span class="pre">__strong</span></code> lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression.  For all other lvalues, moving is equivalent to
+reading the object.</p>
+</div>
+<div class="section" id="arc-ownership-restrictions">
+<span id="id1"></span><h3><a class="toc-backref" href="#id24">Restrictions</a><a class="headerlink" href="#arc-ownership-restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="weak-unavailable-types">
+<span id="arc-ownership-restrictions-weak"></span><h4><a class="toc-backref" href="#id25">Weak-unavailable types</a><a class="headerlink" href="#weak-unavailable-types" title="Permalink to this headline">¶</a></h4>
+<p>It is explicitly permitted for Objective-C classes to not support <code class="docutils literal notranslate"><span class="pre">__weak</span></code>
+references.  It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support <code class="docutils literal notranslate"><span class="pre">__weak</span></code> references.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Historically, it has been possible for a class to provide its own
+reference-count implementation by overriding <code class="docutils literal notranslate"><span class="pre">retain</span></code>, <code class="docutils literal notranslate"><span class="pre">release</span></code>, etc.
+However, weak references to an object require coordination with its class’s
+reference-count implementation because, among other things, weak loads and
+stores must be atomic with respect to the final release.  Therefore, existing
+custom reference-count implementations will generally not support weak
+references without additional effort.  This is unavoidable without breaking
+binary compatibility.</p>
+</div>
+<p>A class may indicate that it does not support weak references by providing the
+<code class="docutils literal notranslate"><span class="pre">objc_arc_weak_reference_unavailable</span></code> attribute on the class’s interface declaration.  A
+retainable object pointer type is <strong>weak-unavailable</strong> if
+is a pointer to an (optionally protocol-qualified) Objective-C class <code class="docutils literal notranslate"><span class="pre">T</span></code> where
+<code class="docutils literal notranslate"><span class="pre">T</span></code> or one of its superclasses has the <code class="docutils literal notranslate"><span class="pre">objc_arc_weak_reference_unavailable</span></code>
+attribute.  A program is ill-formed if it applies the <code class="docutils literal notranslate"><span class="pre">__weak</span></code> ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.</p>
+</div>
+<div class="section" id="storage-duration-of-autoreleasing-objects">
+<span id="arc-ownership-restrictions-autoreleasing"></span><h4><a class="toc-backref" href="#id26">Storage duration of <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> objects</a><a class="headerlink" href="#storage-duration-of-autoreleasing-objects" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares an <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> object of
+non-automatic storage duration.  A program is ill-formed if it captures an
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> object in a block or, unless by reference, in a C++11
+lambda.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are tied to the current thread and scope by their nature.
+While it is possible to have temporary objects whose instance variables are
+filled with autoreleased objects, there is no way that ARC can provide any
+sort of safety guarantee there.</p>
+</div>
+<p>It is undefined behavior if a non-null pointer is assigned to an
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> object while an autorelease pool is in scope and then that
+object is read after the autorelease pool’s scope is left.</p>
+</div>
+<div class="section" id="conversion-of-pointers-to-ownership-qualified-types">
+<span id="arc-ownership-restrictions-conversion-indirect"></span><h4><a class="toc-backref" href="#id27">Conversion of pointers to ownership-qualified types</a><a class="headerlink" href="#conversion-of-pointers-to-ownership-qualified-types" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if an expression of type <code class="docutils literal notranslate"><span class="pre">T*</span></code> is converted,
+explicitly or implicitly, to the type <code class="docutils literal notranslate"><span class="pre">U*</span></code>, where <code class="docutils literal notranslate"><span class="pre">T</span></code> and <code class="docutils literal notranslate"><span class="pre">U</span></code> have
+different ownership qualification, unless:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">T</span></code> is qualified with <code class="docutils literal notranslate"><span class="pre">__strong</span></code>, <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code>, or
+<code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>, and <code class="docutils literal notranslate"><span class="pre">U</span></code> is qualified with both <code class="docutils literal notranslate"><span class="pre">const</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>; or</li>
+<li>either <code class="docutils literal notranslate"><span class="pre">T</span></code> or <code class="docutils literal notranslate"><span class="pre">U</span></code> is <code class="docutils literal notranslate"><span class="pre">cv</span> <span class="pre">void</span></code>, where <code class="docutils literal notranslate"><span class="pre">cv</span></code> is an optional sequence
+of non-ownership qualifiers; or</li>
+<li>the conversion is requested with a <code class="docutils literal notranslate"><span class="pre">reinterpret_cast</span></code> in Objective-C++; or</li>
+<li>the conversion is a well-formed <a class="reference internal" href="#arc-ownership-restrictions-pass-by-writeback"><span class="std std-ref">pass-by-writeback</span></a>.</li>
+</ul>
+<p>The analogous rule applies to <code class="docutils literal notranslate"><span class="pre">T&</span></code> and <code class="docutils literal notranslate"><span class="pre">U&</span></code> in Objective-C++.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules provide a reasonable level of type-safety for indirect pointers,
+as long as the underlying memory is not deallocated.  The conversion to
+<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">__unsafe_unretained</span></code> is permitted because the semantics of reads are
+equivalent across all these ownership semantics, and that’s a very useful and
+common pattern.  The interconversion with <code class="docutils literal notranslate"><span class="pre">void*</span></code> is useful for allocating
+memory or otherwise escaping the type system, but use it carefully.
+<code class="docutils literal notranslate"><span class="pre">reinterpret_cast</span></code> is considered to be an obvious enough sign of taking
+responsibility for any problems.</p>
+</div>
+<p>It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-<code class="docutils literal notranslate"><span class="pre">__weak</span></code> object
+may be read through an <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> lvalue.</p>
+<p>It is undefined behavior if the storage of a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> or <code class="docutils literal notranslate"><span class="pre">__weak</span></code>
+object is not properly initialized before the first managed operation
+is performed on the object, or if the storage of such an object is freed
+or reused before the object has been properly deinitialized.  Storage for
+a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> or <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object may be properly initialized by filling
+it with the representation of a null pointer, e.g. by acquiring the memory
+with <code class="docutils literal notranslate"><span class="pre">calloc</span></code> or using <code class="docutils literal notranslate"><span class="pre">bzero</span></code> to zero it out.  A <code class="docutils literal notranslate"><span class="pre">__strong</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__weak</span></code> object may be properly deinitialized by assigning a null pointer
+into it.  A <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object may also be properly initialized
+by copying into it (e.g. with <code class="docutils literal notranslate"><span class="pre">memcpy</span></code>) the representation of a
+different <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object whose storage has been properly initialized;
+doing this properly deinitializes the source object and causes its storage
+to no longer be properly initialized.  A <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object may not be
+representation-copied in this way.</p>
+<p>These requirements are followed automatically for objects whose
+initialization and deinitialization are under the control of ARC:</p>
+<ul class="simple">
+<li>objects of static, automatic, and temporary storage duration</li>
+<li>instance variables of Objective-C objects</li>
+<li>elements of arrays where the array object’s initialization and
+deinitialization are under the control of ARC</li>
+<li>fields of Objective-C struct types where the struct object’s
+initialization and deinitialization are under the control of ARC</li>
+<li>non-static data members of Objective-C++ non-union class types</li>
+<li>Objective-C++ objects and arrays of dynamic storage duration created
+with the <code class="docutils literal notranslate"><span class="pre">new</span></code> or <code class="docutils literal notranslate"><span class="pre">new[]</span></code> operators and destroyed with the
+corresponding <code class="docutils literal notranslate"><span class="pre">delete</span></code> or <code class="docutils literal notranslate"><span class="pre">delete[]</span></code> operator</li>
+</ul>
+<p>They are not followed automatically for these objects:</p>
+<ul class="simple">
+<li>objects of dynamic storage duration created in other memory, such as
+that returned by <code class="docutils literal notranslate"><span class="pre">malloc</span></code></li>
+<li>union members</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC must perform special operations when initializing an object and
+when destroying it.  In many common situations, ARC knows when an
+object is created and when it is destroyed and can ensure that these
+operations are performed correctly.  Otherwise, however, ARC requires
+programmer cooperation to establish its initialization invariants
+because it is infeasible for ARC to dynamically infer whether they
+are intact.  For example, there is no syntactic difference in C between
+an assignment that is intended by the programmer to initialize a variable
+and one that is intended to replace the existing value stored there,
+but ARC must perform one operation or the other.  ARC chooses to always
+assume that objects are initialized (except when it is in charge of
+initializing them) because the only workable alternative would be to
+ban all code patterns that could potentially be used to access
+uninitialized memory, and that would be too limiting.  In practice,
+this is rarely a problem because programmers do not generally need to
+work with objects for which the requirements are not handled
+automatically.</p>
+</div>
+<p>Note that dynamically-allocated Objective-C++ arrays of
+nontrivially-ownership-qualified type are not ABI-compatible with non-ARC
+code because the non-ARC code will consider the element type to be POD.
+Such arrays that are <code class="docutils literal notranslate"><span class="pre">new[]</span></code>’d in ARC translation units cannot be
+<code class="docutils literal notranslate"><span class="pre">delete[]</span></code>’d in non-ARC translation units and vice-versa.</p>
+</div>
+<div class="section" id="passing-to-an-out-parameter-by-writeback">
+<span id="arc-ownership-restrictions-pass-by-writeback"></span><h4><a class="toc-backref" href="#id28">Passing to an out parameter by writeback</a><a class="headerlink" href="#passing-to-an-out-parameter-by-writeback" title="Permalink to this headline">¶</a></h4>
+<p>If the argument passed to a parameter of type <code class="docutils literal notranslate"><span class="pre">T</span> <span class="pre">__autoreleasing</span> <span class="pre">*</span></code> has type
+<code class="docutils literal notranslate"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></code>, where <code class="docutils literal notranslate"><span class="pre">oq</span></code> is an ownership qualifier, then the argument is a
+candidate for <span class="arc-term">pass-by-writeback`</span> if:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">oq</span></code> is <code class="docutils literal notranslate"><span class="pre">__strong</span></code> or <code class="docutils literal notranslate"><span class="pre">__weak</span></code>, and</li>
+<li>it would be legal to initialize a <code class="docutils literal notranslate"><span class="pre">T</span> <span class="pre">__strong</span> <span class="pre">*</span></code> with a <code class="docutils literal notranslate"><span class="pre">U</span> <span class="pre">__strong</span> <span class="pre">*</span></code>.</li>
+</ul>
+<p>For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.</p>
+<p>The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">&var</span></code>, where <code class="docutils literal notranslate"><span class="pre">var</span></code> is a scalar variable of automatic storage duration
+with retainable object pointer type</li>
+<li>a conditional expression where the second and third operands are both legal
+forms</li>
+<li>a cast whose operand is a legal form</li>
+<li>a null pointer constant</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The restriction in the form of the argument serves two purposes.  First, it
+makes it impossible to pass the address of an array to the argument, which
+serves to protect against an otherwise serious risk of mis-inferring an
+“array” argument as an out-parameter.  Second, it makes it much less likely
+that the user will see confusing aliasing problems due to the implementation,
+below, where their store to the writeback temporary is not immediately seen
+in the original argument variable.</p>
+</div>
+<p>A pass-by-writeback is evaluated as follows:</p>
+<ol class="arabic simple">
+<li>The argument is evaluated to yield a pointer <code class="docutils literal notranslate"><span class="pre">p</span></code> of type <code class="docutils literal notranslate"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></code>.</li>
+<li>If <code class="docutils literal notranslate"><span class="pre">p</span></code> is a null pointer, then a null pointer is passed as the argument,
+and no further work is required for the pass-by-writeback.</li>
+<li>Otherwise, a temporary of type <code class="docutils literal notranslate"><span class="pre">T</span> <span class="pre">__autoreleasing</span></code> is created and
+initialized to a null pointer.</li>
+<li>If the parameter is not an Objective-C method parameter marked <code class="docutils literal notranslate"><span class="pre">out</span></code>,
+then <code class="docutils literal notranslate"><span class="pre">*p</span></code> is read, and the result is written into the temporary with
+primitive semantics.</li>
+<li>The address of the temporary is passed as the argument to the actual call.</li>
+<li>After the call completes, the temporary is loaded with primitive
+semantics, and that value is assigned into <code class="docutils literal notranslate"><span class="pre">*p</span></code>.</li>
+</ol>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is all admittedly convoluted.  In an ideal world, we would see that a
+local variable is being passed to an out-parameter and retroactively modify
+its type to be <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> rather than <code class="docutils literal notranslate"><span class="pre">__strong</span></code>.  This would be
+remarkably difficult and not always well-founded under the C type system.
+However, it was judged unacceptably invasive to require programmers to write
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> on all the variables they intend to use for
+out-parameters.  This was the least bad solution.</p>
+</div>
+</div>
+<div class="section" id="ownership-qualified-fields-of-structs-and-unions">
+<span id="arc-ownership-restrictions-records"></span><h4><a class="toc-backref" href="#id29">Ownership-qualified fields of structs and unions</a><a class="headerlink" href="#ownership-qualified-fields-of-structs-and-unions" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The resulting type would be non-POD in the C++ sense, but C does not give us
+very good language tools for managing the lifetime of aggregates, so it is
+more convenient to simply forbid them.  It is still possible to manage this
+with a <code class="docutils literal notranslate"><span class="pre">void*</span></code> or an <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> object.</p>
+</div>
+<p>This restriction does not apply in Objective-C++.  However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible.  It is a violation of C++’s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Unlike in C, we can express all the necessary ARC semantics for
+ownership-qualified subobjects as suboperations of the (default) special
+member functions for the class.  These functions then become non-trivial.
+This has the non-obvious result that the class will have a non-trivial copy
+constructor and non-trivial destructor; if this would not normally be true
+outside of ARC, objects of the type will be passed and returned in an
+ABI-incompatible manner.</p>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-inference">
+<span id="arc-ownership-inference"></span><h3><a class="toc-backref" href="#id30">Ownership inference</a><a class="headerlink" href="#ownership-inference" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="objects">
+<span id="arc-ownership-inference-variables"></span><h4><a class="toc-backref" href="#id31">Objects</a><a class="headerlink" href="#objects" title="Permalink to this headline">¶</a></h4>
+<p>If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+<code class="docutils literal notranslate"><span class="pre">__strong</span></code> qualification.</p>
+<p>As a special case, if the object’s base type is <code class="docutils literal notranslate"><span class="pre">Class</span></code> (possibly
+protocol-qualified), the type is adjusted to have <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>
+qualification instead.</p>
+</div>
+<div class="section" id="indirect-parameters">
+<span id="arc-ownership-inference-indirect-parameters"></span><h4><a class="toc-backref" href="#id32">Indirect parameters</a><a class="headerlink" href="#indirect-parameters" title="Permalink to this headline">¶</a></h4>
+<p>If a function or method parameter has type <code class="docutils literal notranslate"><span class="pre">T*</span></code>, where <code class="docutils literal notranslate"><span class="pre">T</span></code> is an
+ownership-unqualified retainable object pointer type, then:</p>
+<ul class="simple">
+<li>if <code class="docutils literal notranslate"><span class="pre">T</span></code> is <code class="docutils literal notranslate"><span class="pre">const</span></code>-qualified or <code class="docutils literal notranslate"><span class="pre">Class</span></code>, then it is implicitly
+qualified with <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>;</li>
+<li>otherwise, it is implicitly qualified with <code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code>.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> exists mostly for this case, the Cocoa convention for
+out-parameters.  Since a pointer to <code class="docutils literal notranslate"><span class="pre">const</span></code> is obviously not an
+out-parameter, we instead use a type more useful for passing arrays.  If the
+user instead intends to pass in a <em>mutable</em> array, inferring
+<code class="docutils literal notranslate"><span class="pre">__autoreleasing</span></code> is the wrong thing to do; this directs some of the
+caution in the following rules about writeback.</p>
+</div>
+<p>Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.</p>
+<p>This rule does not apply in Objective-C++ if a parameter’s type is dependent in
+a template pattern and is only <em>instantiated</em> to a type which would be a
+pointer to an unqualified retainable object pointer type.  Such code is still
+ill-formed.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The convention is very unlikely to be intentional in template code.</p>
+</div>
+</div>
+<div class="section" id="template-arguments">
+<span id="arc-ownership-inference-template-arguments"></span><h4><a class="toc-backref" href="#id33">Template arguments</a><a class="headerlink" href="#template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have <code class="docutils literal notranslate"><span class="pre">__strong</span></code> qualification.  This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><code class="docutils literal notranslate"><span class="pre">__strong</span></code> is a useful default for containers (e.g., <code class="docutils literal notranslate"><span class="pre">std::vector<id></span></code>),
+which would otherwise require explicit qualification.  Moreover, unqualified
+retainable object pointer types are unlikely to be useful within templates,
+since they generally need to have a qualifier applied to the before being
+used.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="method-families">
+<span id="arc-method-families"></span><h2><a class="toc-backref" href="#id34">Method families</a><a class="headerlink" href="#method-families" title="Permalink to this headline">¶</a></h2>
+<p>An Objective-C method may fall into a <span class="arc-term">method family</span>, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.</p>
+<p>A method is in a certain method family if:</p>
+<ul class="simple">
+<li>it has a <code class="docutils literal notranslate"><span class="pre">objc_method_family</span></code> attribute placing it in that family; or if
+not that,</li>
+<li>it does not have an <code class="docutils literal notranslate"><span class="pre">objc_method_family</span></code> attribute placing it in a
+different or no family, and</li>
+<li>its selector falls into the corresponding selector family, and</li>
+<li>its signature obeys the added restrictions of the method family.</li>
+</ul>
+<p>A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter.  For example, <code class="docutils literal notranslate"><span class="pre">_perform:with:</span></code> and
+<code class="docutils literal notranslate"><span class="pre">performWith:</span></code> would fall into the <code class="docutils literal notranslate"><span class="pre">perform</span></code> family (if we recognized one),
+but <code class="docutils literal notranslate"><span class="pre">performing:with</span></code> would not.</p>
+<p>The families and their added restrictions are:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">alloc</span></code> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">copy</span></code> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">new</span></code> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">init</span></code> methods must be instance methods and must return an Objective-C
+pointer type.  Additionally, a program is ill-formed if it declares or
+contains a call to an <code class="docutils literal notranslate"><span class="pre">init</span></code> method whose return type is neither <code class="docutils literal notranslate"><span class="pre">id</span></code> nor
+a pointer to a super-class or sub-class of the declaring class (if the method
+was declared on a class) or the static receiver type of the call (if it was
+declared on a protocol).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>There are a fair number of existing methods with <code class="docutils literal notranslate"><span class="pre">init</span></code>-like selectors
+which nonetheless don’t follow the <code class="docutils literal notranslate"><span class="pre">init</span></code> conventions.  Typically these
+are either accidental naming collisions or helper methods called during
+initialization.  Because of the peculiar retain/release behavior of
+<code class="docutils literal notranslate"><span class="pre">init</span></code> methods, it’s very important not to treat these methods as
+<code class="docutils literal notranslate"><span class="pre">init</span></code> methods if they aren’t meant to be.  It was felt that implicitly
+defining these methods out of the family based on the exact relationship
+between the return type and the declaring class would be much too subtle
+and fragile.  Therefore we identify a small number of legitimate-seeming
+return types and call everything else an error.  This serves the secondary
+purpose of encouraging programmers not to accidentally give methods names
+in the <code class="docutils literal notranslate"><span class="pre">init</span></code> family.</p>
+<p class="last">Note that a method with an <code class="docutils literal notranslate"><span class="pre">init</span></code>-family selector which returns a
+non-Objective-C type (e.g. <code class="docutils literal notranslate"><span class="pre">void</span></code>) is perfectly well-formed; it simply
+isn’t in the <code class="docutils literal notranslate"><span class="pre">init</span></code> family.</p>
+</div>
+</li>
+</ul>
+<p>A program is ill-formed if a method’s declarations, implementations, and
+overrides do not all have the same method family.</p>
+<div class="section" id="explicit-method-family-control">
+<span id="arc-family-attribute"></span><h3><a class="toc-backref" href="#id35">Explicit method family control</a><a class="headerlink" href="#explicit-method-family-control" title="Permalink to this headline">¶</a></h3>
+<p>A method may be annotated with the <code class="docutils literal notranslate"><span class="pre">objc_method_family</span></code> attribute to
+precisely control which method family it belongs to.  If a method in an
+<code class="docutils literal notranslate"><span class="pre">@implementation</span></code> does not have this attribute, but there is a method
+declared in the corresponding <code class="docutils literal notranslate"><span class="pre">@interface</span></code> that does, then the attribute is
+copied to the declaration in the <code class="docutils literal notranslate"><span class="pre">@implementation</span></code>.  The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+<code class="docutils literal notranslate"><span class="pre">__has_attribute(objc_method_family)</span></code>.</p>
+<p>The attribute is spelled
+<code class="docutils literal notranslate"><span class="pre">__attribute__((objc_method_family(</span></code> <em>family</em> <code class="docutils literal notranslate"><span class="pre">)))</span></code>.  If <em>family</em> is
+<code class="docutils literal notranslate"><span class="pre">none</span></code>, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type.  Otherwise, <em>family</em> must be one of
+<code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">copy</span></code>, <code class="docutils literal notranslate"><span class="pre">init</span></code>, <code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code>, or <code class="docutils literal notranslate"><span class="pre">new</span></code>, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector.  It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The rules codified in this document describe the standard conventions of
+Objective-C.  However, as these conventions have not heretofore been enforced
+by an unforgiving mechanical system, they are only imperfectly kept,
+especially as they haven’t always even been precisely defined.  While it is
+possible to define low-level ownership semantics with attributes like
+<code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code>, this attribute allows the user to communicate
+semantic intent, which is of use both to ARC (which, e.g., treats calls to
+<code class="docutils literal notranslate"><span class="pre">init</span></code> specially) and the static analyzer.</p>
+</div>
+</div>
+<div class="section" id="semantics-of-method-families">
+<span id="arc-family-semantics"></span><h3><a class="toc-backref" href="#id36">Semantics of method families</a><a class="headerlink" href="#semantics-of-method-families" title="Permalink to this headline">¶</a></h3>
+<p>A method’s membership in a method family may imply non-standard semantics for
+its parameters and return type.</p>
+<p>Methods in the <code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">copy</span></code>, <code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal notranslate"><span class="pre">new</span></code> families —
+that is, methods in all the currently-defined families except <code class="docutils literal notranslate"><span class="pre">init</span></code> —
+implicitly <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">return a retained object</span></a> as if they were annotated with
+the <code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code> attribute.  This can be overridden by annotating
+the method with either of the <code class="docutils literal notranslate"><span class="pre">ns_returns_autoreleased</span></code> or
+<code class="docutils literal notranslate"><span class="pre">ns_returns_not_retained</span></code> attributes.</p>
+<p>Properties also follow same naming rules as methods.  This means that those in
+the <code class="docutils literal notranslate"><span class="pre">alloc</span></code>, <code class="docutils literal notranslate"><span class="pre">copy</span></code>, <code class="docutils literal notranslate"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal notranslate"><span class="pre">new</span></code> families provide access
+to <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">retained objects</span></a>.  This
+can be overridden by annotating the property with <code class="docutils literal notranslate"><span class="pre">ns_returns_not_retained</span></code>
+attribute.</p>
+<div class="section" id="semantics-of-init">
+<span id="arc-family-semantics-init"></span><h4><a class="toc-backref" href="#id37">Semantics of <code class="docutils literal notranslate"><span class="pre">init</span></code></a><a class="headerlink" href="#semantics-of-init" title="Permalink to this headline">¶</a></h4>
+<p>Methods in the <code class="docutils literal notranslate"><span class="pre">init</span></code> family implicitly <a class="reference internal" href="#arc-objects-operands-consumed"><span class="std std-ref">consume</span></a> their <code class="docutils literal notranslate"><span class="pre">self</span></code> parameter and <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">return a
+retained object</span></a>.  Neither of
+these properties can be altered through attributes.</p>
+<p>A call to an <code class="docutils literal notranslate"><span class="pre">init</span></code> method with a receiver that is either <code class="docutils literal notranslate"><span class="pre">self</span></code> (possibly
+parenthesized or casted) or <code class="docutils literal notranslate"><span class="pre">super</span></code> is called a <span class="arc-term">delegate init
+call</span>.  It is an error for a delegate init call to be made except from an
+<code class="docutils literal notranslate"><span class="pre">init</span></code> method, and excluding blocks within such methods.</p>
+<p>As an exception to the <a class="reference internal" href="#arc-misc-self"><span class="std std-ref">usual rule</span></a>, the variable <code class="docutils literal notranslate"><span class="pre">self</span></code>
+is mutable in an <code class="docutils literal notranslate"><span class="pre">init</span></code> method and has the usual semantics for a <code class="docutils literal notranslate"><span class="pre">__strong</span></code>
+variable.  However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an <code class="docutils literal notranslate"><span class="pre">init</span></code> method attempts to use the previous value
+of <code class="docutils literal notranslate"><span class="pre">self</span></code> after the completion of a delegate init call.  It is conventional,
+but not required, for an <code class="docutils literal notranslate"><span class="pre">init</span></code> method to return <code class="docutils literal notranslate"><span class="pre">self</span></code>.</p>
+<p>It is undefined behavior for a program to cause two or more calls to <code class="docutils literal notranslate"><span class="pre">init</span></code>
+methods on the same object, except that each <code class="docutils literal notranslate"><span class="pre">init</span></code> method invocation may
+perform at most one delegate init call.</p>
+</div>
+<div class="section" id="related-result-types">
+<span id="arc-family-semantics-result-type"></span><h4><a class="toc-backref" href="#id38">Related result types</a><a class="headerlink" href="#related-result-types" title="Permalink to this headline">¶</a></h4>
+<p>Certain methods are candidates to have <span class="arc-term">related result types</span>:</p>
+<ul class="simple">
+<li>class methods in the <code class="docutils literal notranslate"><span class="pre">alloc</span></code> and <code class="docutils literal notranslate"><span class="pre">new</span></code> method families</li>
+<li>instance methods in the <code class="docutils literal notranslate"><span class="pre">init</span></code> family</li>
+<li>the instance method <code class="docutils literal notranslate"><span class="pre">self</span></code></li>
+<li>outside of ARC, the instance methods <code class="docutils literal notranslate"><span class="pre">retain</span></code> and <code class="docutils literal notranslate"><span class="pre">autorelease</span></code></li>
+</ul>
+<p>If the formal result type of such a method is <code class="docutils literal notranslate"><span class="pre">id</span></code> or protocol-qualified
+<code class="docutils literal notranslate"><span class="pre">id</span></code>, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type.  In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:</p>
+<ul class="simple">
+<li>if it is a class method, and the receiver is a class name <code class="docutils literal notranslate"><span class="pre">T</span></code>, the message
+send expression has type <code class="docutils literal notranslate"><span class="pre">T*</span></code>; otherwise</li>
+<li>if it is an instance method, and the receiver has type <code class="docutils literal notranslate"><span class="pre">T</span></code>, the message
+send expression has type <code class="docutils literal notranslate"><span class="pre">T</span></code>; otherwise</li>
+<li>the message send expression has the normal result type of the method.</li>
+</ul>
+<p>This is a new rule of the Objective-C language and applies outside of ARC.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC’s automatic code emission is more prone than most code to signature
+errors, i.e. errors where a call was emitted against one method signature,
+but the implementing method has an incompatible signature.  Having more
+precise type information helps drastically lower this risk, as well as
+catching a number of latent bugs.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="optimization">
+<span id="arc-optimization"></span><h2><a class="toc-backref" href="#id39">Optimization</a><a class="headerlink" href="#optimization" title="Permalink to this headline">¶</a></h2>
+<p>Within this section, the word <span class="arc-term">function</span> will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.</p>
+<p>This specification describes ARC as performing specific <code class="docutils literal notranslate"><span class="pre">retain</span></code> and
+<code class="docutils literal notranslate"><span class="pre">release</span></code> operations on retainable object pointers at specific
+points during the execution of a program.  These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the <span class="arc-term">formal local retain history</span> of the
+object pointer.  The corresponding actual sequence executed is the
+<cite>dynamic local retain history</cite>.</p>
+<p>However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general “as if”
+rule of C/C++ and the <a class="reference internal" href="#arc-objects-retains"><span class="std std-ref">restrictions</span></a> on
+the implementation of <code class="docutils literal notranslate"><span class="pre">retain</span></code> and <code class="docutils literal notranslate"><span class="pre">release</span></code>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Specifically, ARC is sometimes permitted to optimize <code class="docutils literal notranslate"><span class="pre">release</span></code>
+operations in ways which might cause an object to be deallocated
+before it would otherwise be.  Without this, it would be almost
+impossible to eliminate any <code class="docutils literal notranslate"><span class="pre">retain</span></code>/<code class="docutils literal notranslate"><span class="pre">release</span></code> pairs.  For
+example, consider the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="n">x</span> <span class="o">=</span> <span class="n">_ivar</span><span class="p">;</span>
+<span class="p">[</span><span class="n">x</span> <span class="n">foo</span><span class="p">];</span>
+</pre></div>
+</div>
+<p class="last">If we were not permitted in any event to shorten the lifetime of the
+object in <code class="docutils literal notranslate"><span class="pre">x</span></code>, then we would not be able to eliminate this retain
+and release unless we could prove that the message send could not
+modify <code class="docutils literal notranslate"><span class="pre">_ivar</span></code> (or deallocate <code class="docutils literal notranslate"><span class="pre">self</span></code>).  Since message sends are
+opaque to the optimizer, this is not possible, and so ARC’s hands
+would be almost completely tied.</p>
+</div>
+<p>ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior.  In particular, ARC makes no
+guarantees in the presence of race conditions.</p>
+<p>ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There is very little point in trying to guarantee correctness in the
+presence of race conditions.  ARC does not have a stack-scanning
+garbage collector, and guaranteeing the atomicity of every load and
+store operation would be prohibitive and preclude a vast amount of
+optimization.</p>
+</div>
+<p>ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object invariants or +1 transfer
+conventions.  For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a “balancing” retain.</p>
+<div class="section" id="object-liveness">
+<span id="arc-optimization-liveness"></span><h3><a class="toc-backref" href="#id40">Object liveness</a><a class="headerlink" href="#object-liveness" title="Permalink to this headline">¶</a></h3>
+<p>ARC may not allow a retainable object <code class="docutils literal notranslate"><span class="pre">X</span></code> to be deallocated at a
+time <code class="docutils literal notranslate"><span class="pre">T</span></code> in a computation history if:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">X</span></code> is the value stored in a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object <code class="docutils literal notranslate"><span class="pre">S</span></code> with
+<a class="reference internal" href="#arc-optimization-precise"><span class="std std-ref">precise lifetime semantics</span></a>, or</li>
+<li><code class="docutils literal notranslate"><span class="pre">X</span></code> is the value stored in a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object <code class="docutils literal notranslate"><span class="pre">S</span></code> with
+imprecise lifetime semantics and, at some point after <code class="docutils literal notranslate"><span class="pre">T</span></code> but
+before the next store to <code class="docutils literal notranslate"><span class="pre">S</span></code>, the computation history features a
+load from <code class="docutils literal notranslate"><span class="pre">S</span></code> and in some way depends on the value loaded, or</li>
+<li><code class="docutils literal notranslate"><span class="pre">X</span></code> is a value described as being released at the end of the
+current full-expression and, at some point after <code class="docutils literal notranslate"><span class="pre">T</span></code> but before
+the end of the full-expression, the computation history depends
+on that value.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The intent of the second rule is to say that objects held in normal
+<code class="docutils literal notranslate"><span class="pre">__strong</span></code> local variables may be released as soon as the value in
+the variable is no longer being used: either the variable stops
+being used completely or a new value is stored in the variable.</p>
+<p class="last">The intent of the third rule is to say that return values may be
+released after they’ve been used.</p>
+</div>
+<p>A computation history depends on a pointer value <code class="docutils literal notranslate"><span class="pre">P</span></code> if it:</p>
+<ul class="simple">
+<li>performs a pointer comparison with <code class="docutils literal notranslate"><span class="pre">P</span></code>,</li>
+<li>loads from <code class="docutils literal notranslate"><span class="pre">P</span></code>,</li>
+<li>stores to <code class="docutils literal notranslate"><span class="pre">P</span></code>,</li>
+<li>depends on a pointer value <code class="docutils literal notranslate"><span class="pre">Q</span></code> derived via pointer arithmetic
+from <code class="docutils literal notranslate"><span class="pre">P</span></code> (including an instance-variable or field access), or</li>
+<li>depends on a pointer value <code class="docutils literal notranslate"><span class="pre">Q</span></code> loaded from <code class="docutils literal notranslate"><span class="pre">P</span></code>.</li>
+</ul>
+<p>Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases <code class="docutils literal notranslate"><span class="pre">P</span></code>.  Furthermore, this
+dependency is not carried by values that are stored to objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The restrictions on dependency are intended to make this analysis
+feasible by an optimizer with only incomplete information about a
+program.  Essentially, dependence is carried to “obvious” uses of a
+pointer.  Merely passing a pointer argument to a function does not
+itself cause dependence, but since generally the optimizer will not
+be able to prove that the function doesn’t depend on that parameter,
+it will be forced to conservatively assume it does.</p>
+<p>Dependency propagates to values loaded from a pointer because those
+values might be invalidated by deallocating the object.  For
+example, given the code <code class="docutils literal notranslate"><span class="pre">__strong</span> <span class="pre">id</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">p->ivar;</span></code>, ARC must not
+move the release of <code class="docutils literal notranslate"><span class="pre">p</span></code> to between the load of <code class="docutils literal notranslate"><span class="pre">p->ivar</span></code> and the
+retain of that value for storing into <code class="docutils literal notranslate"><span class="pre">x</span></code>.</p>
+<p>Dependency does not propagate through stores of dependent pointer
+values because doing so would allow dependency to outlive the
+full-expression which produced the original value.  For example, the
+address of an instance variable could be written to some global
+location and then freely accessed during the lifetime of the local,
+or a function could return an inner pointer of an object and store
+it to a local.  These cases would be potentially impossible to
+reason about and so would basically prevent any optimizations based
+on imprecise lifetime.  There are also uncommon enough to make it
+reasonable to require the precise-lifetime annotation if someone
+really wants to rely on them.</p>
+<p class="last">Dependency does propagate through return values of pointer type.
+The compelling source of need for this rule is a property accessor
+which returns an un-autoreleased result; the calling function must
+have the chance to operate on the value, e.g. to retain it, before
+ARC releases the original pointer.  Note again, however, that
+dependence does not survive a store, so ARC does not guarantee the
+continued validity of the return value past the end of the
+full-expression.</p>
+</div>
+</div>
+<div class="section" id="no-object-lifetime-extension">
+<span id="arc-optimization-object-lifetime"></span><h3><a class="toc-backref" href="#id41">No object lifetime extension</a><a class="headerlink" href="#no-object-lifetime-extension" title="Permalink to this headline">¶</a></h3>
+<p>If, in the formal computation history of the program, an object <code class="docutils literal notranslate"><span class="pre">X</span></code>
+has been deallocated by the time of an observable side-effect, then
+ARC must cause <code class="docutils literal notranslate"><span class="pre">X</span></code> to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>This rule is intended to prohibit ARC from observably extending the
+lifetime of a retainable object, other than as specified in this
+document.  Together with the rule limiting the transformation of
+releases, this rule requires ARC to eliminate retains and release
+only in pairs.</p>
+<p class="last">ARC’s power to reorder the destruction of objects is critical to its
+ability to do any optimization, for essentially the same reason that
+it must retain the power to decrease the lifetime of an object.
+Unfortunately, while it’s generally poor style for the destruction
+of objects to have arbitrary side-effects, it’s certainly possible.
+Hence the caveat.</p>
+</div>
+</div>
+<div class="section" id="precise-lifetime-semantics">
+<span id="arc-optimization-precise"></span><h3><a class="toc-backref" href="#id42">Precise lifetime semantics</a><a class="headerlink" href="#precise-lifetime-semantics" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC maintains an invariant that a retainable object pointer held in
+a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object will be retained for the full formal lifetime of the
+object.  Objects subject to this invariant have <span class="arc-term">precise lifetime
+semantics</span>.</p>
+<p>By default, local variables of automatic storage duration do not have precise
+lifetime semantics.  Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Applying these precise-lifetime semantics strictly would be prohibitive.
+Many useful optimizations that might theoretically decrease the lifetime of
+an object would be rendered impossible.  Essentially, it promises too much.</p>
+</div>
+<p>A local variable of retainable object owner type and automatic storage duration
+may be annotated with the <code class="docutils literal notranslate"><span class="pre">objc_precise_lifetime</span></code> attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Nonetheless, it is sometimes useful to be able to force an object to be
+released at a precise time, even if that object does not appear to be used.
+This is likely to be uncommon enough that the syntactic weight of explicitly
+requesting these semantics will not be burdensome, and may even make the code
+clearer.</p>
+</div>
+</div>
+</div>
+<div class="section" id="miscellaneous">
+<span id="arc-misc"></span><h2><a class="toc-backref" href="#id43">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="special-methods">
+<span id="arc-misc-special-methods"></span><h3><a class="toc-backref" href="#id44">Special methods</a><a class="headerlink" href="#special-methods" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="memory-management-methods">
+<span id="arc-misc-special-methods-retain"></span><h4><a class="toc-backref" href="#id45">Memory management methods</a><a class="headerlink" href="#memory-management-methods" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a method definition, message send, or
+<code class="docutils literal notranslate"><span class="pre">@selector</span></code> expression for any of the following selectors:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">autorelease</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">release</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">retain</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">retainCount</span></code></li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p><code class="docutils literal notranslate"><span class="pre">retainCount</span></code> is banned because ARC robs it of consistent semantics.  The
+others were banned after weighing three options for how to deal with message
+sends:</p>
+<p><strong>Honoring</strong> them would work out very poorly if a programmer naively or
+accidentally tried to incorporate code written for manual retain/release code
+into an ARC program.  At best, such code would do twice as much work as
+necessary; quite frequently, however, ARC and the explicit code would both
+try to balance the same retain, leading to crashes.  The cost is losing the
+ability to perform “unrooted” retains, i.e. retains not logically
+corresponding to a strong reference in the object graph.</p>
+<p><strong>Ignoring</strong> them would badly violate user expectations about their code.
+While it <em>would</em> make it easier to develop code simultaneously for ARC and
+non-ARC, there is very little reason to do so except for certain library
+developers.  ARC and non-ARC translation units share an execution model and
+can seamlessly interoperate.  Within a translation unit, a developer who
+faithfully maintains their code in non-ARC mode is suffering all the
+restrictions of ARC for zero benefit, while a developer who isn’t testing the
+non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+it.</p>
+<p><strong>Banning</strong> them has the disadvantage of making it very awkward to migrate
+existing code to ARC.  The best answer to that, given a number of other
+changes and restrictions in ARC, is to provide a specialized tool to assist
+users in that migration.</p>
+<p class="last">Implementing these methods was banned because they are too integral to the
+semantics of ARC; many tricks which worked tolerably under manual reference
+counting will misbehave if ARC performs an ephemeral extra retain or two.  If
+absolutely required, it is still possible to implement them in non-ARC code,
+for example in a category; the implementations must obey the <a class="reference internal" href="#arc-objects-retains"><span class="std std-ref">semantics</span></a> laid out elsewhere in this document.</p>
+</div>
+</div>
+<div class="section" id="dealloc">
+<span id="arc-misc-special-methods-dealloc"></span><h4><a class="toc-backref" href="#id46"><code class="docutils literal notranslate"><span class="pre">dealloc</span></code></a><a class="headerlink" href="#dealloc" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a message send or <code class="docutils literal notranslate"><span class="pre">@selector</span></code>
+expression for the selector <code class="docutils literal notranslate"><span class="pre">dealloc</span></code>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There are no legitimate reasons to call <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> directly.</p>
+</div>
+<p>A class may provide a method definition for an instance method named
+<code class="docutils literal notranslate"><span class="pre">dealloc</span></code>.  This method will be called after the final <code class="docutils literal notranslate"><span class="pre">release</span></code> of the
+object but before it is deallocated or any of its instance variables are
+destroyed.  The superclass’s implementation of <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> will be called
+automatically when the method returns.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Even though ARC destroys instance variables automatically, there are still
+legitimate reasons to write a <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> method, such as freeing
+non-retainable resources.  Failing to call <code class="docutils literal notranslate"><span class="pre">[super</span> <span class="pre">dealloc]</span></code> in such a
+method is nearly always a bug.  Sometimes, the object is simply trying to
+prevent itself from being destroyed, but <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> is really far too late
+for the object to be raising such objections.  Somewhat more legitimately, an
+object may have been pool-allocated and should not be deallocated with
+<code class="docutils literal notranslate"><span class="pre">free</span></code>; for now, this can only be supported with a <code class="docutils literal notranslate"><span class="pre">dealloc</span></code>
+implementation outside of ARC.  Such an implementation must be very careful
+to do all the other work that <code class="docutils literal notranslate"><span class="pre">NSObject</span></code>’s <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> would, which is
+outside the scope of this document to describe.</p>
+</div>
+<p>The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the <code class="docutils literal notranslate"><span class="pre">dealloc</span></code> method for the root class of the
+class.  The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The traditional, non-ARC pattern for destroying instance variables is to
+destroy them immediately before calling <code class="docutils literal notranslate"><span class="pre">[super</span> <span class="pre">dealloc]</span></code>.  Unfortunately,
+message sends from the superclass are quite capable of reaching methods in
+the subclass, and those methods may well read or write to those instance
+variables.  Making such message sends from dealloc is generally discouraged,
+since the subclass may well rely on other invariants that were broken during
+<code class="docutils literal notranslate"><span class="pre">dealloc</span></code>, but it’s not so inescapably dangerous that we felt comfortable
+calling it undefined behavior.  Therefore we chose to delay destroying the
+instance variables to a point at which message sends are clearly disallowed:
+the point at which the root class’s deallocation routines take over.</p>
+<p class="last">In most code, the difference is not observable.  It can, however, be observed
+if an instance variable holds a strong reference to an object whose
+deallocation will trigger a side-effect which must be carefully ordered with
+respect to the destruction of the super class.  Such code violates the design
+principle that semantically important behavior should be explicit.  A simple
+fix is to clear the instance variable manually during <code class="docutils literal notranslate"><span class="pre">dealloc</span></code>; a more
+holistic solution is to move semantically important side-effects out of
+<code class="docutils literal notranslate"><span class="pre">dealloc</span></code> and into a separate teardown phase which can rely on working with
+well-formed objects.</p>
+</div>
+</div>
+</div>
+<div class="section" id="autoreleasepool">
+<span id="arc-misc-autoreleasepool"></span><h3><a class="toc-backref" href="#id47"><code class="docutils literal notranslate"><span class="pre">@autoreleasepool</span></code></a><a class="headerlink" href="#autoreleasepool" title="Permalink to this headline">¶</a></h3>
+<p>To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C.  It is
+written <code class="docutils literal notranslate"><span class="pre">@autoreleasepool</span></code> followed by a <em>compound-statement</em>, i.e.  by a new
+scope delimited by curly braces.  Upon entry to this block, the current state
+of the autorelease pool is captured.  When the block is exited normally,
+whether by fallthrough or directed control flow (such as <code class="docutils literal notranslate"><span class="pre">return</span></code> or
+<code class="docutils literal notranslate"><span class="pre">break</span></code>), the autorelease pool is restored to the saved state, releasing all
+the objects in it.  When the block is exited with an exception, the pool is not
+drained.</p>
+<p><code class="docutils literal notranslate"><span class="pre">@autoreleasepool</span></code> may be used in non-ARC translation units, with equivalent
+semantics.</p>
+<p>A program is ill-formed if it refers to the <code class="docutils literal notranslate"><span class="pre">NSAutoreleasePool</span></code> class.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are clearly important for the compiler to reason about, but
+it is far too much to expect the compiler to accurately reason about control
+dependencies between two calls.  It is also very easy to accidentally forget
+to drain an autorelease pool when using the manual API, and this can
+significantly inflate the process’s high-water-mark.  The introduction of a
+new scope is unfortunate but basically required for sane interaction with the
+rest of the language.  Not draining the pool during an unwind is apparently
+required by the Objective-C exceptions implementation.</p>
+</div>
+</div>
+<div class="section" id="externally-retained-variables">
+<span id="arc-misc-externally-retained"></span><h3><a class="toc-backref" href="#id48">Externally-Retained Variables</a><a class="headerlink" href="#externally-retained-variables" title="Permalink to this headline">¶</a></h3>
+<p>In some situations, variables with strong ownership are considered
+externally-retained by the implementation. This means that the variable is
+retained elsewhere, and therefore the implementation can elide retaining and
+releasing its value. Such a variable is implicitly <code class="docutils literal notranslate"><span class="pre">const</span></code> for safety. In
+contrast with <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>, an externally-retained variable still
+behaves as a strong variable outside of initialization and destruction. For
+instance, when an externally-retained variable is captured in a block the value
+of the variable is retained and released on block capture and destruction. It
+also affects C++ features such as lambda capture, <code class="docutils literal notranslate"><span class="pre">decltype</span></code>, and template
+argument deduction.</p>
+<p>Implicitly, the implementation assumes that the <a class="reference internal" href="#arc-misc-self"><span class="std std-ref">self parameter in a
+non-init method</span></a> and the <a class="reference internal" href="#arc-misc-enumeration"><span class="std std-ref">variable in a for-in loop</span></a> are externally-retained.</p>
+<p>Externally-retained semantics can also be opted into with the
+<code class="docutils literal notranslate"><span class="pre">objc_externally_retained</span></code> attribute. This attribute can apply to strong local
+variables, functions, methods, or blocks:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@class</span> <span class="nc">WobbleAmount</span>;
+
+<span class="k">@interface</span> <span class="nc">Widget</span> : <span class="bp">NSObject</span>
+<span class="p">-(</span><span class="kt">void</span><span class="p">)</span><span class="nf">wobble:</span><span class="p">(</span><span class="n">WobbleAmount</span> <span class="o">*</span><span class="p">)</span><span class="nv">amount</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@implementation</span> <span class="nc">Widget</span>
+
+<span class="p">-(</span><span class="kt">void</span><span class="p">)</span><span class="nf">wobble:</span><span class="p">(</span><span class="n">WobbleAmount</span> <span class="o">*</span><span class="p">)</span><span class="nv">amount</span>
+         <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_externally_retained</span><span class="p">))</span> <span class="p">{</span>
+  <span class="c1">// 'amount' and 'alias' aren't retained on entry, nor released on exit.</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_externally_retained</span><span class="p">))</span> <span class="n">WobbleAmount</span> <span class="o">*</span><span class="n">alias</span> <span class="o">=</span> <span class="n">amount</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Annotating a function with this attribute makes every parameter with strong
+retainable object pointer type externally-retained, unless the variable was
+explicitly qualified with <code class="docutils literal notranslate"><span class="pre">__strong</span></code>. For instance, <code class="docutils literal notranslate"><span class="pre">first_param</span></code> is
+externally-retained (and therefore <code class="docutils literal notranslate"><span class="pre">const</span></code>) below, but not <code class="docutils literal notranslate"><span class="pre">second_param</span></code>:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_externally_retained</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="bp">NSArray</span> <span class="o">*</span><span class="n">first_param</span><span class="p">,</span> <span class="k">__strong</span> <span class="bp">NSArray</span> <span class="o">*</span><span class="n">second_param</span><span class="p">)</span> <span class="p">{</span>
+  <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>You can test if your compiler has support for <code class="docutils literal notranslate"><span class="pre">objc_externally_retained</span></code> with
+<code class="docutils literal notranslate"><span class="pre">__has_attribute</span></code>:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="cp">#if __has_attribute(objc_externally_retained)</span>
+<span class="c1">// Use externally retained...</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="self">
+<span id="arc-misc-self"></span><h3><a class="toc-backref" href="#id49"><code class="docutils literal notranslate"><span class="pre">self</span></code></a><a class="headerlink" href="#self" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">self</span></code> parameter variable of an non-init Objective-C method is considered
+<a class="reference internal" href="#arc-misc-externally-retained"><span class="std std-ref">externally-retained</span></a> by the implementation.
+It is undefined behavior, or at least dangerous, to cause an object to be
+deallocated during a message send to that object.  In an init method, <code class="docutils literal notranslate"><span class="pre">self</span></code>
+follows the :ref:<code class="docutils literal notranslate"><span class="pre">init</span> <span class="pre">family</span> <span class="pre">rules</span> <span class="pre"><arc.family.semantics.init></span></code>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The cost of retaining <code class="docutils literal notranslate"><span class="pre">self</span></code> in all methods was found to be prohibitive, as
+it tends to be live across calls, preventing the optimizer from proving that
+the retain and release are unnecessary — for good reason, as it’s quite
+possible in theory to cause an object to be deallocated during its execution
+without this retain and release.  Since it’s extremely uncommon to actually
+do so, even unintentionally, and since there’s no natural way for the
+programmer to remove this retain/release pair otherwise (as there is for
+other parameters by, say, making the variable <code class="docutils literal notranslate"><span class="pre">objc_externally_retained</span></code> or
+qualifying it with <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>), we chose to make this optimizing
+assumption and shift some amount of risk to the user.</p>
+</div>
+</div>
+<div class="section" id="fast-enumeration-iteration-variables">
+<span id="arc-misc-enumeration"></span><h3><a class="toc-backref" href="#id50">Fast enumeration iteration variables</a><a class="headerlink" href="#fast-enumeration-iteration-variables" title="Permalink to this headline">¶</a></h3>
+<p>If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+implicitly <a class="reference internal" href="#arc-misc-externally-retained"><span class="std std-ref">externally-retained</span></a> so that
+objects encountered during the enumeration are not actually retained and
+released.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is an optimization made possible because fast enumeration loops promise
+to keep the objects retained during enumeration, and the collection itself
+cannot be synchronously modified.  It can be overridden by explicitly
+qualifying the variable with <code class="docutils literal notranslate"><span class="pre">__strong</span></code>, which will make the variable
+mutable again and cause the loop to retain the objects it encounters.</p>
+</div>
+</div>
+<div class="section" id="blocks">
+<span id="arc-misc-blocks"></span><h3><a class="toc-backref" href="#id51">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">¶</a></h3>
+<p>The implicit <code class="docutils literal notranslate"><span class="pre">const</span></code> capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture.  The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.</p>
+<p>The <a class="reference internal" href="#arc-ownership-inference"><span class="std std-ref">inference</span></a> rules apply equally to
+<code class="docutils literal notranslate"><span class="pre">__block</span></code> variables, which is a shift in semantics from non-ARC, where
+<code class="docutils literal notranslate"><span class="pre">__block</span></code> variables did not implicitly retain during capture.</p>
+<p><code class="docutils literal notranslate"><span class="pre">__block</span></code> variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.</p>
+<p>With the exception of retains done as part of initializing a <code class="docutils literal notranslate"><span class="pre">__strong</span></code>
+parameter variable or reading a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+<code class="docutils literal notranslate"><span class="pre">Block_copy</span></code>.  The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.</p>
+</div>
+<div class="section" id="exceptions">
+<span id="arc-misc-exceptions"></span><h3><a class="toc-backref" href="#id52">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
+<p>By default in Objective C, ARC is not exception-safe for normal releases:</p>
+<ul class="simple">
+<li>It does not end the lifetime of <code class="docutils literal notranslate"><span class="pre">__strong</span></code> variables when their scopes are
+abnormally terminated by an exception.</li>
+<li>It does not perform releases which would occur at the end of a
+full-expression if that full-expression throws an exception.</li>
+</ul>
+<p>A program may be compiled with the option <code class="docutils literal notranslate"><span class="pre">-fobjc-arc-exceptions</span></code> in order to
+enable these, or with the option <code class="docutils literal notranslate"><span class="pre">-fno-objc-arc-exceptions</span></code> to explicitly
+disable them, with the last such argument “winning”.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The standard Cocoa convention is that exceptions signal programmer error and
+are not intended to be recovered from.  Making code exceptions-safe by
+default would impose severe runtime and code size penalties on code that
+typically does not actually care about exceptions safety.  Therefore,
+ARC-generated code leaks by default on exceptions, which is just fine if the
+process is going to be immediately terminated anyway.  Programs which do care
+about recovering from exceptions should enable the option.</p>
+</div>
+<p>In Objective-C++, <code class="docutils literal notranslate"><span class="pre">-fobjc-arc-exceptions</span></code> is enabled by default.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+introduces.  C++ programmers who have not already disabled exceptions are
+much more likely to actual require exception-safety.</p>
+</div>
+<p>ARC does end the lifetimes of <code class="docutils literal notranslate"><span class="pre">__weak</span></code> objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The consequence of a local <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object not being destroyed is very
+likely to be corruption of the Objective-C runtime, so we want to be safer
+here.  Of course, potentially massive leaks are about as likely to take down
+the process as this corruption is if the program does try to recover from
+exceptions.</p>
+</div>
+</div>
+<div class="section" id="interior-pointers">
+<span id="arc-misc-interior"></span><h3><a class="toc-backref" href="#id53">Interior pointers</a><a class="headerlink" href="#interior-pointers" title="Permalink to this headline">¶</a></h3>
+<p>An Objective-C method returning a non-retainable pointer may be annotated with
+the <code class="docutils literal notranslate"><span class="pre">objc_returns_inner_pointer</span></code> attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed.  When such a message is sent to an
+object, the object’s lifetime will be extended until at least the earliest of:</p>
+<ul class="simple">
+<li>the last use of the returned pointer, or any pointer derived from it, in the
+calling function or</li>
+<li>the autorelease pool is restored to a previous state.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Rationale: not all memory and resources are managed with reference counts; it
+is common for objects to manage private resources in their own, private way.
+Typically these resources are completely encapsulated within the object, but
+some classes offer their users direct access for efficiency.  If ARC is not
+aware of methods that return such “interior” pointers, its optimizations can
+cause the owning object to be reclaimed too soon.  This attribute informs ARC
+that it must tread lightly.</p>
+<p class="last">The extension rules are somewhat intentionally vague.  The autorelease pool
+limit is there to permit a simple implementation to simply retain and
+autorelease the receiver.  The other limit permits some amount of
+optimization.  The phrase “derived from” is intended to encompass the results
+both of pointer transformations, such as casts and arithmetic, and of loading
+from such derived pointers; furthermore, it applies whether or not such
+derivations are applied directly in the calling code or by other utility code
+(for example, the C library routine <code class="docutils literal notranslate"><span class="pre">strchr</span></code>).  However, the implementation
+never need account for uses after a return from the code which calls the
+method returning an interior pointer.</p>
+</div>
+<p>As an exception, no extension is required if the receiver is loaded directly
+from a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object with <a class="reference internal" href="#arc-optimization-precise"><span class="std std-ref">precise lifetime semantics</span></a>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Implicit autoreleases carry the risk of significantly inflating memory use,
+so it’s important to provide users a way of avoiding these autoreleases.
+Tying this to precise lifetime semantics is ideal, as for local variables
+this requires a very explicit annotation, which allows ARC to trust the user
+with good cheer.</p>
+</div>
+</div>
+<div class="section" id="c-retainable-pointer-types">
+<span id="arc-misc-c-retainable"></span><h3><a class="toc-backref" href="#id54">C retainable pointer types</a><a class="headerlink" href="#c-retainable-pointer-types" title="Permalink to this headline">¶</a></h3>
+<p>A type is a <span class="arc-term">C retainable pointer type</span> if it is a pointer to
+(possibly qualified) <code class="docutils literal notranslate"><span class="pre">void</span></code> or a pointer to a (possibly qualifier) <code class="docutils literal notranslate"><span class="pre">struct</span></code>
+or <code class="docutils literal notranslate"><span class="pre">class</span></code> type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC does not manage pointers of CoreFoundation type (or any of the related
+families of retainable C pointers which interoperate with Objective-C for
+retain/release operation).  In fact, ARC does not even know how to
+distinguish these types from arbitrary C pointer types.  The intent of this
+concept is to filter out some obviously non-object types while leaving a hook
+for later tightening if a means of exhaustively marking CF types is made
+available.</p>
+</div>
+<div class="section" id="auditing-of-c-retainable-pointer-interfaces">
+<span id="arc-misc-c-retainable-audit"></span><h4><a class="toc-backref" href="#id55">Auditing of C retainable pointer interfaces</a><a class="headerlink" href="#auditing-of-c-retainable-pointer-interfaces" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>A C function may be marked with the <code class="docutils literal notranslate"><span class="pre">cf_audited_transfer</span></code> attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:</p>
+<ul class="simple">
+<li>A parameter of C retainable pointer type is assumed to not be consumed
+unless it is marked with the <code class="docutils literal notranslate"><span class="pre">cf_consumed</span></code> attribute, and</li>
+<li>A result of C retainable pointer type is assumed to not be returned retained
+unless the function is either marked <code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code> or it follows
+the create/copy naming convention and is not marked
+<code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code>.</li>
+</ul>
+<p>A function obeys the <span class="arc-term">create/copy</span> naming convention if its name
+contains as a substring:</p>
+<ul class="simple">
+<li>either “Create” or “Copy” not followed by a lowercase letter, or</li>
+<li>either “create” or “copy” not followed by a lowercase letter and
+not preceded by any letter, whether uppercase or lowercase.</li>
+</ul>
+<p>A second attribute, <code class="docutils literal notranslate"><span class="pre">cf_unknown_transfer</span></code>, signifies that a function’s
+transfer semantics cannot be accurately captured using any of these
+annotations.  A program is ill-formed if it annotates the same function with
+both <code class="docutils literal notranslate"><span class="pre">cf_audited_transfer</span></code> and <code class="docutils literal notranslate"><span class="pre">cf_unknown_transfer</span></code>.</p>
+<p>A pragma is provided to facilitate the mass annotation of interfaces:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang arc_cf_code_audited begin</span>
+<span class="p">...</span>
+<span class="cp">#pragma clang arc_cf_code_audited end</span>
+</pre></div>
+</div>
+<p>All C functions declared within the extent of this pragma are treated as if
+annotated with the <code class="docutils literal notranslate"><span class="pre">cf_audited_transfer</span></code> attribute unless they otherwise have
+the <code class="docutils literal notranslate"><span class="pre">cf_unknown_transfer</span></code> attribute.  The pragma is accepted in all language
+modes.  A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.</p>
+<p>It is possible to test for all the features in this section with
+<code class="docutils literal notranslate"><span class="pre">__has_feature(arc_cf_code_audited)</span></code>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">A significant inconvenience in ARC programming is the necessity of
+interacting with APIs based around C retainable pointers.  These features are
+designed to make it relatively easy for API authors to quickly review and
+annotate their interfaces, in turn improving the fidelity of tools such as
+the static analyzer and ARC.  The single-file restriction on the pragma is
+designed to eliminate the risk of accidentally annotating some other header’s
+interfaces.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="runtime-support">
+<span id="arc-runtime"></span><h2><a class="toc-backref" href="#id56">Runtime support</a><a class="headerlink" href="#runtime-support" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler.  This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the “Itanium” generic ABI for C++.</p>
+<p>Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object is inadequately
+aligned for an object of type <code class="docutils literal notranslate"><span class="pre">id</span></code>.  The other qualifiers may be used on
+explicitly under-aligned memory.</p>
+<p>The runtime tracks <code class="docutils literal notranslate"><span class="pre">__weak</span></code> objects which holds non-null values.  It is
+undefined behavior to direct modify a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object which is being tracked
+by the runtime except through an
+<a class="reference internal" href="#arc-runtime-objc-storeweak"><span class="std std-ref">objc_storeWeak</span></a>,
+<a class="reference internal" href="#arc-runtime-objc-destroyweak"><span class="std std-ref">objc_destroyWeak</span></a>, or
+<a class="reference internal" href="#arc-runtime-objc-moveweak"><span class="std std-ref">objc_moveWeak</span></a> call.</p>
+<p>The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Several of these functions are semantically equivalent to a message send; we
+emit calls to C functions instead because:</p>
+<ul class="simple">
+<li>the machine code to do so is significantly smaller,</li>
+<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
+<li>a sufficient sophisticated runtime may be able to avoid the message send in
+common cases.</li>
+</ul>
+<p class="last">Several other of these functions are “fused” operations which can be
+described entirely in terms of other operations.  We use the fused operations
+primarily as a code-size optimization, although in some cases there is also a
+real potential for avoiding redundant operations in the runtime.</p>
+</div>
+<div class="section" id="arc-runtime-objc-autorelease">
+<span id="id-objc-autorelease-id-value"></span><h3><a class="toc-backref" href="#id57"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-autorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+<code class="docutils literal notranslate"><span class="pre">autorelease</span></code> message.</p>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpop-void-pool">
+<span id="arc-runtime-objc-autoreleasepoolpop"></span><h3><a class="toc-backref" href="#id58"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></code></a><a class="headerlink" href="#void-objc-autoreleasepoolpop-void-pool" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">pool</span></code> is the result of a previous call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasepoolpush"><span class="std std-ref">objc_autoreleasePoolPush</span></a> on the
+current thread, where neither <code class="docutils literal notranslate"><span class="pre">pool</span></code> nor any enclosing pool have previously
+been popped.</p>
+<p>Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing <code class="docutils literal notranslate"><span class="pre">pool</span></code>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpush-void">
+<span id="arc-runtime-objc-autoreleasepoolpush"></span><h3><a class="toc-backref" href="#id59"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></code></a><a class="headerlink" href="#void-objc-autoreleasepoolpush-void" title="Permalink to this headline">¶</a></h3>
+<p>Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque “handle” to it.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While the interface is described as an explicit hierarchy of pools, the rules
+allow the implementation to just keep a stack of objects, using the stack
+depth as the opaque pool handle.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-autoreleasereturnvalue">
+<span id="id-objc-autoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id60"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-autoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+<a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue"><span class="std std-ref">objc_retainAutoreleasedReturnValue</span></a> for the same object in an
+enclosing call frame.  If this is not possible, the object is autoreleased as
+above.</p>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="void-objc-copyweak-id-dest-id-src">
+<span id="arc-runtime-objc-copyweak"></span><h3><a class="toc-backref" href="#id61"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a><a class="headerlink" href="#void-objc-copyweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">src</span></code> is a valid pointer which either contains a null pointer
+or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.  <code class="docutils literal notranslate"><span class="pre">dest</span></code> is a valid pointer
+which has not been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.</p>
+<p><code class="docutils literal notranslate"><span class="pre">dest</span></code> is initialized to be equivalent to <code class="docutils literal notranslate"><span class="pre">src</span></code>, potentially registering it
+with the runtime.  Equivalent to the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">objc_copyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="kt">id</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_release</span><span class="p">(</span><span class="n">objc_initWeak</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">src</span><span class="p">)));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal notranslate"><span class="pre">src</span></code>.</p>
+</div>
+<div class="section" id="void-objc-destroyweak-id-object">
+<span id="arc-runtime-objc-destroyweak"></span><h3><a class="toc-backref" href="#id62"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#void-objc-destroyweak-id-object" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer which either contains a null
+pointer or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.</p>
+<p><code class="docutils literal notranslate"><span class="pre">object</span></code> is unregistered as a weak object, if it ever was.  The current value
+of <code class="docutils literal notranslate"><span class="pre">object</span></code> is left unspecified; otherwise, equivalent to the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">objc_destroyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Does not need to be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on
+<code class="docutils literal notranslate"><span class="pre">object</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-initweak">
+<span id="id-objc-initweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id63"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-initweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer which has not been registered as
+a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.  <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is a null pointer or the object to which it points has begun
+deallocation, <code class="docutils literal notranslate"><span class="pre">object</span></code> is zero-initialized.  Otherwise, <code class="docutils literal notranslate"><span class="pre">object</span></code> is
+registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object pointing to <code class="docutils literal notranslate"><span class="pre">value</span></code>.  Equivalent to the
+following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_initWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="nb">nil</span><span class="p">;</span>
+  <span class="k">return</span> <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Returns the value of <code class="docutils literal notranslate"><span class="pre">object</span></code> after the call.</p>
+<p>Does not need to be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on
+<code class="docutils literal notranslate"><span class="pre">object</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-loadweak">
+<span id="id-objc-loadweak-id-object"></span><h3><a class="toc-backref" href="#id64"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#arc-runtime-objc-loadweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer which either contains a null
+pointer or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">object</span></code> is registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object, and the last value stored
+into <code class="docutils literal notranslate"><span class="pre">object</span></code> has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it.  Otherwise returns null.  Equivalent to
+the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_loadWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">object</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal notranslate"><span class="pre">object</span></code>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Loading weak references would be inherently prone to race conditions without
+the retain.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-loadweakretained">
+<span id="id-objc-loadweakretained-id-object"></span><h3><a class="toc-backref" href="#id65"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#arc-runtime-objc-loadweakretained" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer which either contains a null
+pointer or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">object</span></code> is registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object, and the last value stored
+into <code class="docutils literal notranslate"><span class="pre">object</span></code> has not yet been deallocated or begun deallocation, retains
+that value and returns it.  Otherwise returns null.</p>
+<p>Must be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal notranslate"><span class="pre">object</span></code>.</p>
+</div>
+<div class="section" id="void-objc-moveweak-id-dest-id-src">
+<span id="arc-runtime-objc-moveweak"></span><h3><a class="toc-backref" href="#id66"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a><a class="headerlink" href="#void-objc-moveweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">src</span></code> is a valid pointer which either contains a null pointer
+or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.  <code class="docutils literal notranslate"><span class="pre">dest</span></code> is a valid pointer
+which has not been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.</p>
+<p><code class="docutils literal notranslate"><span class="pre">dest</span></code> is initialized to be equivalent to <code class="docutils literal notranslate"><span class="pre">src</span></code>, potentially registering it
+with the runtime.  <code class="docutils literal notranslate"><span class="pre">src</span></code> may then be left in its original state, in which
+case this call is equivalent to <a class="reference internal" href="#arc-runtime-objc-copyweak"><span class="std std-ref">objc_copyWeak</span></a>, or it may be left as null.</p>
+<p>Must be atomic with respect to calls to <code class="docutils literal notranslate"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal notranslate"><span class="pre">src</span></code>.</p>
+</div>
+<div class="section" id="void-objc-release-id-value">
+<span id="arc-runtime-objc-release"></span><h3><a class="toc-backref" href="#id67"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#void-objc-release-id-value" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it performs a
+release operation exactly as if the object had been sent the <code class="docutils literal notranslate"><span class="pre">release</span></code>
+message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retain">
+<span id="id-objc-retain-id-value"></span><h3><a class="toc-backref" href="#id68"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retain" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it performs a retain
+operation exactly as if the object had been sent the <code class="docutils literal notranslate"><span class="pre">retain</span></code> message.</p>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautorelease">
+<span id="id-objc-retainautorelease-id-value"></span><h3><a class="toc-backref" href="#id69"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by an autorelease operation.  Equivalent to the following
+code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_retainAutorelease</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasereturnvalue">
+<span id="id-objc-retainautoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id70"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by the operation described in
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><span class="std std-ref">objc_autoreleaseReturnValue</span></a>.
+Equivalent to the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_retainAutoreleaseReturnValue</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autoreleaseReturnValue</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasedreturnvalue">
+<span id="id-objc-retainautoreleasedreturnvalue-id-value"></span><h3><a class="toc-backref" href="#id71"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasedreturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><span class="std std-ref">objc_autoreleaseReturnValue</span></a> on
+<code class="docutils literal notranslate"><span class="pre">value</span></code> in a recently-called function or something it calls.  If that fails,
+it performs a retain operation exactly like <a class="reference internal" href="#arc-runtime-objc-retain"><span class="std std-ref">objc_retain</span></a>.</p>
+<p>Always returns <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainblock">
+<span id="id-objc-retainblock-id-value"></span><h3><a class="toc-backref" href="#id72"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainblock" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid block object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is null, this call has no effect.  Otherwise, if the block pointed
+to by <code class="docutils literal notranslate"><span class="pre">value</span></code> is still on the stack, it is copied to the heap and the address
+of the copy is returned.  Otherwise a retain operation is performed on the
+block exactly as if it had been sent the <code class="docutils literal notranslate"><span class="pre">retain</span></code> message.</p>
+</div>
+<div class="section" id="void-objc-storestrong-id-object-id-value">
+<span id="arc-runtime-objc-storestrong"></span><h3><a class="toc-backref" href="#id73"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#void-objc-storestrong-id-object-id-value" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer to a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object which is
+adequately aligned for a pointer.  <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a pointer to a valid
+object.</p>
+<p>Performs the complete sequence for assigning to a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object of
+non-block type <a class="footnote-reference" href="#id3" id="id2">[*]</a>.  Equivalent to the following code:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">objc_storeStrong</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">id</span> <span class="n">oldValue</span> <span class="o">=</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
+  <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">value</span> <span class="k">retain</span><span class="p">];</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="n">value</span><span class="p">;</span>
+  <span class="p">[</span><span class="n">oldValue</span> <span class="k">release</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[*]</a></td><td>This does not imply that a <code class="docutils literal notranslate"><span class="pre">__strong</span></code> object of block type is an
+invalid argument to this function. Rather it implies that an <code class="docutils literal notranslate"><span class="pre">objc_retain</span></code>
+and not an <code class="docutils literal notranslate"><span class="pre">objc_retainBlock</span></code> operation will be emitted if the argument is
+a block.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="arc-runtime-objc-storeweak">
+<span id="id-objc-storeweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id74"><code class="docutils literal notranslate"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-storeweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <code class="docutils literal notranslate"><span class="pre">object</span></code> is a valid pointer which either contains a null
+pointer or has been registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object.  <code class="docutils literal notranslate"><span class="pre">value</span></code> is null or a
+pointer to a valid object.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">value</span></code> is a null pointer or the object to which it points has begun
+deallocation, <code class="docutils literal notranslate"><span class="pre">object</span></code> is assigned null and unregistered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code>
+object.  Otherwise, <code class="docutils literal notranslate"><span class="pre">object</span></code> is registered as a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> object or has its
+registration updated to point to <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
+<p>Returns the value of <code class="docutils literal notranslate"><span class="pre">object</span></code> after the call.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+      
+        <p>
+        «  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCommandLineReference.html">Clang command line argument reference</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer" role="contentinfo">
+        © Copyright 2007-2019, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/9.0.0/tools/clang/docs/Block-ABI-Apple.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/Block-ABI-Apple.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/Block-ABI-Apple.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/Block-ABI-Apple.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,906 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Block Implementation Specification — Clang 9 documentation</title>
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" />
+    <link rel="prev" title="Language Specification for Blocks" href="BlockLanguageSpec.html" /> 
+  </head><body>
+      <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+          <span>Clang 9 documentation</span></a></h1>
+        <h2 class="heading"><span>Block Implementation Specification</span></h2>
+      </div>
+      <div class="topnav" role="navigation" aria-label="top navigation">
+      
+        <p>
+        «  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="block-implementation-specification">
+<h1>Block Implementation Specification<a class="headerlink" href="#block-implementation-specification" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#history" id="id1">History</a></li>
+<li><a class="reference internal" href="#high-level" id="id2">High Level</a></li>
+<li><a class="reference internal" href="#imported-variables" id="id3">Imported Variables</a><ul>
+<li><a class="reference internal" href="#imported-const-copy-variables" id="id4">Imported <code class="docutils literal notranslate"><span class="pre">const</span></code> copy variables</a></li>
+<li><a class="reference internal" href="#imported-const-copy-of-block-reference" id="id5">Imported <code class="docutils literal notranslate"><span class="pre">const</span></code> copy of <code class="docutils literal notranslate"><span class="pre">Block</span></code> reference</a><ul>
+<li><a class="reference internal" href="#importing-attribute-nsobject-variables" id="id6">Importing <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#imported-block-marked-variables" id="id7">Imported <code class="docutils literal notranslate"><span class="pre">__block</span></code> marked variables</a><ul>
+<li><a class="reference internal" href="#layout-of-block-marked-variables" id="id8">Layout of <code class="docutils literal notranslate"><span class="pre">__block</span></code> marked variables</a></li>
+<li><a class="reference internal" href="#access-to-block-variables-from-within-its-lexical-scope" id="id9">Access to <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables from within its lexical scope</a></li>
+<li><a class="reference internal" href="#importing-block-variables-into-blocks" id="id10">Importing <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables into <code class="docutils literal notranslate"><span class="pre">Blocks</span></code></a></li>
+<li><a class="reference internal" href="#importing-attribute-nsobject-block-variables" id="id11">Importing <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables</a></li>
+<li><a class="reference internal" href="#block-escapes" id="id12"><code class="docutils literal notranslate"><span class="pre">__block</span></code> escapes</a></li>
+<li><a class="reference internal" href="#nesting" id="id13">Nesting</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-extensions-to-blocks" id="id14">Objective C Extensions to <code class="docutils literal notranslate"><span class="pre">Blocks</span></code></a><ul>
+<li><a class="reference internal" href="#importing-objects" id="id15">Importing Objects</a></li>
+<li><a class="reference internal" href="#blocks-as-objects" id="id16"><code class="docutils literal notranslate"><span class="pre">Blocks</span></code> as Objects</a></li>
+<li><a class="reference internal" href="#weak-block-support" id="id17"><code class="docutils literal notranslate"><span class="pre">__weak</span> <span class="pre">__block</span></code> Support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-support" id="id18">C++ Support</a></li>
+<li><a class="reference internal" href="#runtime-helper-functions" id="id19">Runtime Helper Functions</a></li>
+<li><a class="reference internal" href="#copyright" id="id20">Copyright</a></li>
+</ul>
+</div>
+<div class="section" id="history">
+<h2><a class="toc-backref" href="#id1">History</a><a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/7/14 - created.</li>
+<li>2008/8/21 - revised, C++.</li>
+<li>2008/9/24 - add <code class="docutils literal notranslate"><span class="pre">NULL</span></code> <code class="docutils literal notranslate"><span class="pre">isa</span></code> field to <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage.</li>
+<li>2008/10/1 - revise block layout to use a <code class="docutils literal notranslate"><span class="pre">static</span></code> descriptor structure.</li>
+<li>2008/10/6 - revise block layout to use an unsigned long int flags.</li>
+<li>2008/10/28 - specify use of <code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> and
+<code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code> for all “Object” types in helper functions.</li>
+<li>2008/10/30 - revise new layout to have invoke function in same place.</li>
+<li>2008/10/30 - add <code class="docutils literal notranslate"><span class="pre">__weak</span></code> support.</li>
+<li>2010/3/16 - rev for stret return, signature field.</li>
+<li>2010/4/6 - improved wording.</li>
+<li>2013/1/6 - improved wording and converted to rst.</li>
+</ul>
+<p>This document describes the Apple ABI implementation specification of Blocks.</p>
+<p>The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.</p>
+<p>Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.</p>
+</div>
+<div class="section" id="high-level">
+<h2><a class="toc-backref" href="#id2">High Level</a><a class="headerlink" href="#high-level" title="Permalink to this headline">¶</a></h2>
+<p>The ABI of <code class="docutils literal notranslate"><span class="pre">Blocks</span></code> consist of their layout and the runtime functions required
+by the compiler.  A <code class="docutils literal notranslate"><span class="pre">Block</span></code> consists of a structure of the following form:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">Block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="p">...);</span>
+    <span class="k">struct</span> <span class="n">Block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>         <span class="c1">// NULL</span>
+        <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>         <span class="c1">// sizeof(struct Block_literal_1)</span>
+        <span class="c1">// optional helper functions</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>     <span class="c1">// IFF (1<<25)</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>             <span class="c1">// IFF (1<<25)</span>
+        <span class="c1">// required ABI.2010.3.16</span>
+        <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">signature</span><span class="p">;</span>                         <span class="c1">// IFF (1<<30)</span>
+    <span class="p">}</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="c1">// imported variables</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The following flags bits are in use thusly for a possible ABI.2010.3.16:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="p">{</span>
+    <span class="c1">// Set to true on blocks that have captures (and thus are not true</span>
+    <span class="c1">// global blocks) but are known not to escape for various other</span>
+    <span class="c1">// reasons. For backward compatiblity with old runtimes, whenever</span>
+    <span class="c1">// BLOCK_IS_NOESCAPE is set, BLOCK_IS_GLOBAL is set too. Copying a</span>
+    <span class="c1">// non-escaping block returns the original block and releasing such a</span>
+    <span class="c1">// block is a no-op, which is exactly how global blocks are handled.</span>
+    <span class="n">BLOCK_IS_NOESCAPE</span>      <span class="o">=</span>  <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">23</span><span class="p">),</span>
+
+    <span class="n">BLOCK_HAS_COPY_DISPOSE</span> <span class="o">=</span>  <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">25</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_CTOR</span> <span class="o">=</span>          <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">26</span><span class="p">),</span> <span class="c1">// helpers have C++ code</span>
+    <span class="n">BLOCK_IS_GLOBAL</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">28</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_STRET</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">29</span><span class="p">),</span> <span class="c1">// IFF BLOCK_HAS_SIGNATURE</span>
+    <span class="n">BLOCK_HAS_SIGNATURE</span> <span class="o">=</span>     <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">30</span><span class="p">),</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">switch</span> <span class="p">(</span><span class="n">flags</span> <span class="o">&</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">))</span> <span class="p">{</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span><span class="o">:</span>      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span><span class="o">:</span>      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">2</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span><span class="o">:</span> <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">regular</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span><span class="o">:</span> <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">stret</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span><span class="p">,</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The signature field is not always populated.</p>
+<p>The following discussions are presented as 10.6.ABI otherwise.</p>
+<p><code class="docutils literal notranslate"><span class="pre">Block</span></code> literals may occur within functions where the structure is created in
+stack local memory.  They may also appear as initialization expressions for
+<code class="docutils literal notranslate"><span class="pre">Block</span></code> variables of global or <code class="docutils literal notranslate"><span class="pre">static</span></code> local variables.</p>
+<p>When a <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal expression is evaluated the stack based structure is
+initialized as follows:</p>
+<ol class="arabic simple">
+<li>A <code class="docutils literal notranslate"><span class="pre">static</span></code> descriptor structure is declared and initialized as follows:</li>
+</ol>
+<blockquote>
+<div><p>a. The <code class="docutils literal notranslate"><span class="pre">invoke</span></code> function pointer is set to a function that takes the
+<code class="docutils literal notranslate"><span class="pre">Block</span></code> structure as its first argument and the rest of the arguments (if
+any) to the <code class="docutils literal notranslate"><span class="pre">Block</span></code> and executes the <code class="docutils literal notranslate"><span class="pre">Block</span></code> compound statement.</p>
+<p>b. The <code class="docutils literal notranslate"><span class="pre">size</span></code> field is set to the size of the following <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal
+structure.</p>
+<p>c. The <code class="docutils literal notranslate"><span class="pre">copy_helper</span></code> and <code class="docutils literal notranslate"><span class="pre">dispose_helper</span></code> function pointers are set to
+respective helper functions if they are required by the <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal.</p>
+</div></blockquote>
+<ol class="arabic" start="2">
+<li><p class="first">A stack (or global) <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal data structure is created and
+initialized as follows:</p>
+<p>a. The <code class="docutils literal notranslate"><span class="pre">isa</span></code> field is set to the address of the external
+<code class="docutils literal notranslate"><span class="pre">_NSConcreteStackBlock</span></code>, which is a block of uninitialized memory supplied
+in <code class="docutils literal notranslate"><span class="pre">libSystem</span></code>, or <code class="docutils literal notranslate"><span class="pre">_NSConcreteGlobalBlock</span></code> if this is a static or file
+level <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal.</p>
+<p>b. The <code class="docutils literal notranslate"><span class="pre">flags</span></code> field is set to zero unless there are variables imported
+into the <code class="docutils literal notranslate"><span class="pre">Block</span></code> that need helper functions for program level
+<code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> and <code class="docutils literal notranslate"><span class="pre">Block_release()</span></code> operations, in which case the
+(1<<25) flags bit is set.</p>
+</li>
+</ol>
+<p>As an example, the <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal expression:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>would cause the following to be created on a 32-bit system:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_1</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_1</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span><span class="p">),</span> <span class="n">__block_invoke_1</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and where the <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal itself appears:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_1</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A <code class="docutils literal notranslate"><span class="pre">Block</span></code> imports other <code class="docutils literal notranslate"><span class="pre">Block</span></code> references, <code class="docutils literal notranslate"><span class="pre">const</span></code> copies of other
+variables, and variables marked <code class="docutils literal notranslate"><span class="pre">__block</span></code>.  In Objective-C, variables may
+additionally be objects.</p>
+<p>When a <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal expression is used as the initial value of a global
+or <code class="docutils literal notranslate"><span class="pre">static</span></code> local variable, it is initialized as follows:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">__block_literal_1</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteGlobalBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">28</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_1</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the <code class="docutils literal notranslate"><span class="pre">flags</span></code> field, and otherwise it is the same as for
+stack based <code class="docutils literal notranslate"><span class="pre">Block</span></code> literals.  This is an optimization that can be used for
+any <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal that imports no <code class="docutils literal notranslate"><span class="pre">const</span></code> or <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage
+variables.</p>
+</div>
+<div class="section" id="imported-variables">
+<h2><a class="toc-backref" href="#id3">Imported Variables</a><a class="headerlink" href="#imported-variables" title="Permalink to this headline">¶</a></h2>
+<p>Variables of <code class="docutils literal notranslate"><span class="pre">auto</span></code> storage class are imported as <code class="docutils literal notranslate"><span class="pre">const</span></code> copies.  Variables
+of <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage class are imported as a pointer to an enclosing data
+structure.  Global variables are simply referenced and not considered as
+imported.</p>
+<div class="section" id="imported-const-copy-variables">
+<h3><a class="toc-backref" href="#id4">Imported <code class="docutils literal notranslate"><span class="pre">const</span></code> copy variables</a><a class="headerlink" href="#imported-const-copy-variables" title="Permalink to this headline">¶</a></h3>
+<p>Automatic storage variables not marked with <code class="docutils literal notranslate"><span class="pre">__block</span></code> are imported as
+<code class="docutils literal notranslate"><span class="pre">const</span></code> copies.</p>
+<p>The simplest example is that of importing a variable of type <code class="docutils literal notranslate"><span class="pre">int</span></code>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="n">x</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+<span class="n">vv</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>which would be compiled to:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_2</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_2</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span><span class="p">)</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="n">__block_literal_2</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_2</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_2</span><span class="p">,</span>
+      <span class="n">x</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>In summary, scalars, structures, unions, and function pointers are generally
+imported as <code class="docutils literal notranslate"><span class="pre">const</span></code> copies with no need for helper functions.</p>
+</div>
+<div class="section" id="imported-const-copy-of-block-reference">
+<h3><a class="toc-backref" href="#id5">Imported <code class="docutils literal notranslate"><span class="pre">const</span></code> copy of <code class="docutils literal notranslate"><span class="pre">Block</span></code> reference</a><a class="headerlink" href="#imported-const-copy-of-block-reference" title="Permalink to this headline">¶</a></h3>
+<p>The first case where copy and dispose helper functions are required is for the
+case of when a <code class="docutils literal notranslate"><span class="pre">Block</span></code> itself is imported.  In this case both a
+<code class="docutils literal notranslate"><span class="pre">copy_helper</span></code> function and a <code class="docutils literal notranslate"><span class="pre">dispose_helper</span></code> function are needed.  The
+<code class="docutils literal notranslate"><span class="pre">copy_helper</span></code> function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the <code class="docutils literal notranslate"><span class="pre">Block</span></code>. The
+runtime functions are all described in <a class="reference internal" href="#runtimehelperfunctions"><span class="std std-ref">Runtime Helper Functions</span></a>.</p>
+<p>A quick example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">existingBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">existingBlock</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">vv</span><span class="p">();</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="p">{</span>
+   <span class="p">...;</span> <span class="c1">// existing block</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="o">*</span><span class="k">const</span> <span class="n">existingBlock</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">// was _Block_destroy</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_4</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_4</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="mi">0</span><span class="p">,</span>
+    <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span><span class="p">),</span>
+    <span class="n">__block_copy_4</span><span class="p">,</span>
+    <span class="n">__block_dispose_4</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and where said <code class="docutils literal notranslate"><span class="pre">Block</span></code> is used:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span>
+      <span class="n">__block_invoke_4</span><span class="p">,</span>
+      <span class="o">&</span> <span class="n">__block_descriptor_4</span>
+      <span class="n">existingBlock</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="importing-attribute-nsobject-variables">
+<h4><a class="toc-backref" href="#id6">Importing <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> variables</a><a class="headerlink" href="#importing-attribute-nsobject-variables" title="Permalink to this headline">¶</a></h4>
+<p>GCC introduces <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> on structure pointers to mean “this
+is an object”.  This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. <code class="docutils literal notranslate"><span class="pre">CFStringRef</span></code>, <code class="docutils literal notranslate"><span class="pre">CFArrayRef</span></code>,
+etc.  When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated.  The copy helper functions generated by the compiler should use the
+<code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> runtime helper function and in the dispose helper the
+<code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code> runtime helper function should be called.</p>
+<p>For example, <code class="docutils literal notranslate"><span class="pre">Block</span></code> foo in the following:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">Opaque</span> <span class="o">*</span><span class="nf">__attribute__</span><span class="p">((</span><span class="n">NSObject</span><span class="p">))</span> <span class="n">objectPointer</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="p">...</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">foo</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span>  <span class="n">CFPrint</span><span class="p">(</span><span class="n">objectPointer</span><span class="p">);</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>would have the following helper functions generated:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">__block_copy_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="imported-block-marked-variables">
+<h3><a class="toc-backref" href="#id7">Imported <code class="docutils literal notranslate"><span class="pre">__block</span></code> marked variables</a><a class="headerlink" href="#imported-block-marked-variables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="layout-of-block-marked-variables">
+<h4><a class="toc-backref" href="#id8">Layout of <code class="docutils literal notranslate"><span class="pre">__block</span></code> marked variables</a><a class="headerlink" href="#layout-of-block-marked-variables" title="Permalink to this headline">¶</a></h4>
+<p>The compiler must embed variables that are marked <code class="docutils literal notranslate"><span class="pre">__block</span></code> in a specialized
+structure of the form:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">Block_byref</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Variables of certain types require helper functions for when <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code>
+and <code class="docutils literal notranslate"><span class="pre">Block_release()</span></code> are performed upon a referencing <code class="docutils literal notranslate"><span class="pre">Block</span></code>.  At the “C”
+level only variables that are of type <code class="docutils literal notranslate"><span class="pre">Block</span></code> or ones that have
+<code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> marked require helper functions.  In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="c1">// helper functions called via Block_copy() and Block_release()</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="kt">void</span>  <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The structure is initialized such that:</p>
+<blockquote>
+<div><p>a. The <code class="docutils literal notranslate"><span class="pre">forwarding</span></code> pointer is set to the beginning of its enclosing
+structure.</p>
+<p>b. The <code class="docutils literal notranslate"><span class="pre">size</span></code> field is initialized to the total size of the enclosing
+structure.</p>
+<p>c. The <code class="docutils literal notranslate"><span class="pre">flags</span></code> field is set to either 0 if no helper functions are needed
+or (1<<25) if they are.</p>
+<ol class="loweralpha simple" start="4">
+<li>The helper functions are initialized (if present).</li>
+<li>The variable itself is set to its initial value.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">isa</span></code> field is set to <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="access-to-block-variables-from-within-its-lexical-scope">
+<h4><a class="toc-backref" href="#id9">Access to <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables from within its lexical scope</a><a class="headerlink" href="#access-to-block-variables-from-within-its-lexical-scope" title="Permalink to this headline">¶</a></h4>
+<p>In order to “move” the variable to the heap upon a <code class="docutils literal notranslate"><span class="pre">copy_helper</span></code> operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures <code class="docutils literal notranslate"><span class="pre">forwarding</span></code> pointer.  For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="n">i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would be rewritten to be:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+  <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+  <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="mi">10</span> <span class="p">};</span>
+
+<span class="n">i</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the case of a <code class="docutils literal notranslate"><span class="pre">Block</span></code> reference variable being marked <code class="docutils literal notranslate"><span class="pre">__block</span></code> the
+helper code generated must use the <code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> and
+<code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code> routines supplied by the runtime to make the
+copies. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__block</span> <span class="nf">void</span> <span class="p">(</span><span class="n">voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">blockA</span><span class="p">;</span>
+<span class="n">voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would translate into:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">captured_voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_keep_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_dispose_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">)}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="n">voidBlock</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">voidBlock</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">),</span>
+    <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_keep_helper</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_dispose_helper</span><span class="p">,</span>
+    <span class="p">.</span><span class="n">captured_voidBlock</span><span class="o">=</span><span class="n">blockA</span> <span class="p">)};</span>
+
+<span class="n">voidBlock</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-block-variables-into-blocks">
+<h4><a class="toc-backref" href="#id10">Importing <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables into <code class="docutils literal notranslate"><span class="pre">Blocks</span></code></a><a class="headerlink" href="#importing-block-variables-into-blocks" title="Permalink to this headline">¶</a></h4>
+<p>A <code class="docutils literal notranslate"><span class="pre">Block</span></code> that uses a <code class="docutils literal notranslate"><span class="pre">__block</span></code> variable in its compound statement body must
+import the variable and emit <code class="docutils literal notranslate"><span class="pre">copy_helper</span></code> and <code class="docutils literal notranslate"><span class="pre">dispose_helper</span></code> helper
+functions that, in turn, call back into the runtime to actually copy or release
+the <code class="docutils literal notranslate"><span class="pre">byref</span></code> data block using the functions <code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> and
+<code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code>.</p>
+<p>For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// set to NULL</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">};</span>
+
+
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">i_holder</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">_block</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->captured_i, src->captured_i);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->captured_i);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">)</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">isa</span><span class="o">=</span><span class="nb">NULL</span><span class="p">,</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">i</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="p">.</span><span class="n">captured_i</span><span class="o">=</span><span class="mi">2</span> <span class="p">)};</span>
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_5</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">i</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-attribute-nsobject-block-variables">
+<h4><a class="toc-backref" href="#id11">Importing <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables</a><a class="headerlink" href="#importing-attribute-nsobject-block-variables" title="Permalink to this headline">¶</a></h4>
+<p>A <code class="docutils literal notranslate"><span class="pre">__block</span></code> variable that is also marked <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> should
+have <code class="docutils literal notranslate"><span class="pre">byref_keep</span></code> and <code class="docutils literal notranslate"><span class="pre">byref_dispose</span></code> helper functions that use
+<code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> and <code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code>.</p>
+</div>
+<div class="section" id="block-escapes">
+<h4><a class="toc-backref" href="#id12"><code class="docutils literal notranslate"><span class="pre">__block</span></code> escapes</a><a class="headerlink" href="#block-escapes" title="Permalink to this headline">¶</a></h4>
+<p>Because <code class="docutils literal notranslate"><span class="pre">Blocks</span></code> referencing <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables may have <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code>
+performed upon them the underlying storage for the variables may move to the
+heap.  In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required.  Otherwise
+the compiler must issue a call to potentially release any heap storage for
+<code class="docutils literal notranslate"><span class="pre">__block</span></code> variables at all escapes or terminations of their scope.  The call
+should be:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">&</span><span class="n">_block_byref_foo</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nesting">
+<h4><a class="toc-backref" href="#id13">Nesting</a><a class="headerlink" href="#nesting" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">Blocks</span></code> may contain <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal expressions.  Any variables used within
+inner blocks are imported into all enclosing <code class="docutils literal notranslate"><span class="pre">Block</span></code> scopes even if the
+variables are not used. This includes <code class="docutils literal notranslate"><span class="pre">const</span></code> imports as well as <code class="docutils literal notranslate"><span class="pre">__block</span></code>
+variables.</p>
+</div>
+</div>
+</div>
+<div class="section" id="objective-c-extensions-to-blocks">
+<h2><a class="toc-backref" href="#id14">Objective C Extensions to <code class="docutils literal notranslate"><span class="pre">Blocks</span></code></a><a class="headerlink" href="#objective-c-extensions-to-blocks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="importing-objects">
+<h3><a class="toc-backref" href="#id15">Importing Objects</a><a class="headerlink" href="#importing-objects" title="Permalink to this headline">¶</a></h3>
+<p>Objects should be treated as <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> variables; all
+<code class="docutils literal notranslate"><span class="pre">copy_helper</span></code>, <code class="docutils literal notranslate"><span class="pre">dispose_helper</span></code>, <code class="docutils literal notranslate"><span class="pre">byref_keep</span></code>, and <code class="docutils literal notranslate"><span class="pre">byref_dispose</span></code>
+helper functions should use <code class="docutils literal notranslate"><span class="pre">_Block_object_assign</span></code> and
+<code class="docutils literal notranslate"><span class="pre">_Block_object_dispose</span></code>.  There should be no code generated that uses
+<code class="docutils literal notranslate"><span class="pre">*-retain</span></code> or <code class="docutils literal notranslate"><span class="pre">*-release</span></code> methods.</p>
+</div>
+<div class="section" id="blocks-as-objects">
+<h3><a class="toc-backref" href="#id16"><code class="docutils literal notranslate"><span class="pre">Blocks</span></code> as Objects</a><a class="headerlink" href="#blocks-as-objects" title="Permalink to this headline">¶</a></h3>
+<p>The compiler will treat <code class="docutils literal notranslate"><span class="pre">Blocks</span></code> as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.</p>
+</div>
+<div class="section" id="weak-block-support">
+<h3><a class="toc-backref" href="#id17"><code class="docutils literal notranslate"><span class="pre">__weak</span> <span class="pre">__block</span></code> Support</a><a class="headerlink" href="#weak-block-support" title="Permalink to this headline">¶</a></h3>
+<p>Objective-C (and Objective-C++) support the <code class="docutils literal notranslate"><span class="pre">__weak</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">__block</span></code>
+variables.  Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions <code class="docutils literal notranslate"><span class="pre">objc_assign_weak</span></code> and <code class="docutils literal notranslate"><span class="pre">objc_read_weak</span></code>.  Both
+should continue to be used for all reads and writes of <code class="docutils literal notranslate"><span class="pre">__weak</span> <span class="pre">__block</span></code>
+variables:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">block</span><span class="o">-></span><span class="n">byref_i</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">__weak</span></code> variable is stored in a <code class="docutils literal notranslate"><span class="pre">_block_byref_foo</span></code> structure and the
+<code class="docutils literal notranslate"><span class="pre">Block</span></code> has copy and dispose helpers for this structure that call:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In turn, the <code class="docutils literal notranslate"><span class="pre">block_byref</span></code> copy support helpers distinguish between whether
+the <code class="docutils literal notranslate"><span class="pre">__block</span></code> variable is a <code class="docutils literal notranslate"><span class="pre">Block</span></code> or not and should either call:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as an object or:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as a <code class="docutils literal notranslate"><span class="pre">Block</span></code>.</p>
+<p>A full example follows:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">__block</span> <span class="n">__weak</span> <span class="n">id</span> <span class="n">obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">obj</span> <span class="n">somemessage</span><span class="p">];</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// uninitialized</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">id</span> <span class="n">captured_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_obj, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>for the block <code class="docutils literal notranslate"><span class="pre">byref</span></code> part and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">byref_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="p">[</span><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">_block</span><span class="o">-></span><span class="n">byref_obj</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">)</span> <span class="n">somemessage</span><span class="p">];</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->byref_obj);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">),</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and within the compound statement:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">truct</span> <span class="n">_block_byref_obj</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">obj</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_obj</span><span class="p">),</span>
+                 <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_obj_keep</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_obj_dispose</span><span class="p">,</span>
+                 <span class="p">.</span><span class="n">captured_obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span> <span class="p">)};</span>
+
+<span class="n">truct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">obj</span><span class="p">,</span>        <span class="c1">// a reference to the on-stack structure containing "captured_obj"</span>
+<span class="p">};</span>
+
+
+<span class="n">functioncall</span><span class="p">(</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="c-support">
+<h2><a class="toc-backref" href="#id18">C++ Support</a><a class="headerlink" href="#c-support" title="Permalink to this headline">¶</a></h2>
+<p>Within a block stack based C++ objects are copied into <code class="docutils literal notranslate"><span class="pre">const</span></code> copies using
+the copy constructor.  It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor.  In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+<code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit.  The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all <code class="docutils literal notranslate"><span class="pre">const</span></code> constructed copies, and similarly
+should call the destructor in the destroy routine.</p>
+<p>As an example, suppose a C++ class <code class="docutils literal notranslate"><span class="pre">FOO</span></code> existed with a copy constructor.
+Within a code block a stack version of a <code class="docutils literal notranslate"><span class="pre">FOO</span></code> object is declared and used
+within a <code class="docutils literal notranslate"><span class="pre">Block</span></code> literal expression:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
+    <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">block</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span> <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The compiler would synthesize:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_literal_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_10</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span><span class="p">),</span> <span class="n">__block_copy_10</span><span class="p">,</span> <span class="n">__block_dispose_10</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and the code would be:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
+  <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+  <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// default constructor</span>
+  <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+    <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">26</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+    <span class="n">__block_invoke_10</span><span class="p">,</span>
+    <span class="o">&</span><span class="n">__block_descriptor_10</span><span class="p">,</span>
+   <span class="p">};</span>
+   <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">foo</span><span class="p">);</span>  <span class="c1">// const copy into stack version</span>
+   <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">&</span><span class="n">block</span> <span class="o">=</span> <span class="o">&</span><span class="n">_block_literal</span><span class="p">;</span>  <span class="c1">// assign literal to block variable</span>
+   <span class="n">block</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">block</span><span class="p">);</span>    <span class="c1">// invoke block</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy stack version of const block copy</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy original version</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>C++ objects stored in <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage start out on the stack in a
+<code class="docutils literal notranslate"><span class="pre">block_byref</span></code> data structure as do other variables.  Such objects (if not
+<code class="docutils literal notranslate"><span class="pre">const</span></code> objects) must support a regular copy constructor.  The <code class="docutils literal notranslate"><span class="pre">block_byref</span></code>
+data structure will have copy and destroy helper routines synthesized by the
+compiler.  The copy helper will have code created to perform the copy
+constructor based on the initial stack <code class="docutils literal notranslate"><span class="pre">block_byref</span></code> data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit.  The destroy helper
+will have code to do the destructor on the object stored within the supplied
+<code class="docutils literal notranslate"><span class="pre">block_byref</span></code> heap data structure.  For example,</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__block</span> <span class="n">FOO</span> <span class="n">blockStorageFoo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>requires the normal constructor for the embedded <code class="docutils literal notranslate"><span class="pre">blockStorageFoo</span></code> object:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and at scope termination the destructor:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note that the forwarding indirection is <em>NOT</em> used.</p>
+<p>The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>for the appropriately named constructor and destructor for the class/struct
+<code class="docutils literal notranslate"><span class="pre">FOO</span></code>.</p>
+<p>To support member variable and function access the compiler will synthesize a
+<code class="docutils literal notranslate"><span class="pre">const</span></code> pointer to a block version of the <code class="docutils literal notranslate"><span class="pre">this</span></code> pointer.</p>
+</div>
+<div class="section" id="runtime-helper-functions">
+<span id="runtimehelperfunctions"></span><h2><a class="toc-backref" href="#id19">Runtime Helper Functions</a><a class="headerlink" href="#runtime-helper-functions" title="Permalink to this headline">¶</a></h2>
+<p>The runtime helper functions are described in
+<code class="docutils literal notranslate"><span class="pre">/usr/local/include/Block_private.h</span></code>.  To summarize their use, a <code class="docutils literal notranslate"><span class="pre">Block</span></code>
+requires copy/dispose helpers if it imports any block variables, <code class="docutils literal notranslate"><span class="pre">__block</span></code>
+storage variables, <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> variables, or C++ <code class="docutils literal notranslate"><span class="pre">const</span></code>
+copied objects with constructor/destructors.  The (1<<26) bit is set and
+functions are generated.</p>
+<p>The block copy helper function should, for each of the variables of the type
+mentioned above, call:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">apropos</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the copy helper and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">apropos</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the dispose helper where <code class="docutils literal notranslate"><span class="pre"><apropos></span></code> is:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="p">{</span>
+    <span class="n">BLOCK_FIELD_IS_OBJECT</span>   <span class="o">=</span>  <span class="mi">3</span><span class="p">,</span>  <span class="c1">// id, NSObject, __attribute__((NSObject)), block, ...</span>
+    <span class="n">BLOCK_FIELD_IS_BLOCK</span>    <span class="o">=</span>  <span class="mi">7</span><span class="p">,</span>  <span class="c1">// a block variable</span>
+    <span class="n">BLOCK_FIELD_IS_BYREF</span>    <span class="o">=</span>  <span class="mi">8</span><span class="p">,</span>  <span class="c1">// the on stack structure holding the __block variable</span>
+
+    <span class="n">BLOCK_FIELD_IS_WEAK</span>     <span class="o">=</span> <span class="mi">16</span><span class="p">,</span>  <span class="c1">// declared __weak</span>
+
+    <span class="n">BLOCK_BYREF_CALLER</span>      <span class="o">=</span> <span class="mi">128</span><span class="p">,</span> <span class="c1">// called from byref copy/dispose helpers</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and of course the constructors/destructors for <code class="docutils literal notranslate"><span class="pre">const</span></code> copied C++ objects.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">block_byref</span></code> data structure similarly requires copy/dispose helpers for
+block variables, <code class="docutils literal notranslate"><span class="pre">__attribute__((NSObject))</span></code> variables, or C++ <code class="docutils literal notranslate"><span class="pre">const</span></code>
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.</p>
+<p>Under ObjC we allow <code class="docutils literal notranslate"><span class="pre">__weak</span></code> as an attribute on <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables, and
+this causes the addition of <code class="docutils literal notranslate"><span class="pre">BLOCK_FIELD_IS_WEAK</span></code> orred onto the
+<code class="docutils literal notranslate"><span class="pre">BLOCK_FIELD_IS_BYREF</span></code> flag when copying the <code class="docutils literal notranslate"><span class="pre">block_byref</span></code> structure in the
+<code class="docutils literal notranslate"><span class="pre">Block</span></code> copy helper, and onto the <code class="docutils literal notranslate"><span class="pre">BLOCK_FIELD_<apropos></span></code> field within the
+<code class="docutils literal notranslate"><span class="pre">block_byref</span></code> copy/dispose helper calls.</p>
+<p>The prototypes, and summary, of the helper functions are:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Certain field types require runtime assistance when being copied to the</span>
+<span class="cm">   heap.  The following function is used to copy fields of types: blocks,</span>
+<span class="cm">   pointers to byref structures, and objects (including</span>
+<span class="cm">   __attribute__((NSObject)) pointers.  BLOCK_FIELD_IS_WEAK is orthogonal to</span>
+<span class="cm">   the other choices which are mutually exclusive.  Only in a Block copy</span>
+<span class="cm">   helper will one see BLOCK_FIELD_IS_BYREF.</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_assign</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">destAddr</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+
+<span class="cm">/* Similarly a compiler generated dispose helper needs to call back for each</span>
+<span class="cm">   field of the byref data structure.  (Currently the implementation only</span>
+<span class="cm">   packs one field into the byref structure but in principle there could be</span>
+<span class="cm">   more).  The same flags used in the copy helper should be used for each</span>
+<span class="cm">   call generated to this function:</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_dispose</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="copyright">
+<h2><a class="toc-backref" href="#id20">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2>
+<p>Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:</p>
+<p>The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.</p>
+<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+      
+        <p>
+        «  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer" role="contentinfo">
+        © Copyright 2007-2019, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/9.0.0/tools/clang/docs/BlockLanguageSpec.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/BlockLanguageSpec.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/BlockLanguageSpec.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/BlockLanguageSpec.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,361 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Language Specification for Blocks — Clang 9 documentation</title>
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
+    <link rel="prev" title="Objective-C Literals" href="ObjectiveCLiterals.html" /> 
+  </head><body>
+      <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+          <span>Clang 9 documentation</span></a></h1>
+        <h2 class="heading"><span>Language Specification for Blocks</span></h2>
+      </div>
+      <div class="topnav" role="navigation" aria-label="top navigation">
+      
+        <p>
+        «  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="language-specification-for-blocks">
+<h1>Language Specification for Blocks<a class="headerlink" href="#language-specification-for-blocks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#revisions" id="id1">Revisions</a></li>
+<li><a class="reference internal" href="#overview" id="id2">Overview</a></li>
+<li><a class="reference internal" href="#the-block-type" id="id3">The Block Type</a></li>
+<li><a class="reference internal" href="#block-variable-declarations" id="id4">Block Variable Declarations</a></li>
+<li><a class="reference internal" href="#block-literal-expressions" id="id5">Block Literal Expressions</a></li>
+<li><a class="reference internal" href="#the-invoke-operator" id="id6">The Invoke Operator</a></li>
+<li><a class="reference internal" href="#the-copy-and-release-operations" id="id7">The Copy and Release Operations</a></li>
+<li><a class="reference internal" href="#the-block-storage-qualifier" id="id8">The <code class="docutils literal notranslate"><span class="pre">__block</span></code> Storage Qualifier</a></li>
+<li><a class="reference internal" href="#control-flow" id="id9">Control Flow</a></li>
+<li><a class="reference internal" href="#objective-c-extensions" id="id10">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#c-extensions" id="id11">C++ Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="revisions">
+<h2><a class="toc-backref" href="#id1">Revisions</a><a class="headerlink" href="#revisions" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/2/25 — created</li>
+<li>2008/7/28 — revised, <code class="docutils literal notranslate"><span class="pre">__block</span></code> syntax</li>
+<li>2008/8/13 — revised, Block globals</li>
+<li>2008/8/21 — revised, C++ elaboration</li>
+<li>2008/11/1 — revised, <code class="docutils literal notranslate"><span class="pre">__weak</span></code> support</li>
+<li>2009/1/12 — revised, explicit return types</li>
+<li>2009/2/10 — revised, <code class="docutils literal notranslate"><span class="pre">__block</span></code> objects need retain</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++</p>
+</div>
+<div class="section" id="the-block-type">
+<h2><a class="toc-backref" href="#id3">The Block Type</a><a class="headerlink" href="#the-block-type" title="Permalink to this headline">¶</a></h2>
+<p>Like function types, the <span class="block-term">Block type</span> is a pair consisting
+of a result value type and a list of parameter types very similar to a
+function type. Blocks are intended to be used much like functions with
+the key distinction being that in addition to executable code they
+also contain various variable bindings to automatic (stack) or managed
+(heap) memory.</p>
+<p>The abstract declarator,</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">char</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>describes a reference to a Block that, when invoked, takes two
+parameters, the first of type char and the second of type float, and
+returns a value of type int.  The Block referenced is of opaque data
+that may reside in automatic (stack) memory, global memory, or heap
+memory.</p>
+</div>
+<div class="section" id="block-variable-declarations">
+<h2><a class="toc-backref" href="#id4">Block Variable Declarations</a><a class="headerlink" href="#block-variable-declarations" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">variable with Block type</span> is declared using function
+pointer style notation substituting <code class="docutils literal notranslate"><span class="pre">^</span></code> for <code class="docutils literal notranslate"><span class="pre">*</span></code>. The following are
+valid Block variable declarations:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningVoidWithVoidArgument</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningIntWithIntAndCharArguments</span><span class="p">)(</span><span class="kt">int</span><span class="p">,</span> <span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">arrayOfTenBlocksReturningVoidWithIntArgument</span><span class="p">[</span><span class="mi">10</span><span class="p">])(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Variadic <code class="docutils literal notranslate"><span class="pre">...</span></code> arguments are supported. [variadic.c] A Block that
+takes no arguments must specify void in the argument list [voidarg.c].
+An empty parameter list does not represent, as K&R provide, an
+unspecified argument list.  Note: both gcc and clang support K&R style
+as a convenience.</p>
+<p>A Block reference may be cast to a pointer of arbitrary type and vice
+versa. [cast.c] A Block reference may not be dereferenced via the
+pointer dereference operator <code class="docutils literal notranslate"><span class="pre">*</span></code>, and thus a Block’s size may not be
+computed at compile time. [sizeof.c]</p>
+</div>
+<div class="section" id="block-literal-expressions">
+<h2><a class="toc-backref" href="#id5">Block Literal Expressions</a><a class="headerlink" href="#block-literal-expressions" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">Block literal expression</span> produces a reference to a
+Block. It is introduced by the use of the <code class="docutils literal notranslate"><span class="pre">^</span></code> token as a unary
+operator.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Block_literal_expression</span> <span class="o">::=</span>   <span class="o">^</span> <span class="n">block_decl</span> <span class="n">compound_statement_body</span>
+<span class="n">block_decl</span> <span class="o">::=</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">parameter_list</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">type_expression</span>
+</pre></div>
+</div>
+<p>where type expression is extended to allow <code class="docutils literal notranslate"><span class="pre">^</span></code> as a Block reference
+(pointer) where <code class="docutils literal notranslate"><span class="pre">*</span></code> is allowed as a function reference (pointer).</p>
+<p>The following Block literal:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span> <span class="kt">void</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>produces a reference to a Block with no arguments with no return value.</p>
+<p>The return type is optional and is inferred from the return
+statements. If the return statements return a value, they all must
+return a value of the same type. If there is no value returned the
+inferred type of the Block is void; otherwise it is the type of the
+return statement value.</p>
+<p>If the return type is omitted and the argument list is <code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></code>,
+the <code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></code> argument list may also be omitted.</p>
+<p>So:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span> <span class="p">(</span> <span class="kt">void</span> <span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are exactly equivalent constructs for the same expression.</p>
+<p>The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.</p>
+<p>Given:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">pointerToFunctionThatReturnsIntWithCharArg</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="n">functionPointer</span><span class="p">;</span>
+<span class="o">^</span> <span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span> <span class="kt">int</span> <span class="p">((</span><span class="o">*</span><span class="p">)(</span><span class="kt">float</span> <span class="n">x</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are equivalent expressions, as is:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">^</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>[returnfunctionptr.c]</p>
+<p>The compound statement body establishes a new lexical scope within
+that of its parent. Variables used within the scope of the compound
+statement are bound to the Block in the normal manner with the
+exception of those in automatic (stack) storage. Thus one may access
+functions and global variables as one would expect, as well as static
+local variables. [testme]</p>
+<p>Local automatic (stack) variables referenced within the compound
+statement of a Block are imported and captured by the Block as const
+copies. The capture (binding) is performed at the time of the Block
+literal expression evaluation.</p>
+<p>The compiler is not required to capture a variable if it can prove
+that no references to the variable will actually be evaluated.
+Programmers can force a variable to be captured by referencing it in a
+statement at the beginning of the Block, like so:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.</p>
+<p>The lifetime of variables declared in a Block is that of a function;
+each activation frame contains a new copy of variables declared within
+the local scope of the Block. Such variable declarations should be
+allowed anywhere [testme] rather than only when C99 parsing is
+requested, including for statements. [testme]</p>
+<p>Block literal expressions may occur within Block literal expressions
+(nest) and all variables captured by any nested blocks are implicitly
+also captured in the scopes of their enclosing Blocks.</p>
+<p>A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.</p>
+</div>
+<div class="section" id="the-invoke-operator">
+<h2><a class="toc-backref" href="#id6">The Invoke Operator</a><a class="headerlink" href="#the-invoke-operator" title="Permalink to this headline">¶</a></h2>
+<p>Blocks are <span class="block-term">invoked</span> using function call syntax with a
+list of expression parameters of types corresponding to the
+declaration and returning a result type also according to the
+declaration. Given:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">x</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">z</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>the following are all legal Block invocations:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="p">(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="nb">true</span> <span class="o">?</span> <span class="nl">x</span> <span class="p">:</span> <span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-copy-and-release-operations">
+<h2><a class="toc-backref" href="#id7">The Copy and Release Operations</a><a class="headerlink" href="#the-copy-and-release-operations" title="Permalink to this headline">¶</a></h2>
+<p>The compiler and runtime provide <span class="block-term">copy</span> and
+<span class="block-term">release</span> operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.</p>
+<p>The copy operation <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, <code class="docutils literal notranslate"><span class="pre">Block_release()</span></code>, is styled as a
+function that takes an arbitrary Block reference and, if dynamically
+matched to a Block copy operation, allows recovery of the referenced
+allocated memory.</p>
+</div>
+<div class="section" id="the-block-storage-qualifier">
+<h2><a class="toc-backref" href="#id8">The <code class="docutils literal notranslate"><span class="pre">__block</span></code> Storage Qualifier</a><a class="headerlink" href="#the-block-storage-qualifier" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the new Block type we also introduce a new storage
+qualifier, <span class="block-term">__block</span>, for local variables. [testme: a
+__block declaration within a block literal] The <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+<code class="docutils literal notranslate"><span class="pre">__block</span></code> act as if they were in allocated storage and this storage
+is automatically recovered after last use of said variable.  An
+implementation may choose an optimization where the storage is
+initially automatic and only “moved” to allocated (heap) storage upon
+a Block_copy of a referencing Block.  Such variables may be mutated as
+normal variables are.</p>
+<p>In the case where a <code class="docutils literal notranslate"><span class="pre">__block</span></code> variable is a Block one must assume
+that the <code class="docutils literal notranslate"><span class="pre">__block</span></code> variable resides in allocated storage and as such
+is assumed to reference a Block that is also in allocated storage
+(that it is the result of a <code class="docutils literal notranslate"><span class="pre">Block_copy</span></code> operation).  Despite this
+there is no provision to do a <code class="docutils literal notranslate"><span class="pre">Block_copy</span></code> or a <code class="docutils literal notranslate"><span class="pre">Block_release</span></code> if
+an implementation provides initial automatic storage for Blocks.  This
+is due to the inherent race condition of potentially several threads
+trying to update the shared variable and the need for synchronization
+around disposing of older values and copying new ones.  Such
+synchronization is beyond the scope of this language specification.</p>
+</div>
+<div class="section" id="control-flow">
+<h2><a class="toc-backref" href="#id9">Control Flow</a><a class="headerlink" href="#control-flow" title="Permalink to this headline">¶</a></h2>
+<p>The compound statement of a Block is treated much like a function body
+with respect to control flow in that goto, break, and continue do not
+escape the Block.  Exceptions are treated <em>normally</em> in that when
+thrown they pop stack frames until a catch clause is found.</p>
+</div>
+<div class="section" id="objective-c-extensions">
+<h2><a class="toc-backref" href="#id10">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Objective-C extends the definition of a Block reference type to be
+that also of id.  A variable or expression of Block type may be
+messaged or used as a parameter wherever an id may be. The converse is
+also true. Block references may thus appear as properties and are
+subject to the assign, retain, and copy attribute logic that is
+reserved for objects.</p>
+<p>All Blocks are constructed to be Objective-C objects regardless of
+whether the Objective-C runtime is operational in the program or
+not. Blocks using automatic (stack) memory are objects and may be
+messaged, although they may not be assigned into <code class="docutils literal notranslate"><span class="pre">__weak</span></code> locations
+if garbage collection is enabled.</p>
+<p>Within a Block literal expression within a method definition
+references to instance variables are also imported into the lexical
+scope of the compound statement. These variables are implicitly
+qualified as references from self, and so self is imported as a const
+copy. The net effect is that instance variables can be mutated.</p>
+<p>The <span class="block-term">Block_copy</span> operator retains all objects held in
+variables of automatic storage referenced within the Block expression
+(or form strong references if running under garbage collection).
+Object variables of <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage type are assumed to hold
+normal pointers with no provision for retain and release messages.</p>
+<p>Foundation defines (and supplies) <code class="docutils literal notranslate"><span class="pre">-copy</span></code> and <code class="docutils literal notranslate"><span class="pre">-release</span></code> methods for
+Blocks.</p>
+<p>In the Objective-C and Objective-C++ languages, we allow the
+<code class="docutils literal notranslate"><span class="pre">__weak</span></code> specifier for <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables of object type.  If
+garbage collection is not enabled, this qualifier causes these
+variables to be kept without retain messages being sent. This
+knowingly leads to dangling pointers if the Block (or a copy) outlives
+the lifetime of this object.</p>
+<p>In garbage collected environments, the <code class="docutils literal notranslate"><span class="pre">__weak</span></code> variable is set to
+nil when the object it references is collected, as long as the
+<code class="docutils literal notranslate"><span class="pre">__block</span></code> variable resides in the heap (either by default or via
+<code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code>).  The initial Apple implementation does in fact
+start <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables on the stack and migrate them to the heap
+only as a result of a <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> operation.</p>
+<p>It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked <code class="docutils literal notranslate"><span class="pre">__weak</span></code>, including
+<code class="docutils literal notranslate"><span class="pre">__weak</span></code> <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables.</p>
+</div>
+<div class="section" id="c-extensions">
+<h2><a class="toc-backref" href="#id11">C++ Extensions</a><a class="headerlink" href="#c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.</p>
+<p>As usual, within the block, references to captured variables become
+const-qualified, as if they were references to members of a const
+object.  Note that this does not change the type of a variable of
+reference type.</p>
+<p>For example, given a class Foo:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Foo</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">fooRef</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="n">fooPtr</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>A Block that referenced these variables would import the variables as
+const variations:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="n">Foo</span> <span class="n">block_foo</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">block_fooRef</span> <span class="o">=</span> <span class="n">fooRef</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="k">const</span> <span class="n">block_fooPtr</span> <span class="o">=</span> <span class="n">fooPtr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression.  They are also copied when
+calling <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> on a Block allocated on the stack.  In both
+cases, they are copied as if the variable were const-qualified, and
+it’s an error if there’s no such constructor.</p>
+<p>Captured variables in Blocks on the stack are destroyed when control
+leaves the compound statement that contains the Block literal
+expression.  Captured variables in Blocks on the heap are destroyed
+when the reference count of the Block drops to zero.</p>
+<p>Variables declared as residing in <code class="docutils literal notranslate"><span class="pre">__block</span></code> storage may be initially
+allocated in the heap or may first appear on the stack and be copied
+to the heap as a result of a <code class="docutils literal notranslate"><span class="pre">Block_copy()</span></code> operation. When copied
+from the stack, <code class="docutils literal notranslate"><span class="pre">__block</span></code> variables are copied using their normal
+qualification (i.e. without adding const).  In C++11, <code class="docutils literal notranslate"><span class="pre">__block</span></code>
+variables are copied as x-values if that is possible, then as l-values
+if not; if both fail, it’s an error.  The destructor for any initial
+stack-based version is called at the variable’s normal end of scope.</p>
+<p>References to <code class="docutils literal notranslate"><span class="pre">this</span></code>, as well as references to non-static members of
+any enclosing class, are evaluated by capturing <code class="docutils literal notranslate"><span class="pre">this</span></code> just like a
+normal variable of C pointer type.</p>
+<p>Member variables that are Blocks may not be overloaded by the types of
+their arguments.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+      
+        <p>
+        «  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer" role="contentinfo">
+        © Copyright 2007-2019, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/9.0.0/tools/clang/docs/ClangCheck.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/ClangCheck.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/ClangCheck.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/ClangCheck.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,93 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>ClangCheck — Clang 9 documentation</title>
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="ClangFormat" href="ClangFormat.html" />
+    <link rel="prev" title="Overview" href="ClangTools.html" /> 
+  </head><body>
+      <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+          <span>Clang 9 documentation</span></a></h1>
+        <h2 class="heading"><span>ClangCheck</span></h2>
+      </div>
+      <div class="topnav" role="navigation" aria-label="top navigation">
+      
+        <p>
+        «  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clangcheck">
+<h1>ClangCheck<a class="headerlink" href="#clangcheck" title="Permalink to this headline">¶</a></h1>
+<p><cite>ClangCheck</cite> is a small wrapper around <a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling</span></a> which can be used to
+do basic error checking and AST dumping.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> cat <span class="s"><<EOF > snippet.cc</span>
+<span class="gp">></span><span class="s"> void f() {</span>
+<span class="gp">></span><span class="s">   int a = 0</span>
+<span class="gp">></span><span class="s"> }</span>
+<span class="gp">></span><span class="s"> EOF</span>
+<span class="gp">$</span> ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+<span class="go">Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.</span>
+<span class="go">/Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of</span>
+<span class="go">      declaration</span>
+<span class="go">  int a = 0</span>
+<span class="go">           ^</span>
+<span class="go">           ;</span>
+<span class="go">(TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>></span>
+<span class="go">  (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')</span>
+<span class="go">  (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'</span>
+<span class="go">    (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1></span>
+<span class="go">      (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1></span>
+<span class="go">        (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'</span>
+<span class="go">          (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))</span>
+<span class="go">1 error generated.</span>
+<span class="go">Error while processing snippet.cc.</span>
+</pre></div>
+</div>
+<p>The ‘–’ at the end is important as it prevents <strong class="program">clang-check</strong> from
+searching for a compilation database. For more information on how to setup and
+use <strong class="program">clang-check</strong> in a project, see <a class="reference internal" href="HowToSetupToolingForLLVM.html"><span class="doc">How To Setup Clang Tooling For LLVM</span></a>.</p>
+</div>
+
+
+      </div>
+      <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+      
+        <p>
+        «  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer" role="contentinfo">
+        © Copyright 2007-2019, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+    </div>
+  </body>
+</html>
\ No newline at end of file

More information about the llvm-commits mailing list