Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / a8e0cd8cdecc7e0ba1792e46773b884c6eed4829 / . / docs / LanguageExtensions.html
blob: 804080d32668917971e9668560463953add9bde2 [file] [log] [blame]
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]4<html>
5<head>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>Clang LanguageExtensions</title>
Sean Hunt64f857b2011-06-23 01:22:53 +0000[diff] [blame]8 <link type="text/css" rel="stylesheet" href="../menu.css">
9 <link type="text/css" rel="stylesheet" href="../content.css">
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]10 <style type="text/css">
11 td {
12 vertical-align: top;
13 }
14 </style>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]15</head>
16<body>
17
18<!--#include virtual="../menu.html.incl"-->
19
20<div id="content">
21
22<h1>Clang Language Extensions</h1>
23
24<ul>
25<li><a href="#intro">Introduction</a></li>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]26<li><a href="#feature_check">Feature Checking Macros</a></li>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]27<li><a href="#has_include">Include File Checking Macros</a></li>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]28<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]29<li><a href="#vectors">Vectors and Extended Vectors</a></li>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]30<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
31<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]32<li><a href="#checking_language_features">Checks for Standard Language Features</a>
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]33 <ul>
34 <li><a href="#cxx_exceptions">C++ exceptions</a></li>
35 <li><a href="#cxx_rtti">C++ RTTI</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]36 </ul></li>
37<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]38 <ul>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]39 <li><a href="#cxx0x">C++0x</a>
40 <ul>
41 <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li>
42 <li><a href="#cxx_access_control_sfinae">C++0x SFINAE includes access control</a></li>
43 <li><a href="#cxx_alias_templates">C++0x alias templates</a></li>
44 <li><a href="#cxx_attributes">C++0x attributes</a></li>
45 <li><a href="#cxx_default_function_template_args">C++0x default template arguments in function templates</a></li>
Sean Huntd9624992011-06-23 06:11:37 +0000[diff] [blame]46 <li><a href="#cxx_delegating_constructor">C++0x delegating constructors</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]47 <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li>
48 <li><a href="#cxx_lambdas">C++0x lambdas</a></li>
49 <li><a href="#cxx_nullptr">C++0x nullptr</a></li>
50 <li><a href="#cxx_override_control">C++0x override control</a></li>
51 <li><a href="#cxx_range_for">C++0x range-based for loop</a></li>
52 <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li>
53 <li><a href="#cxx_reference_qualified_functions">C++0x reference-qualified functions</a></li>
54 <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li>
55 <li><a href="#cxx_auto_type">C++0x type inference</a></li>
56 <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li>
57 <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li>
58 <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li>
59 <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li>
60 <li><a href="#cxx_noexcept">C++0x noexcept specification</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]61 </ul></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]62 <li><a href="#c1x">C1X</a>
63 <ul>
64 <li><a href="#c_generic_selections">C1X generic selections</a></li>
65 <li><a href="#c_static_assert">C1X <tt>_Static_assert()</tt></a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]66 </ul></li>
67 </ul> </li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]68<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]69<li><a href="#blocks">Blocks</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]70<li><a href="#objc_features">Objective-C Features</a>
71 <ul>
72 <li><a href="#objc_instancetype">Related result types</a></li>
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]73 <li><a href="#objc_arc">Automatic reference counting</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]74 </ul>
75</li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]76<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]77<li><a href="#builtins">Builtin Functions</a>
78 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]79 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]80 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]81 <li><a href="#__sync_swap">__sync_swap</a></li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]82 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]83</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]84<li><a href="#targetspecific">Target-Specific Extensions</a>
85 <ul>
86 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
87 </ul>
88</li>
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]89<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]90<li><a href="#threadsafety">Thread Safety Annotation Checking</a></li>
91 <ul>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]92 <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>
93 <li><a href="#ts_lockable"><tt>lockable</tt></a></li>
94 <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]95 <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li>
96 <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]97 <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li>
98 <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li>
99 <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li>
100 <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li>
101 <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li>
102 <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li>
103 <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li>
104 <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li>
105 <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li>
106 <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li>
107 <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li>
108 <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li>
109 <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]110 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]111</ul>
112
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]113<!-- ======================================================================= -->
114<h2 id="intro">Introduction</h2>
115<!-- ======================================================================= -->
116
117<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]118addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]119range of GCC extensions. Please see the <a
120href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
121more information on these extensions.</p>
122
123<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]124<h2 id="feature_check">Feature Checking Macros</h2>
125<!-- ======================================================================= -->
126
127<p>Language extensions can be very useful, but only if you know you can depend
Chris Lattnerc70e1932011-03-21 16:25:11 +0000[diff] [blame]128on them. In order to allow fine-grain features checks, we support three builtin
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]129function-like macros. This allows you to directly test for a feature in your
130code without having to resort to something like autoconf or fragile "compiler
131version checks".</p>
132
133<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]134<h3><a name="__has_builtin">__has_builtin</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]135<!-- ======================================================================= -->
136
137<p>This function-like macro takes a single identifier argument that is the name
138of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
139not. It can be used like this:</p>
140
141<blockquote>
142<pre>
143#ifndef __has_builtin // Optional of course.
144 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
145#endif
146
147...
148#if __has_builtin(__builtin_trap)
149 __builtin_trap();
150#else
151 abort();
152#endif
153...
154</pre>
155</blockquote>
156
157
158<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]159<h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]160<!-- ======================================================================= -->
161
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]162<p>These function-like macros take a single identifier argument that is the
163name of a feature. <code>__has_feature</code> evaluates to 1 if the feature
164is both supported by Clang and standardized in the current language standard
165or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
166<code>__has_extension</code> evaluates to 1 if the feature is supported by
167Clang in the current language (either as a language extension or a standard
168language feature) or 0 if not. They can be used like this:</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]169
170<blockquote>
171<pre>
172#ifndef __has_feature // Optional of course.
173 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
174#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]175#ifndef __has_extension
176 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
177#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]178
179...
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]180#if __has_feature(cxx_rvalue_references)
181// This code will only be compiled with the -std=c++0x and -std=gnu++0x
182// options, because rvalue references are only standardized in C++0x.
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]183#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]184
185#if __has_extension(cxx_rvalue_references)
186// This code will be compiled with the -std=c++0x, -std=gnu++0x, -std=c++98
187// and -std=gnu++98 options, because rvalue references are supported as a
188// language extension in C++98.
189#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]190</pre>
191</blockquote>
192
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]193<p id="has_feature_back_compat">For backwards compatibility reasons,
194<code>__has_feature</code> can also be used to test for support for
195non-standardized features, i.e. features not prefixed <code>c_</code>,
196<code>cxx_</code> or <code>objc_</code>.</p>
197
198<p>If the <code>-pedantic-errors</code> option is given,
199<code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
200
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]201<p>The feature tag is described along with the language feature below.</p>
202
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]203<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]204<h3><a name="__has_attribute">__has_attribute</a></h3>
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]205<!-- ======================================================================= -->
206
207<p>This function-like macro takes a single identifier argument that is the name
208of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
209can be used like this:</p>
210
211<blockquote>
212<pre>
213#ifndef __has_attribute // Optional of course.
214 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
215#endif
216
217...
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]218#if __has_attribute(always_inline)
219#define ALWAYS_INLINE __attribute__((always_inline))
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]220#else
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]221#define ALWAYS_INLINE
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]222#endif
223...
224</pre>
225</blockquote>
226
227<!-- ======================================================================= -->
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]228<h2 id="has_include">Include File Checking Macros</h2>
229<!-- ======================================================================= -->
230
231<p>Not all developments systems have the same include files.
232The <a href="#__has_include">__has_include</a> and
233<a href="#__has_include_next">__has_include_next</a> macros allow you to
234check for the existence of an include file before doing
235a possibly failing #include directive.</p>
236
237<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]238<h3><a name="__has_include">__has_include</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]239<!-- ======================================================================= -->
240
241<p>This function-like macro takes a single file name string argument that
242is the name of an include file. It evaluates to 1 if the file can
243be found using the include paths, or 0 otherwise:</p>
244
245<blockquote>
246<pre>
247// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]248#if __has_include("myinclude.h") &amp;&amp; __has_include(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]249# include "myinclude.h"
250#endif
251
252// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]253#if defined(__has_include) &amp;&amp; __has_include("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]254# include "myinclude.h"
255#endif
256</pre>
257</blockquote>
258
259<p>To test for this feature, use #if defined(__has_include).</p>
260
261<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]262<h3><a name="__has_include_next">__has_include_next</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]263<!-- ======================================================================= -->
264
265<p>This function-like macro takes a single file name string argument that
266is the name of an include file. It is like __has_include except that it
267looks for the second instance of the given file found in the include
268paths. It evaluates to 1 if the second instance of the file can
269be found using the include paths, or 0 otherwise:</p>
270
271<blockquote>
272<pre>
273// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]274#if __has_include_next("myinclude.h") &amp;&amp; __has_include_next(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]275# include_next "myinclude.h"
276#endif
277
278// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]279#if defined(__has_include_next) &amp;&amp; __has_include_next("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]280# include_next "myinclude.h"
281#endif
282</pre>
283</blockquote>
284
285<p>Note that __has_include_next, like the GNU extension
286#include_next directive, is intended for use in headers only,
287and will issue a warning if used in the top-level compilation
288file. A warning will also be issued if an absolute path
289is used in the file argument.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]290
291<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]292<h2 id="builtinmacros">Builtin Macros</h2>
293<!-- ======================================================================= -->
294
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]295<dl>
296 <dt><code>__BASE_FILE__</code></dt>
297 <dd>Defined to a string that contains the name of the main input
298 file passed to Clang.</dd>
299
300 <dt><code>__COUNTER__</code></dt>
301 <dd>Defined to an integer value that starts at zero and is
302 incremented each time the <code>__COUNTER__</code> macro is
303 expanded.</dd>
304
305 <dt><code>__INCLUDE_LEVEL__</code></dt>
306 <dd>Defined to an integral value that is the include depth of the
307 file currently being translated. For the main file, this value is
308 zero.</dd>
309
310 <dt><code>__TIMESTAMP__</code></dt>
311 <dd>Defined to the date and time of the last modification of the
312 current source file.</dd>
313
314 <dt><code>__clang__</code></dt>
315 <dd>Defined when compiling with Clang</dd>
316
317 <dt><code>__clang_major__</code></dt>
318 <dd>Defined to the major version number of Clang (e.g., the 2 in
319 2.0.1).</dd>
320
321 <dt><code>__clang_minor__</code></dt>
322 <dd>Defined to the minor version number of Clang (e.g., the 0 in
323 2.0.1).</dd>
324
325 <dt><code>__clang_patchlevel__</code></dt>
326 <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd>
327
328 <dt><code>__clang_version__</code></dt>
329 <dd>Defined to a string that captures the Clang version, including
330 the Subversion tag or revision number, e.g., "1.5 (trunk
331 102332)".</dd>
332</dl>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]333
334<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]335<h2 id="vectors">Vectors and Extended Vectors</h2>
336<!-- ======================================================================= -->
337
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]338<p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
339
340<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
341syntax and other tidbits as seen in OpenCL. An example is:</p>
342
343<blockquote>
344<pre>
345typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
346typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
347
348float4 foo(float2 a, float2 b) {
349 float4 c;
350 c.xz = a;
351 c.yw = b;
352 return c;
353}
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]354</pre>
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]355</blockquote>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]356
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]357<p>Query for this feature with __has_extension(attribute_ext_vector_type).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]358
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]359<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
360
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]361<!-- ======================================================================= -->
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]362<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]363<!-- ======================================================================= -->
364
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]365<p>An optional string message can be added to the <tt>deprecated</tt>
366and <tt>unavailable</tt> attributes. For example:</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]367
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]368<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]369<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]370</blockquote>
371
372<p>If the deprecated or unavailable declaration is used, the message
373will be incorporated into the appropriate diagnostic:</p>
374
375<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]376<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]377 explode();
378 ^</pre>
379</blockquote>
380
381<p>Query for this feature
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]382with <tt>__has_extension(attribute_deprecated_with_message)</tt>
383and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]384
385<!-- ======================================================================= -->
386<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
387<!-- ======================================================================= -->
388
389<p>Clang allows attributes to be written on individual enumerators.
390This allows enumerators to be deprecated, made unavailable, etc. The
391attribute must appear after the enumerator name and before any
392initializer, like so:</p>
393
394<blockquote>
395<pre>enum OperationMode {
396 OM_Invalid,
397 OM_Normal,
398 OM_Terrified __attribute__((deprecated)),
399 OM_AbortOnError __attribute__((deprecated)) = 4
400};</pre>
401</blockquote>
402
403<p>Attributes on the <tt>enum</tt> declaration do not apply to
404individual enumerators.</p>
405
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]406<p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]407
408<!-- ======================================================================= -->
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]409<h2 id="checking_language_features">Checks for Standard Language Features</h2>
410<!-- ======================================================================= -->
411
412<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
413enabled. Those features are listed here.</p>
414
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]415<h3 id="cxx_exceptions">C++ exceptions</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]416
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]417<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
Sean Hunt647ba1b2011-06-23 00:42:53 +0000[diff] [blame]418example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]419
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]420<h3 id="cxx_rtti">C++ RTTI</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]421
Ted Kremenek0eb95602009-12-03 02:06:43 +0000[diff] [blame]422<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]423compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]424
425<!-- ======================================================================= -->
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]426<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
427<!-- ======================================================================= -->
428
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]429<p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used
430to query if certain upcoming standard language features are enabled. Those
431features are listed here. Features that are not yet implemented will be
432noted.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]433
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]434<h3 id="cxx0x">C++0x</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]435
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]436<p>The features listed below are slated for inclusion in the upcoming
437C++0x standard. As a result, all these features are enabled
438with the <tt>-std=c++0x</tt> option when compiling C++ code.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]439
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]440<h4 id="cxx_decltype">C++0x <tt>decltype()</tt></h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]441
442<p>Use <tt>__has_feature(cxx_decltype)</tt> or
443<tt>__has_extension(cxx_decltype)</tt> to determine if support for the
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]444<tt>decltype()</tt> specifier is enabled.</p>
445
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]446<h4 id="cxx_access_control_sfinae">C++0x SFINAE includes access control</h4>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]447
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]448<p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]449
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]450<h4 id="cxx_alias_templates">C++0x alias templates</h4>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]451
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]452<p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
453<tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]454C++0x's alias declarations and alias templates is enabled.</p>
455
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]456<h4 id="cxx_attributes">C++0x attributes</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]457
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]458<p>Use <tt>__has_feature(cxx_attributes)</tt> or
459<tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
460parsing with C++0x's square bracket notation is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]461
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]462<h4 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h4>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]463
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]464<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
465<tt>__has_extension(cxx_default_function_template_args)</tt> to determine
466if support for default template arguments in function templates is enabled.</p>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]467
Sean Huntd9624992011-06-23 06:11:37 +0000[diff] [blame]468<h4 id="cxx_delegating_constructors">C++0x delegating constructors</h4>
469
470<p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if
471support for delegating constructors is enabled.</p>
472
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]473<h4 id="cxx_deleted_functions">C++0x <tt>delete</tt>d functions</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]474
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]475<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
476<tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]477deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]478
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]479<h4 id="cxx_lambdas">C++0x lambdas</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]480
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]481<p>Use <tt>__has_feature(cxx_lambdas)</tt> or
482<tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
483is enabled. clang does not currently implement this feature.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]484
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]485<h4 id="cxx_nullptr">C++0x <tt>nullptr</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]486
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]487<p>Use <tt>__has_feature(cxx_nullptr)</tt> or
488<tt>__has_extension(cxx_nullptr)</tt> to determine if support for
Douglas Gregor84ee2ee2011-05-21 23:15:46 +0000[diff] [blame]489<tt>nullptr</tt> is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]490
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]491<h4 id="cxx_override_control">C++0x <tt>override control</tt></h4>
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]492
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]493<p>Use <tt>__has_feature(cxx_override_control)</tt> or
494<tt>__has_extension(cxx_override_control)</tt> to determine if support for
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]495the override control keywords is enabled.</p>
496
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]497<h4 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]498<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
499<tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
500if support for reference-qualified functions (e.g., member functions with
501<code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>)
502is enabled.</p>
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]503
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]504<h4 id="cxx_range_for">C++0x range-based <tt>for</tt> loop</h4>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]505
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]506<p>Use <tt>__has_feature(cxx_range_for)</tt> or
507<tt>__has_extension(cxx_range_for)</tt> to determine if support for the
508range-based for loop is enabled. </p>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]509
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]510<h4 id="cxx_rvalue_references">C++0x rvalue references</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]511
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]512<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
513<tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]514rvalue references is enabled. </p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]515
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]516<h4 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]517
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]518<p>Use <tt>__has_feature(cxx_static_assert)</tt> or
519<tt>__has_extension(cxx_static_assert)</tt> to determine if support for
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]520compile-time assertions using <tt>static_assert</tt> is enabled.</p>
521
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]522<h4 id="cxx_auto_type">C++0x type inference</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]523
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]524<p>Use <tt>__has_feature(cxx_auto_type)</tt> or
525<tt>__has_extension(cxx_auto_type)</tt> to determine C++0x type inference is
526supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
527will instead be a storage class specifier, as in C or C++98.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]528
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]529<h4 id="cxx_variadic_templates">C++0x variadic templates</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]530
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]531<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
532<tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
Douglas Gregor83d77812011-01-19 23:15:20 +0000[diff] [blame]533for variadic templates is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]534
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]535<h4 id="cxx_inline_namespaces">C++0x inline namespaces</h4>
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]536
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]537<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
538<tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]539inline namespaces is enabled.</p>
540
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]541<h4 id="cxx_trailing_return">C++0x trailing return type</h4>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]542
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]543<p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
544<tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
545alternate function declaration syntax with trailing return type is enabled.</p>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]546
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]547<h4 id="cxx_noexcept">C++0x noexcept</h4>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]548
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]549<p>Use <tt>__has_feature(cxx_noexcept)</tt> or
550<tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
551exception specifications is enabled.</p>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]552
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]553<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</h4>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]554
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]555<p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
556<tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]557strongly typed, scoped enumerations is enabled.</p>
558
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]559<h3 id="c1x">C1X</h3>
560
561<p>The features listed below are slated for inclusion in the upcoming
562C1X standard. As a result, all these features are enabled
563with the <tt>-std=c1x</tt> option when compiling C code.</p>
564
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]565<h4 id="c_generic_selections">C1X generic selections</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]566
567<p>Use <tt>__has_feature(c_generic_selections)</tt> or
568<tt>__has_extension(c_generic_selections)</tt> to determine if support for
569generic selections is enabled.</p>
570
571<p>As an extension, the C1X generic selection expression is available in all
572languages supported by Clang. The syntax is the same as that given in the
573C1X draft standard.</p>
574
575<p>In C, type compatibility is decided according to the rules given in the
576appropriate standard, but in C++, which lacks the type compatibility rules
577used in C, types are considered compatible only if they are equivalent.</p>
578
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]579<h4 id="c_static_assert">C1X <tt>_Static_assert()</tt></h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]580
581<p>Use <tt>__has_feature(c_static_assert)</tt> or
582<tt>__has_extension(c_static_assert)</tt> to determine if support for
583compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
584
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]585<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]586<h2 id="checking_type_traits">Checks for Type Traits</h2>
587<!-- ======================================================================= -->
588
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]589<p>Clang supports the <a href="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_extension(X)</code> indicates the presence of the type trait. For example:
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]590<blockquote>
591<pre>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]592#if __has_extension(is_convertible_to)
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]593template&lt;typename From, typename To&gt;
594struct is_convertible_to {
595 static const bool value = __is_convertible_to(From, To);
596};
597#else
598// Emulate type trait
599#endif
600</pre>
601</blockquote>
602
603<p>The following type traits are supported by Clang:</p>
604<ul>
605 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
606 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
607 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
608 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
609 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
610 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
611 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
612 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
613 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
614 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
615 <li><code>__is_class</code> (GNU, Microsoft)</li>
616 <li><code>__is_convertible_to</code> (Microsoft)</li>
617 <li><code>__is_empty</code> (GNU, Microsoft)</li>
618 <li><code>__is_enum</code> (GNU, Microsoft)</li>
619 <li><code>__is_pod</code> (GNU, Microsoft)</li>
620 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
621 <li><code>__is_union</code> (GNU, Microsoft)</li>
622 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
Sean Hunt1fba8282011-07-18 17:22:33 +0000[diff] [blame]623 <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++0x standard library.</li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]624</ul>
625
626<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]627<h2 id="blocks">Blocks</h2>
628<!-- ======================================================================= -->
629
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]630<p>The syntax and high level language feature description is in <a
631href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
632details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]633href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]634
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]635
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]636<p>Query for this feature with __has_extension(blocks).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]637
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]638<!-- ======================================================================= -->
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]639<h2 id="objc_features">Objective-C Features</h2>
640<!-- ======================================================================= -->
641
642<h3 id="objc_instancetype">Related result types</h3>
643
644<p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p>
645
646<blockquote>
647<pre>
648@interface NSObject
649+ (id)alloc;
650- (id)init;
651@end
652
653@interface NSArray : NSObject
654@end
655</pre>
656</blockquote>
657
658<p>and this common initialization pattern</p>
659
660<blockquote>
661<pre>
662NSArray *array = [[NSArray alloc] init];
663</pre>
664</blockquote>
665
666<p>the type of the expression <code>[NSArray alloc]</code> is
667<code>NSArray*</code> because <code>alloc</code> implicitly has a
668related result type. Similarly, the type of the expression
669<code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
670<code>init</code> has a related result type and its receiver is known
671to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p>
672
673<p>To determine whether a method has a related result type, the first
674word in the camel-case selector (e.g., "init" in "initWithObjects") is
675considered, and the method will a related result type if its return
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]676type is compatible with the type of its class and if</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]677
678<ul>
679
680 <li>the first word is "alloc" or "new", and the method is a class
681 method, or</li>
682
683 <li>the first word is "autorelease", "init", "retain", or "self",
684 and the method is an instance method.</li>
685
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]686</ul>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]687
688<p>If a method with a related result type is overridden by a subclass
689method, the subclass method must also return a type that is compatible
690with the subclass type. For example:</p>
691
692<blockquote>
693<pre>
694@interface NSString : NSObject
695- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
696@end
697</pre>
698</blockquote>
699
700<p>Related result types only affect the type of a message send or
701property access via the given method. In all other respects, a method
702with a related result type is treated the same way as method without a
703related result type.</p>
704
705<!-- ======================================================================= -->
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]706<h2 id="objc_arc">Automatic reference counting </h2>
707<!-- ======================================================================= -->
708
709<p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p>
710
711<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]712<h2 id="overloading-in-c">Function Overloading in C</h2>
713<!-- ======================================================================= -->
714
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]715<p>Clang provides support for C++ function overloading in C. Function
716overloading in C is introduced using the <tt>overloadable</tt> attribute. For
717example, one might provide several overloaded versions of a <tt>tgsin</tt>
718function that invokes the appropriate standard function computing the sine of a
719value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
720precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]721
722<blockquote>
723<pre>
724#include &lt;math.h&gt;
725float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
726double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
727long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
728</pre>
729</blockquote>
730
731<p>Given these declarations, one can call <tt>tgsin</tt> with a
732<tt>float</tt> value to receive a <tt>float</tt> result, with a
733<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
734overloading in C follows the rules of C++ function overloading to pick
735the best overload given the call arguments, with a few C-specific
736semantics:</p>
737<ul>
738 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
739 double</tt> is ranked as a floating-point promotion (per C99) rather
740 than as a floating-point conversion (as in C++).</li>
741
742 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
743 <tt>U*</tt> is considered a pointer conversion (with conversion
744 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
745
746 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
747 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
748 conversion is given "conversion" rank.</li>
749</ul>
750
751<p>The declaration of <tt>overloadable</tt> functions is restricted to
752function declarations and definitions. Most importantly, if any
753function with a given name is given the <tt>overloadable</tt>
754attribute, then all function declarations and definitions with that
755name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]756attribute. This rule even applies to redeclarations of functions whose original
757declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]758
759<blockquote>
760<pre>
761int f(int) __attribute__((overloadable));
762float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
763
764int g(int) __attribute__((overloadable));
765int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
766</pre>
767</blockquote>
768
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]769<p>Functions marked <tt>overloadable</tt> must have
770prototypes. Therefore, the following code is ill-formed:</p>
771
772<blockquote>
773<pre>
774int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
775</pre>
776</blockquote>
777
778<p>However, <tt>overloadable</tt> functions are allowed to use a
779ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p>
780
781<blockquote>
782<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]783void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]784</pre>
785</blockquote>
786
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]787<p>Functions declared with the <tt>overloadable</tt> attribute have
788their names mangled according to the same rules as C++ function
789names. For example, the three <tt>tgsin</tt> functions in our
790motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]791<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]792caveats to this use of name mangling:</p>
793
794<ul>
795
796 <li>Future versions of Clang may change the name mangling of
797 functions overloaded in C, so you should not depend on an specific
798 mangling. To be completely safe, we strongly urge the use of
799 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
800
801 <li>The <tt>overloadable</tt> attribute has almost no meaning when
802 used in C++, because names will already be mangled and functions are
803 already overloadable. However, when an <tt>overloadable</tt>
804 function occurs within an <tt>extern "C"</tt> linkage specification,
805 it's name <i>will</i> be mangled in the same way as it would in
806 C.</li>
807</ul>
808
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]809<p>Query for this feature with __has_extension(attribute_overloadable).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]810
811
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]812<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]813<h2 id="builtins">Builtin Functions</h2>
814<!-- ======================================================================= -->
815
816<p>Clang supports a number of builtin library functions with the same syntax as
817GCC, including things like <tt>__builtin_nan</tt>,
818<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
819<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
820addition to the GCC builtins, Clang supports a number of builtins that GCC does
821not, which are listed here.</p>
822
823<p>Please note that Clang does not and will not support all of the GCC builtins
824for vector operations. Instead of using builtins, you should use the functions
825defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
826define portable wrappers for these. Many of the Clang versions of these
827functions are implemented directly in terms of <a href="#vectors">extended
828vector support</a> instead of builtins, in order to reduce the number of
829builtins that we need to implement.</p>
830
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]831<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]832<h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]833<!-- ======================================================================= -->
834
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]835<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]836permutation/shuffle/swizzle operations. This builtin is also very important for
837the implementation of various target-specific header files like
838<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]839</p>
840
841<p><b>Syntax:</b></p>
842
843<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]844__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]845</pre>
846
847<p><b>Examples:</b></p>
848
849<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]850 // Identity operation - return 4-element vector V1.
851 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
852
853 // "Splat" element 0 of V1 into a 4-element result.
854 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
855
856 // Reverse 4-element vector V1.
857 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
858
859 // Concatenate every other element of 4-element vectors V1 and V2.
860 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
861
862 // Concatenate every other element of 8-element vectors V1 and V2.
863 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]864</pre>
865
866<p><b>Description:</b></p>
867
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]868<p>The first two arguments to __builtin_shufflevector are vectors that have the
869same element type. The remaining arguments are a list of integers that specify
870the elements indices of the first two vectors that should be extracted and
871returned in a new vector. These element indices are numbered sequentially
872starting with the first vector, continuing into the second vector. Thus, if
873vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]874</p>
875
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]876<p>The result of __builtin_shufflevector is a vector
877with the same element type as vec1/vec2 but that has an element count equal to
878the number of indices specified.
879</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]880
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]881<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
882
883<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]884<h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]885<!-- ======================================================================= -->
886
887<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
888the program cannot be reached, even if the compiler might otherwise think it
889can. This is useful to improve optimization and eliminates certain warnings.
890For example, without the <tt>__builtin_unreachable</tt> in the example below,
891the compiler assumes that the inline asm can fall through and prints a "function
892declared 'noreturn' should not return" warning.
893</p>
894
895<p><b>Syntax:</b></p>
896
897<pre>
898__builtin_unreachable()
899</pre>
900
901<p><b>Example of Use:</b></p>
902
903<pre>
904void myabort(void) __attribute__((noreturn));
905void myabort(void) {
906 asm("int3");
907 __builtin_unreachable();
908}
909</pre>
910
911<p><b>Description:</b></p>
912
913<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
914it has undefined behavior, it is a statement that it is never reached and the
915optimizer can take advantage of this to produce better code. This builtin takes
916no arguments and produces a void result.
917</p>
918
919<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
920
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]921<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]922<h3><a name="__sync_swap">__sync_swap</a></h3>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]923<!-- ======================================================================= -->
924
925<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
926memory.
927</p>
928
929<p><b>Syntax:</b></p>
930
931<pre>
932<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
933</pre>
934
935<p><b>Example of Use:</b></p>
936
937<pre>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]938int old_value = __sync_swap(&amp;value, new_value);
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]939</pre>
940
941<p><b>Description:</b></p>
942
943<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
944intrinsics to allow code to atomically swap the current value with the new
945value. More importantly, it helps developers write more efficient and correct
946code by avoiding expensive loops around __sync_bool_compare_and_swap() or
947relying on the platform specific implementation details of
948__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
949</p>
950
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]951
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]952<!-- ======================================================================= -->
953<h2 id="targetspecific">Target-Specific Extensions</h2>
954<!-- ======================================================================= -->
955
956<p>Clang supports some language features conditionally on some targets.</p>
957
958<!-- ======================================================================= -->
959<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
960<!-- ======================================================================= -->
961
962<p>The X86 backend has these language extensions:</p>
963
964<!-- ======================================================================= -->
965<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
966<!-- ======================================================================= -->
967
968<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]969relative to the X86 GS segment register, and address space #257 causes it to be
970relative to the X86 FS segment. Note that this is a very very low-level
971feature that should only be used if you know what you're doing (for example in
972an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]973
974<p>Here is an example:</p>
975
976<pre>
977#define GS_RELATIVE __attribute__((address_space(256)))
978int foo(int GS_RELATIVE *P) {
979 return *P;
980}
981</pre>
982
983<p>Which compiles to (on X86-32):</p>
984
985<pre>
986_foo:
987 movl 4(%esp), %eax
988 movl %gs:(%eax), %eax
989 ret
990</pre>
991
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]992<!-- ======================================================================= -->
993<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
994<!-- ======================================================================= -->
995
996<p>Clang supports additional attributes that are useful for documenting program
997invariants and rules for static analysis tools. The extensions documented here
998are used by the <a
999href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
1000engine</a> that is part of Clang's Analysis library.</p>
1001
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1002<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1003
1004<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]1005attribute. This attribute, which is typically affixed to a function prototype,
1006indicates that a call to a given function never returns. Function prototypes for
1007common functions like <tt>exit</tt> are typically annotated with this attribute,
1008as well as a variety of common assertion handlers. Users can educate the static
1009analyzer about their own custom assertion handles (thus cutting down on false
1010positives due to false paths) by marking their own &quot;panic&quot; functions
1011with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1012
1013<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]1014there are special functions that for all intents and purposes should be
1015considered panic functions (i.e., they are only called when an internal program
1016error occurs) but may actually return so that the program can fail gracefully.
1017The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
1018as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1019pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1020<tt>noreturn</tt>).</p>
1021
1022<p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1023same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1024placed at the end of function prototypes:</p>
1025
1026<pre>
1027 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1028</pre>
1029
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1030<p>Query for this feature with
1031<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1032
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1033<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
1034
1035<p>Many methods in Objective-C have conventional meanings determined
1036by their selectors. For the purposes of static analysis, it is
1037sometimes useful to be able to mark a method as having a particular
1038conventional meaning despite not having the right selector, or as not
1039having the conventional meaning that its selector would suggest.
1040For these use cases, we provide an attribute to specifically describe
1041the <q>method family</q> that a method belongs to.</p>
1042
1043<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1044where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1045<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
1046can only be placed at the end of a method declaration:</p>
1047
1048<pre>
1049 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1050</pre>
1051
1052<p>Users who do not wish to change the conventional meaning of a
1053method, and who merely want to document its non-standard retain and
1054release semantics, should use the
1055<a href="#attr_retain_release">retaining behavior attributes</a>
1056described below.</p>
1057
1058<p>Query for this feature with
1059<tt>__has_attribute(objc_method_family)</tt>.</p>
1060
1061<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1062
1063<p>In Objective-C, functions and methods are generally assumed to take
1064and return objects with +0 retain counts, with some exceptions for
1065special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
1066there are exceptions, and so Clang provides attributes to allow these
1067exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1068ignore non-leaks). Some exceptions may be better described using
1069the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1070attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1071
1072<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1073<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1074and <tt>cf_returns_not_retained</tt> attributes can be placed on
1075methods and functions that return Objective-C or CoreFoundation
1076objects. They are commonly placed at the end of a function prototype
1077or method declaration:</p>
1078
1079<pre>
1080 id foo() <b>__attribute__((ns_returns_retained))</b>;
1081
1082 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1083</pre>
1084
1085<p>The <tt>*_returns_retained</tt> attributes specify that the
1086returned object has a +1 retain count.
1087The <tt>*_returns_not_retained</tt> attributes specify that the return
1088object has a +0 retain count, even if the normal convention for its
1089selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
1090returned object is +0, but is guaranteed to live at least as long as the
1091next flush of an autorelease pool.</p>
1092
1093<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1094attributes can be placed on an parameter declaration; they specify
1095that the argument is expected to have a +1 retain count, which will be
1096balanced in some way by the function or method.
1097The <tt>ns_consumes_self</tt> attribute can only be placed on an
1098Objective-C method; it specifies that the method expects
1099its <tt>self</tt> parameter to have a +1 retain count, which it will
1100balance in some way.</p>
1101
1102<pre>
1103 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1104
1105 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1106 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1107</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1108
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1109<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1110<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1111
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1112
1113<!-- ======================================================================= -->
Caitlin Sadowski73cbbc82011-07-28 18:38:36 +0000[diff] [blame]1114<h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1115<!-- ======================================================================= -->
1116
1117<p>Clang supports additional attributes for checking basic locking policies in
1118multithreaded programs.
1119Clang currently parses the following list of attributes, although
1120<b>the implementation for these annotations is currently in development.</b>
1121For more details, see the
1122<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
1123</p>
1124
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1125<h4 id="ts_noanal">no_thread_safety_analysis</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1126
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1127<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
1128declaration to specify that the thread safety analysis should not be run on that
1129function. This attribute provides an escape hatch (e.g. for situations when it
1130is difficult to annotate the locking policy). </p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1131
1132<h4 id="ts_lockable">lockable</h4>
1133
1134<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
1135that it has a lockable type (e.g. a Mutex class). This annotation is primarily
1136used to check consistency.</p>
1137
1138<h4 id="ts_scopedlockable">scoped_lockable</h4>
1139
1140<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
1141specify that it has a "scoped" lockable type. Objects of this type will acquire
1142the lock upon construction and release it upon going out of scope.
1143 This annotation is primarily used to check
1144consistency.</p>
1145
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1146<h4 id="ts_guardedvar">guarded_var</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1147
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1148<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
1149specify that the variable must be accessed while holding some lock.</p>
1150
1151<h4 id="ts_ptguardedvar">pt_guarded_var</h4>
1152
1153<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
1154specify that the pointer must be dereferenced while holding some lock.</p>
1155
1156<h4 id="ts_guardedby">guarded_by(l)</h4>
1157
1158<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
1159specify that the variable must be accessed while holding lock l.</p>
1160
1161<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
1162
1163<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
1164specify that the pointer must be dereferenced while holding lock l.</p>
1165
1166<h4 id="ts_acquiredbefore">acquired_before(...)</h4>
1167
1168<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
1169of a lockable variable to specify that the lock must be acquired before all
1170attribute arguments. Arguments must be lockable type, and there must be at
1171least one argument.</p>
1172
1173<h4 id="ts_acquiredafter">acquired_after(...)</h4>
1174
1175<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
1176of a lockable variable to specify that the lock must be acquired after all
1177attribute arguments. Arguments must be lockable type, and there must be at
1178least one argument.</p>
1179
1180<h4 id="ts_elf">exclusive_lock_function(...)</h4>
1181
1182<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1183declaration to specify that the function acquires all listed locks
1184exclusively. This attribute takes zero or more
1185arguments: either of lockable type or integers indexing into
1186function parameters of lockable type. If no arguments are given, the acquired
1187lock is implicitly <tt>this</tt> of the enclosing object.</p>
1188
1189<h4 id="ts_slf">shared_lock_function(...)</h4>
1190
1191<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1192declaration to specify that the function acquires all listed locks, although
1193 the locks may be shared (e.g. read locks).
1194This attribute takes zero or more
1195arguments: either of lockable type or integers indexing into
1196function parameters of lockable type. If no arguments are given, the acquired
1197lock is implicitly <tt>this</tt> of the enclosing object.</p>
1198
1199<h4 id="ts_etf">exclusive_trylock_function(...)</h4>
1200
1201<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1202declaration to specify that the function will try (without blocking) to acquire
1203all listed locks exclusively. This attribute takes one or more
1204arguments. The first argument is an integer or boolean value specifying the
1205return value of a successful lock acquisition. The remaining arugments are
1206either of lockable type or integers indexing into
1207function parameters of lockable type. If only one argument is given, the
1208acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1209
1210<h4 id="ts_stf">shared_trylock_function(...)</h4>
1211
1212<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1213declaration to specify that the function will try (without blocking) to acquire
1214all listed locks, although
1215 the locks may be shared (e.g. read locks).
1216This attribute takes one or more
1217arguments. The first argument is an integer or boolean value specifying the
1218return value of a successful lock acquisition. The remaining arugments are
1219either of lockable type or integers indexing into
1220function parameters of lockable type. If only one argument is given, the
1221acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1222
1223<h4 id="ts_uf">unlock_function(...)</h4>
1224
1225<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
1226declaration to specify that the function release all listed locks.
1227 This attribute takes zero or more
1228arguments: either of lockable type or integers indexing into
1229function parameters of lockable type. If no arguments are given, the acquired
1230lock is implicitly <tt>this</tt> of the enclosing object.</p>
1231
1232<h4 id="ts_lr">lock_returned(l)</h4>
1233
1234<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
1235declaration to specify that the function returns lock l (l must be of lockable
1236type). This annotation is used
1237to aid in resolving lock expressions.</p>
1238
1239<h4 id="ts_le">locks_excluded(...)</h4>
1240
1241<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
1242to specify that the function must not be called with the listed locks.
1243Arguments must be lockable type, and there must be at
1244least one argument.</p>
1245
1246<h4 id="ts_elr">exclusive_locks_required(...)</h4>
1247
1248<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
1249declaration to specify that the function must be called while holding the listed
1250exclusive locks. Arguments must be lockable type, and there must be at
1251least one argument.</p>
1252
1253<h4 id="ts_slr">shared_locks_required(...)</h4>
1254
1255<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
1256declaration to specify that the function must be called while holding the listed
1257shared locks. Arguments must be lockable type, and there must be at
1258least one argument.</p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1259
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1260</div>
1261</body>
1262</html>