Sean Hunt | 7e98b47 | 2011-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 Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 4 | <html> |
| 5 | <head> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 6 | <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
Eli Friedman | 0c706c2 | 2011-09-19 23:17:44 +0000 | [diff] [blame] | 7 | <title>Clang Language Extensions</title> |
Sean Hunt | 64f857b | 2011-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 Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 10 | <style type="text/css"> |
| 11 | td { |
| 12 | vertical-align: top; |
| 13 | } |
Benjamin Kramer | 3419d7c | 2012-01-15 16:42:14 +0000 | [diff] [blame] | 14 | th { background-color: #ffddaa; } |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 15 | </style> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 16 | </head> |
| 17 | <body> |
| 18 | |
| 19 | <!--#include virtual="../menu.html.incl"--> |
| 20 | |
| 21 | <div id="content"> |
| 22 | |
| 23 | <h1>Clang Language Extensions</h1> |
| 24 | |
| 25 | <ul> |
| 26 | <li><a href="#intro">Introduction</a></li> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 27 | <li><a href="#feature_check">Feature Checking Macros</a></li> |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 28 | <li><a href="#has_include">Include File Checking Macros</a></li> |
Chris Lattner | 81edc9f | 2009-04-13 02:45:46 +0000 | [diff] [blame] | 29 | <li><a href="#builtinmacros">Builtin Macros</a></li> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 30 | <li><a href="#vectors">Vectors and Extended Vectors</a></li> |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 31 | <li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li> |
| 32 | <li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 33 | <li><a href="#checking_language_features">Checks for Standard Language Features</a> |
Ted Kremenek | 22c3410 | 2009-12-03 02:05:57 +0000 | [diff] [blame] | 34 | <ul> |
| 35 | <li><a href="#cxx_exceptions">C++ exceptions</a></li> |
| 36 | <li><a href="#cxx_rtti">C++ RTTI</a></li> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 37 | </ul></li> |
| 38 | <li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 39 | <ul> |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 40 | <li><a href="#cxx0x">C++11</a> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 41 | <ul> |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 42 | <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes |
| 43 | access control</a></li> |
| 44 | <li><a href="#cxx_alias_templates">C++11 alias templates</a></li> |
| 45 | <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li> |
| 46 | <li><a href="#cxx_attributes">C++11 attributes</a></li> |
| 47 | <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li> |
| 48 | <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li> |
| 49 | <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li> |
Douglas Gregor | f695a69 | 2011-11-01 01:19:34 +0000 | [diff] [blame] | 50 | <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li> |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 51 | <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li> |
| 52 | <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li> |
| 53 | <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li> |
| 54 | <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li> |
| 55 | <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li> |
| 56 | <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li> |
| 57 | <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li> |
| 58 | <li><a href="#cxx_lambdas">C++11 lambdas</a></li> |
| 59 | <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li> |
| 60 | <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li> |
| 61 | <li><a href="#cxx_nullptr">C++11 nullptr</a></li> |
| 62 | <li><a href="#cxx_override_control">C++11 override control</a></li> |
| 63 | <li><a href="#cxx_range_for">C++11 range-based for loop</a></li> |
| 64 | <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li> |
| 65 | <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li> |
| 66 | <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li> |
| 67 | <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li> |
| 68 | <li><a href="#cxx_auto_type">C++11 type inference</a></li> |
| 69 | <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li> |
| 70 | <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li> |
| 71 | <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li> |
| 72 | <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li> |
| 73 | <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li> |
| 74 | <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 75 | </ul></li> |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 76 | <li><a href="#c11">C11</a> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 77 | <ul> |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 78 | <li><a href="#c_alignas">C11 alignment specifiers</a></li> |
| 79 | <li><a href="#c_generic_selections">C11 generic selections</a></li> |
| 80 | <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 81 | </ul></li> |
| 82 | </ul> </li> |
Douglas Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 83 | <li><a href="#checking_type_traits">Checks for Type Traits</a></li> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 84 | <li><a href="#blocks">Blocks</a></li> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 85 | <li><a href="#objc_features">Objective-C Features</a> |
| 86 | <ul> |
| 87 | <li><a href="#objc_instancetype">Related result types</a></li> |
John McCall | f85e193 | 2011-06-15 23:02:42 +0000 | [diff] [blame] | 88 | <li><a href="#objc_arc">Automatic reference counting</a></li> |
Douglas Gregor | 5471bc8 | 2011-09-08 17:18:35 +0000 | [diff] [blame] | 89 | <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 90 | </ul> |
| 91 | </li> |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 92 | <li><a href="#overloading-in-c">Function Overloading in C</a></li> |
Eli Friedman | 0c706c2 | 2011-09-19 23:17:44 +0000 | [diff] [blame] | 93 | <li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 94 | <li><a href="#builtins">Builtin Functions</a> |
| 95 | <ul> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 96 | <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> |
Chris Lattner | 21190d5 | 2009-09-21 03:09:59 +0000 | [diff] [blame] | 97 | <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li> |
Chris Lattner | 23aa9c8 | 2011-04-09 03:57:26 +0000 | [diff] [blame] | 98 | <li><a href="#__sync_swap">__sync_swap</a></li> |
Douglas Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 99 | </ul> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 100 | </li> |
Chris Lattner | 1177f91 | 2009-04-09 19:58:15 +0000 | [diff] [blame] | 101 | <li><a href="#targetspecific">Target-Specific Extensions</a> |
| 102 | <ul> |
| 103 | <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li> |
| 104 | </ul> |
| 105 | </li> |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 106 | <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 107 | <li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a> |
Kostya Serebryany | ce98c9b | 2011-11-28 20:51:02 +0000 | [diff] [blame] | 108 | <ul> |
| 109 | <li><a href="#address_sanitizer">AddressSanitizer</a></li> |
| 110 | </ul> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 111 | </li> |
| 112 | <li><a href="#threadsafety">Thread Safety Annotation Checking</a> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 113 | <ul> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 114 | <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li> |
| 115 | <li><a href="#ts_lockable"><tt>lockable</tt></a></li> |
| 116 | <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 117 | <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li> |
| 118 | <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 119 | <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li> |
| 120 | <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li> |
| 121 | <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li> |
| 122 | <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li> |
| 123 | <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li> |
| 124 | <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li> |
| 125 | <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li> |
| 126 | <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li> |
| 127 | <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li> |
| 128 | <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li> |
| 129 | <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li> |
| 130 | <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li> |
| 131 | <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 132 | </ul> |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 133 | </li> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 134 | </ul> |
| 135 | |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 136 | <!-- ======================================================================= --> |
| 137 | <h2 id="intro">Introduction</h2> |
| 138 | <!-- ======================================================================= --> |
| 139 | |
| 140 | <p>This document describes the language extensions provided by Clang. In |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 141 | addition to the language extensions listed here, Clang aims to support a broad |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 142 | range of GCC extensions. Please see the <a |
| 143 | href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for |
| 144 | more information on these extensions.</p> |
| 145 | |
| 146 | <!-- ======================================================================= --> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 147 | <h2 id="feature_check">Feature Checking Macros</h2> |
| 148 | <!-- ======================================================================= --> |
| 149 | |
| 150 | <p>Language extensions can be very useful, but only if you know you can depend |
Chris Lattner | c70e193 | 2011-03-21 16:25:11 +0000 | [diff] [blame] | 151 | on them. In order to allow fine-grain features checks, we support three builtin |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 152 | function-like macros. This allows you to directly test for a feature in your |
| 153 | code without having to resort to something like autoconf or fragile "compiler |
| 154 | version checks".</p> |
| 155 | |
| 156 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 157 | <h3><a name="__has_builtin">__has_builtin</a></h3> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 158 | <!-- ======================================================================= --> |
| 159 | |
| 160 | <p>This function-like macro takes a single identifier argument that is the name |
| 161 | of a builtin function. It evaluates to 1 if the builtin is supported or 0 if |
| 162 | not. It can be used like this:</p> |
| 163 | |
| 164 | <blockquote> |
| 165 | <pre> |
| 166 | #ifndef __has_builtin // Optional of course. |
| 167 | #define __has_builtin(x) 0 // Compatibility with non-clang compilers. |
| 168 | #endif |
| 169 | |
| 170 | ... |
| 171 | #if __has_builtin(__builtin_trap) |
| 172 | __builtin_trap(); |
| 173 | #else |
| 174 | abort(); |
| 175 | #endif |
| 176 | ... |
| 177 | </pre> |
| 178 | </blockquote> |
| 179 | |
| 180 | |
| 181 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 182 | <h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 183 | <!-- ======================================================================= --> |
| 184 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 185 | <p>These function-like macros take a single identifier argument that is the |
| 186 | name of a feature. <code>__has_feature</code> evaluates to 1 if the feature |
| 187 | is both supported by Clang and standardized in the current language standard |
| 188 | or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while |
| 189 | <code>__has_extension</code> evaluates to 1 if the feature is supported by |
| 190 | Clang in the current language (either as a language extension or a standard |
| 191 | language feature) or 0 if not. They can be used like this:</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 192 | |
| 193 | <blockquote> |
| 194 | <pre> |
| 195 | #ifndef __has_feature // Optional of course. |
| 196 | #define __has_feature(x) 0 // Compatibility with non-clang compilers. |
| 197 | #endif |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 198 | #ifndef __has_extension |
| 199 | #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. |
| 200 | #endif |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 201 | |
| 202 | ... |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 203 | #if __has_feature(cxx_rvalue_references) |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 204 | // This code will only be compiled with the -std=c++11 and -std=gnu++11 |
| 205 | // options, because rvalue references are only standardized in C++11. |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 206 | #endif |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 207 | |
| 208 | #if __has_extension(cxx_rvalue_references) |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 209 | // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 210 | // and -std=gnu++98 options, because rvalue references are supported as a |
| 211 | // language extension in C++98. |
| 212 | #endif |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 213 | </pre> |
| 214 | </blockquote> |
| 215 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 216 | <p id="has_feature_back_compat">For backwards compatibility reasons, |
| 217 | <code>__has_feature</code> can also be used to test for support for |
| 218 | non-standardized features, i.e. features not prefixed <code>c_</code>, |
| 219 | <code>cxx_</code> or <code>objc_</code>.</p> |
| 220 | |
Kostya Serebryany | ce98c9b | 2011-11-28 20:51:02 +0000 | [diff] [blame] | 221 | <p id="has_feature_for_non_language_features"> |
| 222 | Another use of <code>__has_feature</code> is to check for compiler features |
| 223 | not related to the language standard, such as e.g. |
| 224 | <a href="AddressSanitizer.html">AddressSanitizer</a>. |
| 225 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 226 | <p>If the <code>-pedantic-errors</code> option is given, |
| 227 | <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p> |
| 228 | |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 229 | <p>The feature tag is described along with the language feature below.</p> |
| 230 | |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 231 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 232 | <h3><a name="__has_attribute">__has_attribute</a></h3> |
Anders Carlsson | cae5095 | 2010-10-20 02:31:43 +0000 | [diff] [blame] | 233 | <!-- ======================================================================= --> |
| 234 | |
| 235 | <p>This function-like macro takes a single identifier argument that is the name |
| 236 | of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It |
| 237 | can be used like this:</p> |
| 238 | |
| 239 | <blockquote> |
| 240 | <pre> |
| 241 | #ifndef __has_attribute // Optional of course. |
| 242 | #define __has_attribute(x) 0 // Compatibility with non-clang compilers. |
| 243 | #endif |
| 244 | |
| 245 | ... |
Anders Carlsson | 961003d | 2011-01-24 03:54:51 +0000 | [diff] [blame] | 246 | #if __has_attribute(always_inline) |
| 247 | #define ALWAYS_INLINE __attribute__((always_inline)) |
Anders Carlsson | cae5095 | 2010-10-20 02:31:43 +0000 | [diff] [blame] | 248 | #else |
Anders Carlsson | 961003d | 2011-01-24 03:54:51 +0000 | [diff] [blame] | 249 | #define ALWAYS_INLINE |
Anders Carlsson | cae5095 | 2010-10-20 02:31:43 +0000 | [diff] [blame] | 250 | #endif |
| 251 | ... |
| 252 | </pre> |
| 253 | </blockquote> |
| 254 | |
| 255 | <!-- ======================================================================= --> |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 256 | <h2 id="has_include">Include File Checking Macros</h2> |
| 257 | <!-- ======================================================================= --> |
| 258 | |
| 259 | <p>Not all developments systems have the same include files. |
| 260 | The <a href="#__has_include">__has_include</a> and |
| 261 | <a href="#__has_include_next">__has_include_next</a> macros allow you to |
| 262 | check for the existence of an include file before doing |
| 263 | a possibly failing #include directive.</p> |
| 264 | |
| 265 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 266 | <h3><a name="__has_include">__has_include</a></h3> |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 267 | <!-- ======================================================================= --> |
| 268 | |
| 269 | <p>This function-like macro takes a single file name string argument that |
| 270 | is the name of an include file. It evaluates to 1 if the file can |
| 271 | be found using the include paths, or 0 otherwise:</p> |
| 272 | |
| 273 | <blockquote> |
| 274 | <pre> |
| 275 | // Note the two possible file name string formats. |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 276 | #if __has_include("myinclude.h") && __has_include(<stdint.h>) |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 277 | # include "myinclude.h" |
| 278 | #endif |
| 279 | |
| 280 | // To avoid problem with non-clang compilers not having this macro. |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 281 | #if defined(__has_include) && __has_include("myinclude.h") |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 282 | # include "myinclude.h" |
| 283 | #endif |
| 284 | </pre> |
| 285 | </blockquote> |
| 286 | |
| 287 | <p>To test for this feature, use #if defined(__has_include).</p> |
| 288 | |
| 289 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 290 | <h3><a name="__has_include_next">__has_include_next</a></h3> |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 291 | <!-- ======================================================================= --> |
| 292 | |
| 293 | <p>This function-like macro takes a single file name string argument that |
| 294 | is the name of an include file. It is like __has_include except that it |
| 295 | looks for the second instance of the given file found in the include |
| 296 | paths. It evaluates to 1 if the second instance of the file can |
| 297 | be found using the include paths, or 0 otherwise:</p> |
| 298 | |
| 299 | <blockquote> |
| 300 | <pre> |
| 301 | // Note the two possible file name string formats. |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 302 | #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 303 | # include_next "myinclude.h" |
| 304 | #endif |
| 305 | |
| 306 | // To avoid problem with non-clang compilers not having this macro. |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 307 | #if defined(__has_include_next) && __has_include_next("myinclude.h") |
John Thompson | 92bd8c7 | 2009-11-02 22:28:12 +0000 | [diff] [blame] | 308 | # include_next "myinclude.h" |
| 309 | #endif |
| 310 | </pre> |
| 311 | </blockquote> |
| 312 | |
| 313 | <p>Note that __has_include_next, like the GNU extension |
| 314 | #include_next directive, is intended for use in headers only, |
| 315 | and will issue a warning if used in the top-level compilation |
| 316 | file. A warning will also be issued if an absolute path |
| 317 | is used in the file argument.</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 318 | |
Ted Kremenek | d768150 | 2011-10-12 19:46:30 +0000 | [diff] [blame] | 319 | |
| 320 | <!-- ======================================================================= --> |
| 321 | <h3><a name="__has_warning">__has_warning</a></h3> |
| 322 | <!-- ======================================================================= --> |
| 323 | |
| 324 | <p>This function-like macro takes a string literal that represents a command |
| 325 | line option for a warning and returns true if that is a valid warning |
| 326 | option.</p> |
| 327 | |
| 328 | <blockquote> |
| 329 | <pre> |
| 330 | #if __has_warning("-Wformat") |
| 331 | ... |
| 332 | #endif |
| 333 | </pre> |
| 334 | </blockquote> |
| 335 | |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 336 | <!-- ======================================================================= --> |
Chris Lattner | 81edc9f | 2009-04-13 02:45:46 +0000 | [diff] [blame] | 337 | <h2 id="builtinmacros">Builtin Macros</h2> |
| 338 | <!-- ======================================================================= --> |
| 339 | |
Douglas Gregor | 4290fbd | 2010-04-30 02:51:06 +0000 | [diff] [blame] | 340 | <dl> |
| 341 | <dt><code>__BASE_FILE__</code></dt> |
| 342 | <dd>Defined to a string that contains the name of the main input |
| 343 | file passed to Clang.</dd> |
| 344 | |
| 345 | <dt><code>__COUNTER__</code></dt> |
| 346 | <dd>Defined to an integer value that starts at zero and is |
| 347 | incremented each time the <code>__COUNTER__</code> macro is |
| 348 | expanded.</dd> |
| 349 | |
| 350 | <dt><code>__INCLUDE_LEVEL__</code></dt> |
| 351 | <dd>Defined to an integral value that is the include depth of the |
| 352 | file currently being translated. For the main file, this value is |
| 353 | zero.</dd> |
| 354 | |
| 355 | <dt><code>__TIMESTAMP__</code></dt> |
| 356 | <dd>Defined to the date and time of the last modification of the |
| 357 | current source file.</dd> |
| 358 | |
| 359 | <dt><code>__clang__</code></dt> |
| 360 | <dd>Defined when compiling with Clang</dd> |
| 361 | |
| 362 | <dt><code>__clang_major__</code></dt> |
Chris Lattner | d4b66b9 | 2011-12-15 19:06:36 +0000 | [diff] [blame] | 363 | <dd>Defined to the major marketing version number of Clang (e.g., the |
| 364 | 2 in 2.0.1). Note that marketing version numbers should not be used to |
| 365 | check for language features, as different vendors use different numbering |
| 366 | schemes. Instead, use the <a href="#feature_check">feature checking |
| 367 | macros</a>.</dd> |
Douglas Gregor | 4290fbd | 2010-04-30 02:51:06 +0000 | [diff] [blame] | 368 | |
| 369 | <dt><code>__clang_minor__</code></dt> |
| 370 | <dd>Defined to the minor version number of Clang (e.g., the 0 in |
Chris Lattner | d4b66b9 | 2011-12-15 19:06:36 +0000 | [diff] [blame] | 371 | 2.0.1). Note that marketing version numbers should not be used to |
| 372 | check for language features, as different vendors use different numbering |
| 373 | schemes. Instead, use the <a href="#feature_check">feature checking |
| 374 | macros</a>.</dd> |
Douglas Gregor | 4290fbd | 2010-04-30 02:51:06 +0000 | [diff] [blame] | 375 | |
| 376 | <dt><code>__clang_patchlevel__</code></dt> |
Chris Lattner | d4b66b9 | 2011-12-15 19:06:36 +0000 | [diff] [blame] | 377 | <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd> |
Douglas Gregor | 4290fbd | 2010-04-30 02:51:06 +0000 | [diff] [blame] | 378 | |
| 379 | <dt><code>__clang_version__</code></dt> |
Chris Lattner | d4b66b9 | 2011-12-15 19:06:36 +0000 | [diff] [blame] | 380 | <dd>Defined to a string that captures the Clang marketing version, including |
| 381 | the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd> |
Douglas Gregor | 4290fbd | 2010-04-30 02:51:06 +0000 | [diff] [blame] | 382 | </dl> |
Chris Lattner | 81edc9f | 2009-04-13 02:45:46 +0000 | [diff] [blame] | 383 | |
| 384 | <!-- ======================================================================= --> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 385 | <h2 id="vectors">Vectors and Extended Vectors</h2> |
| 386 | <!-- ======================================================================= --> |
| 387 | |
Anton Yartsev | da90c77 | 2012-01-15 16:22:24 +0000 | [diff] [blame] | 388 | <p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p> |
Owen Anderson | d2bf0cd | 2010-01-27 01:22:36 +0000 | [diff] [blame] | 389 | |
Benjamin Kramer | 3419d7c | 2012-01-15 16:42:14 +0000 | [diff] [blame] | 390 | <p>OpenCL vector types are created using <tt>ext_vector_type</tt> attribute. It |
| 391 | support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An |
| 392 | example is:</p> |
Owen Anderson | d2bf0cd | 2010-01-27 01:22:36 +0000 | [diff] [blame] | 393 | |
| 394 | <blockquote> |
| 395 | <pre> |
| 396 | typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>; |
| 397 | typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>; |
| 398 | |
| 399 | float4 foo(float2 a, float2 b) { |
| 400 | float4 c; |
| 401 | c.xz = a; |
| 402 | c.yw = b; |
| 403 | return c; |
| 404 | } |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 405 | </pre> |
Owen Anderson | d2bf0cd | 2010-01-27 01:22:36 +0000 | [diff] [blame] | 406 | </blockquote> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 407 | |
Benjamin Kramer | 3419d7c | 2012-01-15 16:42:14 +0000 | [diff] [blame] | 408 | <p>Query for this feature with |
| 409 | <tt>__has_extension(attribute_ext_vector_type)</tt>.</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 410 | |
Benjamin Kramer | 3419d7c | 2012-01-15 16:42:14 +0000 | [diff] [blame] | 411 | <p>Giving <tt>-faltivec</tt> option to clang enables support for AltiVec vector |
| 412 | syntax and functions. For example:</p> |
Anton Yartsev | da90c77 | 2012-01-15 16:22:24 +0000 | [diff] [blame] | 413 | |
| 414 | <blockquote> |
| 415 | <pre> |
| 416 | vector float foo(vector int a) { |
| 417 | vector int b; |
| 418 | b = vec_add(a, a) + a; |
| 419 | return (vector float)b; |
| 420 | } |
| 421 | </pre> |
| 422 | </blockquote> |
| 423 | |
| 424 | <p>NEON vector types are created using <tt>neon_vector_type</tt> and |
| 425 | <tt>neon_polyvector_type</tt> attributes. For example:</p> |
| 426 | |
| 427 | <blockquote> |
| 428 | <pre> |
| 429 | typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t; |
| 430 | typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t; |
| 431 | |
| 432 | int8x8_t foo(int8x8_t a) { |
| 433 | int8x8_t v; |
| 434 | v = a; |
| 435 | return v; |
| 436 | } |
| 437 | </pre> |
| 438 | </blockquote> |
| 439 | |
| 440 | <!-- ======================================================================= --> |
| 441 | <h3><a name="vector_literals">Vector Literals</a></h3> |
| 442 | <!-- ======================================================================= --> |
| 443 | |
| 444 | <p>Vector literals can be used to create vectors from a set of scalars, or |
| 445 | vectors. Either parentheses or braces form can be used. In the parentheses form |
| 446 | the number of literal values specified must be one, i.e. referring to a scalar |
| 447 | value, or must match the size of the vector type being created. If a single |
| 448 | scalar literal value is specified, the scalar literal value will be replicated |
| 449 | to all the components of the vector type. In the brackets form any number of |
| 450 | literals can be specified. For example:</p> |
| 451 | |
| 452 | <blockquote> |
| 453 | <pre> |
| 454 | typedef int v4si __attribute__((__vector_size__(16))); |
| 455 | typedef float float4 __attribute__((ext_vector_type(4))); |
| 456 | typedef float float2 __attribute__((ext_vector_type(2))); |
| 457 | |
| 458 | v4si vsi = (v4si){1, 2, 3, 4}; |
| 459 | float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); |
| 460 | vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). |
| 461 | vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). |
| 462 | vector int vi3 = (vector int)(1, 2); // error |
| 463 | vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). |
| 464 | vector int vi5 = (vector int)(1, 2, 3, 4); |
| 465 | float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); |
| 466 | </pre> |
| 467 | </blockquote> |
| 468 | |
| 469 | <!-- ======================================================================= --> |
| 470 | <h3><a name="vector_operations">Vector Operations</a></h3> |
| 471 | <!-- ======================================================================= --> |
| 472 | |
| 473 | <p>The table below shows the support for each operation by vector extension. |
| 474 | A dash indicates that an operation is not accepted according to a corresponding |
| 475 | specification.</p> |
| 476 | |
| 477 | <table width="500" border="1" cellspacing="0"> |
| 478 | <tr> |
Benjamin Kramer | 3419d7c | 2012-01-15 16:42:14 +0000 | [diff] [blame] | 479 | <th>Operator</th> |
| 480 | <th>OpenCL</th> |
| 481 | <th>AltiVec</th> |
| 482 | <th>GCC</th> |
| 483 | <th>NEON</th> |
Anton Yartsev | da90c77 | 2012-01-15 16:22:24 +0000 | [diff] [blame] | 484 | </tr> |
| 485 | <tr> |
| 486 | <td>[]</td> |
| 487 | <td align="center">yes</td> |
| 488 | <td align="center">yes</td> |
| 489 | <td align="center">yes</td> |
| 490 | <td align="center">-</td> |
| 491 | </tr> |
| 492 | <tr> |
| 493 | <td>unary operators +, -</td> |
| 494 | <td align="center">yes</td> |
| 495 | <td align="center">yes</td> |
| 496 | <td align="center">yes</td> |
| 497 | <td align="center">-</td> |
| 498 | </tr> |
| 499 | <tr> |
| 500 | <td>++, --</td> |
| 501 | <td align="center">yes</td> |
| 502 | <td align="center">yes</td> |
| 503 | <td align="center">-</td> |
| 504 | <td align="center">-</td> |
| 505 | </tr> |
| 506 | <tr> |
| 507 | <td>+, -, *, /, %</td> |
| 508 | <td align="center">yes</td> |
| 509 | <td align="center">yes</td> |
| 510 | <td align="center">yes</td> |
| 511 | <td align="center">-</td> |
| 512 | </tr> |
| 513 | <tr> |
| 514 | <td>bitwise operators &, |, ^, ~</td> |
| 515 | <td align="center">yes</td> |
| 516 | <td align="center">yes</td> |
| 517 | <td align="center">yes</td> |
| 518 | <td align="center">-</td> |
| 519 | </tr> |
| 520 | <tr> |
| 521 | <td>>>, <<</td> |
| 522 | <td align="center">yes</td> |
| 523 | <td align="center">yes</td> |
| 524 | <td align="center">yes</td> |
| 525 | <td align="center">-</td> |
| 526 | </tr> |
| 527 | <tr> |
| 528 | <td>!, &&,||</td> |
| 529 | <td align="center">no</td> |
| 530 | <td align="center">-</td> |
| 531 | <td align="center">-</td> |
| 532 | <td align="center">-</td> |
| 533 | </tr> |
| 534 | <tr> |
| 535 | <td>==,!=, >, <, >=, <=</td> |
| 536 | <td align="center">yes</td> |
| 537 | <td align="center">yes</td> |
| 538 | <td align="center">-</td> |
| 539 | <td align="center">-</td> |
| 540 | </tr> |
| 541 | <tr> |
| 542 | <td>=</td> |
| 543 | <td align="center">yes</td> |
| 544 | <td align="center">yes</td> |
| 545 | <td align="center">yes</td> |
| 546 | <td align="center">yes</td> |
| 547 | </tr> |
| 548 | <tr> |
| 549 | <td>:?</td> |
| 550 | <td align="center">yes</td> |
| 551 | <td align="center">-</td> |
| 552 | <td align="center">-</td> |
| 553 | <td align="center">-</td> |
| 554 | </tr> |
| 555 | <tr> |
| 556 | <td>sizeof</td> |
| 557 | <td align="center">yes</td> |
| 558 | <td align="center">yes</td> |
| 559 | <td align="center">yes</td> |
| 560 | <td align="center">yes</td> |
| 561 | </tr> |
| 562 | </table> |
| 563 | |
Owen Anderson | d2bf0cd | 2010-01-27 01:22:36 +0000 | [diff] [blame] | 564 | <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p> |
| 565 | |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 566 | <!-- ======================================================================= --> |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 567 | <h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2> |
Fariborz Jahanian | c784dc1 | 2010-10-06 23:12:32 +0000 | [diff] [blame] | 568 | <!-- ======================================================================= --> |
| 569 | |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 570 | <p>An optional string message can be added to the <tt>deprecated</tt> |
| 571 | and <tt>unavailable</tt> attributes. For example:</p> |
Fariborz Jahanian | c784dc1 | 2010-10-06 23:12:32 +0000 | [diff] [blame] | 572 | |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 573 | <blockquote> |
Chris Lattner | 4836d6a | 2010-11-09 19:43:35 +0000 | [diff] [blame] | 574 | <pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre> |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 575 | </blockquote> |
| 576 | |
| 577 | <p>If the deprecated or unavailable declaration is used, the message |
| 578 | will be incorporated into the appropriate diagnostic:</p> |
| 579 | |
| 580 | <blockquote> |
Chris Lattner | 4836d6a | 2010-11-09 19:43:35 +0000 | [diff] [blame] | 581 | <pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations] |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 582 | explode(); |
| 583 | ^</pre> |
| 584 | </blockquote> |
| 585 | |
| 586 | <p>Query for this feature |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 587 | with <tt>__has_extension(attribute_deprecated_with_message)</tt> |
| 588 | and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p> |
John McCall | 4820908 | 2010-11-08 19:48:17 +0000 | [diff] [blame] | 589 | |
| 590 | <!-- ======================================================================= --> |
| 591 | <h2 id="attributes-on-enumerators">Attributes on Enumerators</h2> |
| 592 | <!-- ======================================================================= --> |
| 593 | |
| 594 | <p>Clang allows attributes to be written on individual enumerators. |
| 595 | This allows enumerators to be deprecated, made unavailable, etc. The |
| 596 | attribute must appear after the enumerator name and before any |
| 597 | initializer, like so:</p> |
| 598 | |
| 599 | <blockquote> |
| 600 | <pre>enum OperationMode { |
| 601 | OM_Invalid, |
| 602 | OM_Normal, |
| 603 | OM_Terrified __attribute__((deprecated)), |
| 604 | OM_AbortOnError __attribute__((deprecated)) = 4 |
| 605 | };</pre> |
| 606 | </blockquote> |
| 607 | |
| 608 | <p>Attributes on the <tt>enum</tt> declaration do not apply to |
| 609 | individual enumerators.</p> |
| 610 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 611 | <p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p> |
Fariborz Jahanian | c784dc1 | 2010-10-06 23:12:32 +0000 | [diff] [blame] | 612 | |
| 613 | <!-- ======================================================================= --> |
Ted Kremenek | 87774fd | 2009-12-03 02:04:01 +0000 | [diff] [blame] | 614 | <h2 id="checking_language_features">Checks for Standard Language Features</h2> |
| 615 | <!-- ======================================================================= --> |
| 616 | |
| 617 | <p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are |
| 618 | enabled. Those features are listed here.</p> |
| 619 | |
Ted Kremenek | 22c3410 | 2009-12-03 02:05:57 +0000 | [diff] [blame] | 620 | <h3 id="cxx_exceptions">C++ exceptions</h3> |
Ted Kremenek | 87774fd | 2009-12-03 02:04:01 +0000 | [diff] [blame] | 621 | |
Ted Kremenek | 22c3410 | 2009-12-03 02:05:57 +0000 | [diff] [blame] | 622 | <p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For |
Sean Hunt | 647ba1b | 2011-06-23 00:42:53 +0000 | [diff] [blame] | 623 | example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p> |
Ted Kremenek | 87774fd | 2009-12-03 02:04:01 +0000 | [diff] [blame] | 624 | |
Ted Kremenek | 22c3410 | 2009-12-03 02:05:57 +0000 | [diff] [blame] | 625 | <h3 id="cxx_rtti">C++ RTTI</h3> |
Ted Kremenek | 87774fd | 2009-12-03 02:04:01 +0000 | [diff] [blame] | 626 | |
Ted Kremenek | 0eb9560 | 2009-12-03 02:06:43 +0000 | [diff] [blame] | 627 | <p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example, |
Ted Kremenek | 22c3410 | 2009-12-03 02:05:57 +0000 | [diff] [blame] | 628 | compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p> |
Ted Kremenek | 87774fd | 2009-12-03 02:04:01 +0000 | [diff] [blame] | 629 | |
| 630 | <!-- ======================================================================= --> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 631 | <h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2> |
| 632 | <!-- ======================================================================= --> |
| 633 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 634 | <p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used |
| 635 | to query if certain upcoming standard language features are enabled. Those |
| 636 | features are listed here. Features that are not yet implemented will be |
| 637 | noted.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 638 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 639 | <h3 id="cxx0x">C++11</h3> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 640 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 641 | <p>The features listed below are slated for inclusion in the upcoming |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 642 | C++11 standard. As a result, all these features are enabled |
| 643 | with the <tt>-std=c++11</tt> option when compiling C++ code.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 644 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 645 | <h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4> |
Douglas Gregor | 7822ee3 | 2011-05-11 23:45:11 +0000 | [diff] [blame] | 646 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 647 | <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 Gregor | 7822ee3 | 2011-05-11 23:45:11 +0000 | [diff] [blame] | 648 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 649 | <h4 id="cxx_alias_templates">C++11 alias templates</h4> |
Richard Smith | 3e4c6c4 | 2011-05-05 21:57:07 +0000 | [diff] [blame] | 650 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 651 | <p>Use <tt>__has_feature(cxx_alias_templates)</tt> or |
| 652 | <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 653 | C++11's alias declarations and alias templates is enabled.</p> |
Richard Smith | 3e4c6c4 | 2011-05-05 21:57:07 +0000 | [diff] [blame] | 654 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 655 | <h4 id="cxx_alignas">C++11 alignment specifiers</h4> |
Peter Collingbourne | fd5f686 | 2011-10-14 23:44:46 +0000 | [diff] [blame] | 656 | |
| 657 | <p>Use <tt>__has_feature(cxx_alignas)</tt> or |
| 658 | <tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment |
| 659 | specifiers using <tt>alignas</tt> is enabled.</p> |
| 660 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 661 | <h4 id="cxx_attributes">C++11 attributes</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 662 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 663 | <p>Use <tt>__has_feature(cxx_attributes)</tt> or |
| 664 | <tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 665 | parsing with C++11's square bracket notation is enabled.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 666 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 667 | <h4 id="cxx_constexpr">C++11 generalized constant expressions</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 668 | |
| 669 | <p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support |
| 670 | for generalized constant expressions (e.g., <tt>constexpr</tt>) is |
| 671 | enabled. Clang does not currently implement this feature.</p> |
| 672 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 673 | <h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 674 | |
| 675 | <p>Use <tt>__has_feature(cxx_decltype)</tt> or |
| 676 | <tt>__has_extension(cxx_decltype)</tt> to determine if support for the |
| 677 | <tt>decltype()</tt> specifier is enabled.</p> |
| 678 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 679 | <h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4> |
Douglas Gregor | 0750800 | 2011-02-05 20:35:30 +0000 | [diff] [blame] | 680 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 681 | <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or |
| 682 | <tt>__has_extension(cxx_default_function_template_args)</tt> to determine |
| 683 | if support for default template arguments in function templates is enabled.</p> |
Douglas Gregor | 0750800 | 2011-02-05 20:35:30 +0000 | [diff] [blame] | 684 | |
Douglas Gregor | f695a69 | 2011-11-01 01:19:34 +0000 | [diff] [blame] | 685 | <h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4> |
| 686 | |
| 687 | <p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or |
| 688 | <tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for |
| 689 | defaulted function definitions (with <tt>= default</tt>) is enabled.</p> |
| 690 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 691 | <h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4> |
Sean Hunt | d962499 | 2011-06-23 06:11:37 +0000 | [diff] [blame] | 692 | |
| 693 | <p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if |
| 694 | support for delegating constructors is enabled.</p> |
| 695 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 696 | <h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 697 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 698 | <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or |
| 699 | <tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for |
Sebastian Redl | f6c0977 | 2010-08-31 23:28:47 +0000 | [diff] [blame] | 700 | deleted function definitions (with <tt>= delete</tt>) is enabled.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 701 | |
Benjamin Kramer | 665a8dc | 2012-01-15 15:26:07 +0000 | [diff] [blame] | 702 | <h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 703 | <p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p> |
| 704 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 705 | <h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4> |
Sean Hunt | e1f6dea | 2011-08-07 00:34:32 +0000 | [diff] [blame] | 706 | |
| 707 | <p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if |
| 708 | support for generalized initializers (using braced lists and |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 709 | <tt>std::initializer_list</tt>) is enabled. Clang does not currently implement |
| 710 | this feature.</p> |
| 711 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 712 | <h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 713 | |
Sebastian Redl | 72a81d2 | 2011-10-10 18:10:00 +0000 | [diff] [blame] | 714 | <p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will |
| 715 | implicitly generate move constructors and move assignment operators where needed.</p> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 716 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 717 | <h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 718 | |
| 719 | <p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p> |
| 720 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 721 | <h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 722 | |
| 723 | <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or |
| 724 | <tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for |
| 725 | inline namespaces is enabled.</p> |
Sean Hunt | e1f6dea | 2011-08-07 00:34:32 +0000 | [diff] [blame] | 726 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 727 | <h4 id="cxx_lambdas">C++11 lambdas</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 728 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 729 | <p>Use <tt>__has_feature(cxx_lambdas)</tt> or |
| 730 | <tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 731 | is enabled. Clang does not currently implement this feature.</p> |
| 732 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 733 | <h4 id="cxx_noexcept">C++11 noexcept</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 734 | |
| 735 | <p>Use <tt>__has_feature(cxx_noexcept)</tt> or |
| 736 | <tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept |
| 737 | exception specifications is enabled.</p> |
| 738 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 739 | <h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 740 | |
| 741 | <p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 742 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 743 | <h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 744 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 745 | <p>Use <tt>__has_feature(cxx_nullptr)</tt> or |
| 746 | <tt>__has_extension(cxx_nullptr)</tt> to determine if support for |
Douglas Gregor | 84ee2ee | 2011-05-21 23:15:46 +0000 | [diff] [blame] | 747 | <tt>nullptr</tt> is enabled.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 748 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 749 | <h4 id="cxx_override_control">C++11 <tt>override control</tt></h4> |
Anders Carlsson | c8b9f79 | 2011-03-25 15:04:23 +0000 | [diff] [blame] | 750 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 751 | <p>Use <tt>__has_feature(cxx_override_control)</tt> or |
| 752 | <tt>__has_extension(cxx_override_control)</tt> to determine if support for |
Anders Carlsson | c8b9f79 | 2011-03-25 15:04:23 +0000 | [diff] [blame] | 753 | the override control keywords is enabled.</p> |
| 754 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 755 | <h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 756 | <p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or |
| 757 | <tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine |
| 758 | if support for reference-qualified functions (e.g., member functions with |
| 759 | <code>&</code> or <code>&&</code> applied to <code>*this</code>) |
| 760 | is enabled.</p> |
Douglas Gregor | 56209ff | 2011-01-26 21:25:54 +0000 | [diff] [blame] | 761 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 762 | <h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4> |
Richard Smith | a391a46 | 2011-04-15 15:14:40 +0000 | [diff] [blame] | 763 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 764 | <p>Use <tt>__has_feature(cxx_range_for)</tt> or |
| 765 | <tt>__has_extension(cxx_range_for)</tt> to determine if support for the |
| 766 | range-based for loop is enabled. </p> |
Richard Smith | a391a46 | 2011-04-15 15:14:40 +0000 | [diff] [blame] | 767 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 768 | <h4 id="cxx_raw_string_literals">C++11 raw string literals</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 769 | <p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support for raw string literals (e.g., <tt>R"foo\bar"</tt>) is enabled.</p> |
| 770 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 771 | <h4 id="cxx_rvalue_references">C++11 rvalue references</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 772 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 773 | <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or |
| 774 | <tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for |
Douglas Gregor | 56209ff | 2011-01-26 21:25:54 +0000 | [diff] [blame] | 775 | rvalue references is enabled. </p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 776 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 777 | <h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 778 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 779 | <p>Use <tt>__has_feature(cxx_static_assert)</tt> or |
| 780 | <tt>__has_extension(cxx_static_assert)</tt> to determine if support for |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 781 | compile-time assertions using <tt>static_assert</tt> is enabled.</p> |
| 782 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 783 | <h4 id="cxx_auto_type">C++11 type inference</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 784 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 785 | <p>Use <tt>__has_feature(cxx_auto_type)</tt> or |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 786 | <tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 787 | supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt> |
| 788 | will instead be a storage class specifier, as in C or C++98.</p> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 789 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 790 | <h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4> |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 791 | |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 792 | <p>Use <tt>__has_feature(cxx_strong_enums)</tt> or |
| 793 | <tt>__has_extension(cxx_strong_enums)</tt> to determine if support for |
| 794 | strongly typed, scoped enumerations is enabled.</p> |
Sebastian Redl | f6c0977 | 2010-08-31 23:28:47 +0000 | [diff] [blame] | 795 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 796 | <h4 id="cxx_trailing_return">C++11 trailing return type</h4> |
Douglas Gregor | dab60ad | 2010-10-01 18:44:50 +0000 | [diff] [blame] | 797 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 798 | <p>Use <tt>__has_feature(cxx_trailing_return)</tt> or |
| 799 | <tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the |
| 800 | alternate function declaration syntax with trailing return type is enabled.</p> |
Douglas Gregor | dab60ad | 2010-10-01 18:44:50 +0000 | [diff] [blame] | 801 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 802 | <h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 803 | <p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if |
| 804 | support for Unicode string literals is enabled.</p> |
Sebastian Redl | 4561ecd | 2011-03-15 21:17:12 +0000 | [diff] [blame] | 805 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 806 | <h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4> |
Sebastian Redl | 4561ecd | 2011-03-15 21:17:12 +0000 | [diff] [blame] | 807 | |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 808 | <p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.</p> |
Douglas Gregor | 1274ccd | 2010-10-08 23:50:27 +0000 | [diff] [blame] | 809 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 810 | <h4 id="cxx_user_literals">C++11 user-defined literals</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 811 | |
| 812 | <p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled. Clang does not currently support this feature.</p> |
| 813 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 814 | <h4 id="cxx_variadic_templates">C++11 variadic templates</h4> |
Douglas Gregor | ece3894 | 2011-08-29 17:28:38 +0000 | [diff] [blame] | 815 | |
| 816 | <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or |
| 817 | <tt>__has_extension(cxx_variadic_templates)</tt> to determine if support |
| 818 | for variadic templates is enabled.</p> |
Douglas Gregor | 1274ccd | 2010-10-08 23:50:27 +0000 | [diff] [blame] | 819 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 820 | <h3 id="c11">C11</h3> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 821 | |
| 822 | <p>The features listed below are slated for inclusion in the upcoming |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 823 | C11 standard. As a result, all these features are enabled |
| 824 | with the <tt>-std=c11</tt> option when compiling C code.</p> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 825 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 826 | <h4 id="c_alignas">C11 alignment specifiers</h4> |
Peter Collingbourne | fd5f686 | 2011-10-14 23:44:46 +0000 | [diff] [blame] | 827 | |
| 828 | <p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt> |
| 829 | to determine if support for alignment specifiers using <tt>_Alignas</tt> |
| 830 | is enabled.</p> |
| 831 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 832 | <h4 id="c_generic_selections">C11 generic selections</h4> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 833 | |
| 834 | <p>Use <tt>__has_feature(c_generic_selections)</tt> or |
| 835 | <tt>__has_extension(c_generic_selections)</tt> to determine if support for |
| 836 | generic selections is enabled.</p> |
| 837 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 838 | <p>As an extension, the C11 generic selection expression is available in all |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 839 | languages supported by Clang. The syntax is the same as that given in the |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 840 | C11 standard.</p> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 841 | |
| 842 | <p>In C, type compatibility is decided according to the rules given in the |
| 843 | appropriate standard, but in C++, which lacks the type compatibility rules |
| 844 | used in C, types are considered compatible only if they are equivalent.</p> |
| 845 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 846 | <h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 847 | |
| 848 | <p>Use <tt>__has_feature(c_static_assert)</tt> or |
| 849 | <tt>__has_extension(c_static_assert)</tt> to determine if support for |
| 850 | compile-time assertions using <tt>_Static_assert</tt> is enabled.</p> |
| 851 | |
Sean Hunt | 4ef4c6b | 2010-01-13 08:31:49 +0000 | [diff] [blame] | 852 | <!-- ======================================================================= --> |
Douglas Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 853 | <h2 id="checking_type_traits">Checks for Type Traits</h2> |
| 854 | <!-- ======================================================================= --> |
| 855 | |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 856 | <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 Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 857 | <blockquote> |
| 858 | <pre> |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 859 | #if __has_extension(is_convertible_to) |
Douglas Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 860 | template<typename From, typename To> |
| 861 | struct is_convertible_to { |
| 862 | static const bool value = __is_convertible_to(From, To); |
| 863 | }; |
| 864 | #else |
| 865 | // Emulate type trait |
| 866 | #endif |
| 867 | </pre> |
| 868 | </blockquote> |
| 869 | |
| 870 | <p>The following type traits are supported by Clang:</p> |
| 871 | <ul> |
| 872 | <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li> |
| 873 | <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li> |
| 874 | <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li> |
| 875 | <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li> |
| 876 | <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li> |
| 877 | <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li> |
| 878 | <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li> |
| 879 | <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li> |
| 880 | <li><code>__is_abstract</code> (GNU, Microsoft)</li> |
| 881 | <li><code>__is_base_of</code> (GNU, Microsoft)</li> |
| 882 | <li><code>__is_class</code> (GNU, Microsoft)</li> |
| 883 | <li><code>__is_convertible_to</code> (Microsoft)</li> |
| 884 | <li><code>__is_empty</code> (GNU, Microsoft)</li> |
| 885 | <li><code>__is_enum</code> (GNU, Microsoft)</li> |
| 886 | <li><code>__is_pod</code> (GNU, Microsoft)</li> |
| 887 | <li><code>__is_polymorphic</code> (GNU, Microsoft)</li> |
| 888 | <li><code>__is_union</code> (GNU, Microsoft)</li> |
| 889 | <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li> |
Douglas Gregor | 5e9392b | 2011-12-03 18:14:24 +0000 | [diff] [blame] | 890 | <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li> |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 891 | <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li> |
Douglas Gregor | afdf137 | 2011-02-03 21:57:35 +0000 | [diff] [blame] | 892 | </ul> |
| 893 | |
| 894 | <!-- ======================================================================= --> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 895 | <h2 id="blocks">Blocks</h2> |
| 896 | <!-- ======================================================================= --> |
| 897 | |
Chris Lattner | a7dbdf5 | 2009-03-09 07:03:22 +0000 | [diff] [blame] | 898 | <p>The syntax and high level language feature description is in <a |
| 899 | href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI |
| 900 | details for the clang implementation are in <a |
Chris Lattner | 5d7650b | 2010-03-16 21:43:03 +0000 | [diff] [blame] | 901 | href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 902 | |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 903 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 904 | <p>Query for this feature with __has_extension(blocks).</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 905 | |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 906 | <!-- ======================================================================= --> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 907 | <h2 id="objc_features">Objective-C Features</h2> |
| 908 | <!-- ======================================================================= --> |
| 909 | |
| 910 | <h3 id="objc_instancetype">Related result types</h3> |
| 911 | |
| 912 | <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> |
| 913 | |
| 914 | <blockquote> |
| 915 | <pre> |
| 916 | @interface NSObject |
| 917 | + (id)alloc; |
| 918 | - (id)init; |
| 919 | @end |
| 920 | |
| 921 | @interface NSArray : NSObject |
| 922 | @end |
| 923 | </pre> |
| 924 | </blockquote> |
| 925 | |
| 926 | <p>and this common initialization pattern</p> |
| 927 | |
| 928 | <blockquote> |
| 929 | <pre> |
| 930 | NSArray *array = [[NSArray alloc] init]; |
| 931 | </pre> |
| 932 | </blockquote> |
| 933 | |
| 934 | <p>the type of the expression <code>[NSArray alloc]</code> is |
| 935 | <code>NSArray*</code> because <code>alloc</code> implicitly has a |
| 936 | related result type. Similarly, the type of the expression |
| 937 | <code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since |
| 938 | <code>init</code> has a related result type and its receiver is known |
| 939 | to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p> |
| 940 | |
Douglas Gregor | e97179c | 2011-09-08 01:46:34 +0000 | [diff] [blame] | 941 | <p>A method with a related result type can be declared by using the |
| 942 | type <tt>instancetype</tt> as its result type. <tt>instancetype</tt> |
| 943 | is a contextual keyword that is only permitted in the result type of |
| 944 | an Objective-C method, e.g.</p> |
| 945 | |
| 946 | <pre> |
| 947 | @interface A |
| 948 | + (<b>instancetype</b>)constructAnA; |
| 949 | @end |
| 950 | </pre> |
| 951 | |
| 952 | <p>The related result type can also be inferred for some methods. |
| 953 | To determine whether a method has an inferred related result type, the first |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 954 | word in the camel-case selector (e.g., "init" in "initWithObjects") is |
Douglas Gregor | 8a0ace6 | 2011-11-03 18:33:01 +0000 | [diff] [blame] | 955 | considered, and the method will have a related result type if its return |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 956 | type is compatible with the type of its class and if</p> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 957 | |
| 958 | <ul> |
| 959 | |
| 960 | <li>the first word is "alloc" or "new", and the method is a class |
| 961 | method, or</li> |
| 962 | |
| 963 | <li>the first word is "autorelease", "init", "retain", or "self", |
| 964 | and the method is an instance method.</li> |
| 965 | |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 966 | </ul> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 967 | |
| 968 | <p>If a method with a related result type is overridden by a subclass |
| 969 | method, the subclass method must also return a type that is compatible |
| 970 | with the subclass type. For example:</p> |
| 971 | |
| 972 | <blockquote> |
| 973 | <pre> |
| 974 | @interface NSString : NSObject |
| 975 | - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString |
| 976 | @end |
| 977 | </pre> |
| 978 | </blockquote> |
| 979 | |
| 980 | <p>Related result types only affect the type of a message send or |
| 981 | property access via the given method. In all other respects, a method |
Douglas Gregor | e97179c | 2011-09-08 01:46:34 +0000 | [diff] [blame] | 982 | with a related result type is treated the same way as method that |
| 983 | returns <tt>id</tt>.</p> |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 984 | |
Douglas Gregor | aebb653 | 2011-09-08 17:19:31 +0000 | [diff] [blame] | 985 | <p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether |
| 986 | the <tt>instancetype</tt> contextual keyword is available.</p> |
| 987 | |
Douglas Gregor | 926df6c | 2011-06-11 01:09:30 +0000 | [diff] [blame] | 988 | <!-- ======================================================================= --> |
John McCall | f85e193 | 2011-06-15 23:02:42 +0000 | [diff] [blame] | 989 | <h2 id="objc_arc">Automatic reference counting </h2> |
| 990 | <!-- ======================================================================= --> |
| 991 | |
| 992 | <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> |
| 993 | |
| 994 | <!-- ======================================================================= --> |
Douglas Gregor | 5471bc8 | 2011-09-08 17:18:35 +0000 | [diff] [blame] | 995 | <h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2> |
| 996 | <!-- ======================================================================= --> |
| 997 | |
David Blaikie | 5090e9f | 2011-10-18 05:49:30 +0000 | [diff] [blame] | 998 | <p>Clang provides support for C++11 enumerations with a fixed |
Douglas Gregor | 5471bc8 | 2011-09-08 17:18:35 +0000 | [diff] [blame] | 999 | underlying type within Objective-C. For example, one can write an |
| 1000 | enumeration type as:</p> |
| 1001 | |
| 1002 | <pre> |
| 1003 | typedef enum : unsigned char { Red, Green, Blue } Color; |
| 1004 | </pre> |
| 1005 | |
| 1006 | <p>This specifies that the underlying type, which is used to store the |
| 1007 | enumeration value, is <tt>unsigned char</tt>.</p> |
| 1008 | |
| 1009 | <p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether |
| 1010 | support for fixed underlying types is available in Objective-C.</p> |
| 1011 | |
| 1012 | <!-- ======================================================================= --> |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1013 | <h2 id="overloading-in-c">Function Overloading in C</h2> |
| 1014 | <!-- ======================================================================= --> |
| 1015 | |
Chris Lattner | f161d41 | 2009-02-13 21:51:45 +0000 | [diff] [blame] | 1016 | <p>Clang provides support for C++ function overloading in C. Function |
| 1017 | overloading in C is introduced using the <tt>overloadable</tt> attribute. For |
| 1018 | example, one might provide several overloaded versions of a <tt>tgsin</tt> |
| 1019 | function that invokes the appropriate standard function computing the sine of a |
| 1020 | value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> |
| 1021 | precision:</p> |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1022 | |
| 1023 | <blockquote> |
| 1024 | <pre> |
| 1025 | #include <math.h> |
| 1026 | float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); } |
| 1027 | double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); } |
| 1028 | long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); } |
| 1029 | </pre> |
| 1030 | </blockquote> |
| 1031 | |
| 1032 | <p>Given these declarations, one can call <tt>tgsin</tt> with a |
| 1033 | <tt>float</tt> value to receive a <tt>float</tt> result, with a |
| 1034 | <tt>double</tt> to receive a <tt>double</tt> result, etc. Function |
| 1035 | overloading in C follows the rules of C++ function overloading to pick |
| 1036 | the best overload given the call arguments, with a few C-specific |
| 1037 | semantics:</p> |
| 1038 | <ul> |
| 1039 | <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long |
| 1040 | double</tt> is ranked as a floating-point promotion (per C99) rather |
| 1041 | than as a floating-point conversion (as in C++).</li> |
| 1042 | |
| 1043 | <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type |
| 1044 | <tt>U*</tt> is considered a pointer conversion (with conversion |
| 1045 | rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li> |
| 1046 | |
| 1047 | <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt> |
| 1048 | is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This |
| 1049 | conversion is given "conversion" rank.</li> |
| 1050 | </ul> |
| 1051 | |
| 1052 | <p>The declaration of <tt>overloadable</tt> functions is restricted to |
| 1053 | function declarations and definitions. Most importantly, if any |
| 1054 | function with a given name is given the <tt>overloadable</tt> |
| 1055 | attribute, then all function declarations and definitions with that |
| 1056 | name (and in that scope) must have the <tt>overloadable</tt> |
Chris Lattner | f161d41 | 2009-02-13 21:51:45 +0000 | [diff] [blame] | 1057 | attribute. This rule even applies to redeclarations of functions whose original |
| 1058 | declaration had the <tt>overloadable</tt> attribute, e.g.,</p> |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1059 | |
| 1060 | <blockquote> |
| 1061 | <pre> |
| 1062 | int f(int) __attribute__((overloadable)); |
| 1063 | float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i> |
| 1064 | |
| 1065 | int g(int) __attribute__((overloadable)); |
| 1066 | int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i> |
| 1067 | </pre> |
| 1068 | </blockquote> |
| 1069 | |
Douglas Gregor | 965acbb | 2009-02-18 07:07:28 +0000 | [diff] [blame] | 1070 | <p>Functions marked <tt>overloadable</tt> must have |
| 1071 | prototypes. Therefore, the following code is ill-formed:</p> |
| 1072 | |
| 1073 | <blockquote> |
| 1074 | <pre> |
| 1075 | int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i> |
| 1076 | </pre> |
| 1077 | </blockquote> |
| 1078 | |
| 1079 | <p>However, <tt>overloadable</tt> functions are allowed to use a |
| 1080 | ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p> |
| 1081 | |
| 1082 | <blockquote> |
| 1083 | <pre> |
Chris Lattner | 0224680 | 2009-02-18 22:27:46 +0000 | [diff] [blame] | 1084 | void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i> |
Douglas Gregor | 965acbb | 2009-02-18 07:07:28 +0000 | [diff] [blame] | 1085 | </pre> |
| 1086 | </blockquote> |
| 1087 | |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1088 | <p>Functions declared with the <tt>overloadable</tt> attribute have |
| 1089 | their names mangled according to the same rules as C++ function |
| 1090 | names. For example, the three <tt>tgsin</tt> functions in our |
| 1091 | motivating example get the mangled names <tt>_Z5tgsinf</tt>, |
Chris Lattner | 71b48d6 | 2010-11-28 18:19:13 +0000 | [diff] [blame] | 1092 | <tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1093 | caveats to this use of name mangling:</p> |
| 1094 | |
| 1095 | <ul> |
| 1096 | |
| 1097 | <li>Future versions of Clang may change the name mangling of |
| 1098 | functions overloaded in C, so you should not depend on an specific |
| 1099 | mangling. To be completely safe, we strongly urge the use of |
| 1100 | <tt>static inline</tt> with <tt>overloadable</tt> functions.</li> |
| 1101 | |
| 1102 | <li>The <tt>overloadable</tt> attribute has almost no meaning when |
| 1103 | used in C++, because names will already be mangled and functions are |
| 1104 | already overloadable. However, when an <tt>overloadable</tt> |
| 1105 | function occurs within an <tt>extern "C"</tt> linkage specification, |
| 1106 | it's name <i>will</i> be mangled in the same way as it would in |
| 1107 | C.</li> |
| 1108 | </ul> |
| 1109 | |
Peter Collingbourne | c1b5fa4 | 2011-05-13 20:54:45 +0000 | [diff] [blame] | 1110 | <p>Query for this feature with __has_extension(attribute_overloadable).</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 1111 | |
Eli Friedman | 0c706c2 | 2011-09-19 23:17:44 +0000 | [diff] [blame] | 1112 | <!-- ======================================================================= --> |
| 1113 | <h2 id="complex-list-init">Initializer lists for complex numbers in C</h2> |
| 1114 | <!-- ======================================================================= --> |
| 1115 | |
| 1116 | <p>clang supports an extension which allows the following in C:</p> |
| 1117 | |
| 1118 | <blockquote> |
| 1119 | <pre> |
| 1120 | #include <math.h> |
| 1121 | #include <complex.h> |
| 1122 | complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) |
| 1123 | </pre> |
| 1124 | </blockquote> |
| 1125 | |
| 1126 | <p>This construct is useful because there is no way to separately |
| 1127 | initialize the real and imaginary parts of a complex variable in |
| 1128 | standard C, given that clang does not support <code>_Imaginary</code>. |
| 1129 | (clang also supports the <code>__real__</code> and <code>__imag__</code> |
| 1130 | extensions from gcc, which help in some cases, but are not usable in |
| 1131 | static initializers.) |
| 1132 | |
| 1133 | <p>Note that this extension does not allow eliding the braces; the |
| 1134 | meaning of the following two lines is different:</p> |
| 1135 | |
| 1136 | <blockquote> |
| 1137 | <pre> |
| 1138 | complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) |
| 1139 | complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) |
| 1140 | </pre> |
| 1141 | </blockquote> |
| 1142 | |
| 1143 | <p>This extension also works in C++ mode, as far as that goes, but does not |
| 1144 | apply to the C++ <code>std::complex</code>. (In C++11, list |
| 1145 | initialization allows the same syntax to be used with |
| 1146 | <code>std::complex</code> with the same meaning.) |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 1147 | |
Douglas Gregor | cb54d43 | 2009-02-13 00:57:04 +0000 | [diff] [blame] | 1148 | <!-- ======================================================================= --> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1149 | <h2 id="builtins">Builtin Functions</h2> |
| 1150 | <!-- ======================================================================= --> |
| 1151 | |
| 1152 | <p>Clang supports a number of builtin library functions with the same syntax as |
| 1153 | GCC, including things like <tt>__builtin_nan</tt>, |
| 1154 | <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>, |
| 1155 | <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In |
| 1156 | addition to the GCC builtins, Clang supports a number of builtins that GCC does |
| 1157 | not, which are listed here.</p> |
| 1158 | |
| 1159 | <p>Please note that Clang does not and will not support all of the GCC builtins |
| 1160 | for vector operations. Instead of using builtins, you should use the functions |
| 1161 | defined in target-specific header files like <tt><xmmintrin.h></tt>, which |
| 1162 | define portable wrappers for these. Many of the Clang versions of these |
| 1163 | functions are implemented directly in terms of <a href="#vectors">extended |
| 1164 | vector support</a> instead of builtins, in order to reduce the number of |
| 1165 | builtins that we need to implement.</p> |
| 1166 | |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1167 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 1168 | <h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1169 | <!-- ======================================================================= --> |
| 1170 | |
Chris Lattner | aad826b | 2009-09-16 18:56:12 +0000 | [diff] [blame] | 1171 | <p><tt>__builtin_shufflevector</tt> is used to express generic vector |
Chris Lattner | 6f72da5 | 2009-02-13 20:00:20 +0000 | [diff] [blame] | 1172 | permutation/shuffle/swizzle operations. This builtin is also very important for |
| 1173 | the implementation of various target-specific header files like |
| 1174 | <tt><xmmintrin.h></tt>. |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1175 | </p> |
| 1176 | |
| 1177 | <p><b>Syntax:</b></p> |
| 1178 | |
| 1179 | <pre> |
Chris Lattner | 6f72da5 | 2009-02-13 20:00:20 +0000 | [diff] [blame] | 1180 | __builtin_shufflevector(vec1, vec2, index1, index2, ...) |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1181 | </pre> |
| 1182 | |
| 1183 | <p><b>Examples:</b></p> |
| 1184 | |
| 1185 | <pre> |
Chris Lattner | 6f72da5 | 2009-02-13 20:00:20 +0000 | [diff] [blame] | 1186 | // Identity operation - return 4-element vector V1. |
| 1187 | __builtin_shufflevector(V1, V1, 0, 1, 2, 3) |
| 1188 | |
| 1189 | // "Splat" element 0 of V1 into a 4-element result. |
| 1190 | __builtin_shufflevector(V1, V1, 0, 0, 0, 0) |
| 1191 | |
| 1192 | // Reverse 4-element vector V1. |
| 1193 | __builtin_shufflevector(V1, V1, 3, 2, 1, 0) |
| 1194 | |
| 1195 | // Concatenate every other element of 4-element vectors V1 and V2. |
| 1196 | __builtin_shufflevector(V1, V2, 0, 2, 4, 6) |
| 1197 | |
| 1198 | // Concatenate every other element of 8-element vectors V1 and V2. |
| 1199 | __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1200 | </pre> |
| 1201 | |
| 1202 | <p><b>Description:</b></p> |
| 1203 | |
Chris Lattner | 6f72da5 | 2009-02-13 20:00:20 +0000 | [diff] [blame] | 1204 | <p>The first two arguments to __builtin_shufflevector are vectors that have the |
| 1205 | same element type. The remaining arguments are a list of integers that specify |
| 1206 | the elements indices of the first two vectors that should be extracted and |
| 1207 | returned in a new vector. These element indices are numbered sequentially |
| 1208 | starting with the first vector, continuing into the second vector. Thus, if |
| 1209 | vec1 is a 4-element vector, index 5 would refer to the second element of vec2. |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1210 | </p> |
| 1211 | |
Chris Lattner | 6f72da5 | 2009-02-13 20:00:20 +0000 | [diff] [blame] | 1212 | <p>The result of __builtin_shufflevector is a vector |
| 1213 | with the same element type as vec1/vec2 but that has an element count equal to |
| 1214 | the number of indices specified. |
| 1215 | </p> |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1216 | |
Chris Lattner | 21190d5 | 2009-09-21 03:09:59 +0000 | [diff] [blame] | 1217 | <p>Query for this feature with __has_builtin(__builtin_shufflevector).</p> |
| 1218 | |
| 1219 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 1220 | <h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3> |
Chris Lattner | 21190d5 | 2009-09-21 03:09:59 +0000 | [diff] [blame] | 1221 | <!-- ======================================================================= --> |
| 1222 | |
| 1223 | <p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in |
| 1224 | the program cannot be reached, even if the compiler might otherwise think it |
| 1225 | can. This is useful to improve optimization and eliminates certain warnings. |
| 1226 | For example, without the <tt>__builtin_unreachable</tt> in the example below, |
| 1227 | the compiler assumes that the inline asm can fall through and prints a "function |
| 1228 | declared 'noreturn' should not return" warning. |
| 1229 | </p> |
| 1230 | |
| 1231 | <p><b>Syntax:</b></p> |
| 1232 | |
| 1233 | <pre> |
| 1234 | __builtin_unreachable() |
| 1235 | </pre> |
| 1236 | |
| 1237 | <p><b>Example of Use:</b></p> |
| 1238 | |
| 1239 | <pre> |
| 1240 | void myabort(void) __attribute__((noreturn)); |
| 1241 | void myabort(void) { |
| 1242 | asm("int3"); |
| 1243 | __builtin_unreachable(); |
| 1244 | } |
| 1245 | </pre> |
| 1246 | |
| 1247 | <p><b>Description:</b></p> |
| 1248 | |
| 1249 | <p>The __builtin_unreachable() builtin has completely undefined behavior. Since |
| 1250 | it has undefined behavior, it is a statement that it is never reached and the |
| 1251 | optimizer can take advantage of this to produce better code. This builtin takes |
| 1252 | no arguments and produces a void result. |
| 1253 | </p> |
| 1254 | |
| 1255 | <p>Query for this feature with __has_builtin(__builtin_unreachable).</p> |
| 1256 | |
Chris Lattner | 23aa9c8 | 2011-04-09 03:57:26 +0000 | [diff] [blame] | 1257 | <!-- ======================================================================= --> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 1258 | <h3><a name="__sync_swap">__sync_swap</a></h3> |
Chris Lattner | 23aa9c8 | 2011-04-09 03:57:26 +0000 | [diff] [blame] | 1259 | <!-- ======================================================================= --> |
| 1260 | |
| 1261 | <p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in |
| 1262 | memory. |
| 1263 | </p> |
| 1264 | |
| 1265 | <p><b>Syntax:</b></p> |
| 1266 | |
| 1267 | <pre> |
| 1268 | <i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...) |
| 1269 | </pre> |
| 1270 | |
| 1271 | <p><b>Example of Use:</b></p> |
| 1272 | |
| 1273 | <pre> |
Sean Hunt | 7e98b47 | 2011-06-23 01:21:01 +0000 | [diff] [blame] | 1274 | int old_value = __sync_swap(&value, new_value); |
Chris Lattner | 23aa9c8 | 2011-04-09 03:57:26 +0000 | [diff] [blame] | 1275 | </pre> |
| 1276 | |
| 1277 | <p><b>Description:</b></p> |
| 1278 | |
| 1279 | <p>The __sync_swap() builtin extends the existing __sync_*() family of atomic |
| 1280 | intrinsics to allow code to atomically swap the current value with the new |
| 1281 | value. More importantly, it helps developers write more efficient and correct |
| 1282 | code by avoiding expensive loops around __sync_bool_compare_and_swap() or |
| 1283 | relying on the platform specific implementation details of |
| 1284 | __sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier. |
| 1285 | </p> |
| 1286 | |
Chris Lattner | 21190d5 | 2009-09-21 03:09:59 +0000 | [diff] [blame] | 1287 | |
Chris Lattner | 1177f91 | 2009-04-09 19:58:15 +0000 | [diff] [blame] | 1288 | <!-- ======================================================================= --> |
| 1289 | <h2 id="targetspecific">Target-Specific Extensions</h2> |
| 1290 | <!-- ======================================================================= --> |
| 1291 | |
| 1292 | <p>Clang supports some language features conditionally on some targets.</p> |
| 1293 | |
| 1294 | <!-- ======================================================================= --> |
| 1295 | <h3 id="x86-specific">X86/X86-64 Language Extensions</h3> |
| 1296 | <!-- ======================================================================= --> |
| 1297 | |
| 1298 | <p>The X86 backend has these language extensions:</p> |
| 1299 | |
| 1300 | <!-- ======================================================================= --> |
| 1301 | <h4 id="x86-gs-segment">Memory references off the GS segment</h4> |
| 1302 | <!-- ======================================================================= --> |
| 1303 | |
| 1304 | <p>Annotating a pointer with address space #256 causes it to be code generated |
Chris Lattner | a021e7c | 2009-05-05 18:54:47 +0000 | [diff] [blame] | 1305 | relative to the X86 GS segment register, and address space #257 causes it to be |
| 1306 | relative to the X86 FS segment. Note that this is a very very low-level |
| 1307 | feature that should only be used if you know what you're doing (for example in |
| 1308 | an OS kernel).</p> |
Chris Lattner | 1177f91 | 2009-04-09 19:58:15 +0000 | [diff] [blame] | 1309 | |
| 1310 | <p>Here is an example:</p> |
| 1311 | |
| 1312 | <pre> |
| 1313 | #define GS_RELATIVE __attribute__((address_space(256))) |
| 1314 | int foo(int GS_RELATIVE *P) { |
| 1315 | return *P; |
| 1316 | } |
| 1317 | </pre> |
| 1318 | |
| 1319 | <p>Which compiles to (on X86-32):</p> |
| 1320 | |
| 1321 | <pre> |
| 1322 | _foo: |
| 1323 | movl 4(%esp), %eax |
| 1324 | movl %gs:(%eax), %eax |
| 1325 | ret |
| 1326 | </pre> |
| 1327 | |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1328 | <!-- ======================================================================= --> |
| 1329 | <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2> |
| 1330 | <!-- ======================================================================= --> |
| 1331 | |
| 1332 | <p>Clang supports additional attributes that are useful for documenting program |
| 1333 | invariants and rules for static analysis tools. The extensions documented here |
| 1334 | are used by the <a |
| 1335 | href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer |
| 1336 | engine</a> that is part of Clang's Analysis library.</p> |
| 1337 | |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 1338 | <h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3> |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1339 | |
| 1340 | <p>Clang's static analysis engine understands the standard <tt>noreturn</tt> |
Ted Kremenek | 4df2114 | 2009-04-10 05:04:22 +0000 | [diff] [blame] | 1341 | attribute. This attribute, which is typically affixed to a function prototype, |
| 1342 | indicates that a call to a given function never returns. Function prototypes for |
| 1343 | common functions like <tt>exit</tt> are typically annotated with this attribute, |
| 1344 | as well as a variety of common assertion handlers. Users can educate the static |
| 1345 | analyzer about their own custom assertion handles (thus cutting down on false |
| 1346 | positives due to false paths) by marking their own "panic" functions |
| 1347 | with this attribute.</p> |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1348 | |
| 1349 | <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes |
Nick Lewycky | 625b586 | 2009-06-14 04:08:08 +0000 | [diff] [blame] | 1350 | there are special functions that for all intents and purposes should be |
| 1351 | considered panic functions (i.e., they are only called when an internal program |
| 1352 | error occurs) but may actually return so that the program can fail gracefully. |
| 1353 | The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions |
| 1354 | as being interpreted as "no return" functions by the analyzer (thus |
Chris Lattner | 2893589 | 2009-04-10 05:54:56 +0000 | [diff] [blame] | 1355 | pruning bogus paths) but will not affect compilation (as in the case of |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1356 | <tt>noreturn</tt>).</p> |
| 1357 | |
| 1358 | <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the |
Chris Lattner | 2893589 | 2009-04-10 05:54:56 +0000 | [diff] [blame] | 1359 | same places where the <tt>noreturn</tt> attribute can be placed. It is commonly |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1360 | placed at the end of function prototypes:</p> |
| 1361 | |
| 1362 | <pre> |
| 1363 | void foo() <b>__attribute__((analyzer_noreturn))</b>; |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 1364 | </pre> |
| 1365 | |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 1366 | <p>Query for this feature with |
| 1367 | <tt>__has_attribute(analyzer_noreturn)</tt>.</p> |
Chris Lattner | 148772a | 2009-06-13 07:13:28 +0000 | [diff] [blame] | 1368 | |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 1369 | <h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3> |
| 1370 | |
| 1371 | <p>Many methods in Objective-C have conventional meanings determined |
| 1372 | by their selectors. For the purposes of static analysis, it is |
| 1373 | sometimes useful to be able to mark a method as having a particular |
| 1374 | conventional meaning despite not having the right selector, or as not |
| 1375 | having the conventional meaning that its selector would suggest. |
| 1376 | For these use cases, we provide an attribute to specifically describe |
| 1377 | the <q>method family</q> that a method belongs to.</p> |
| 1378 | |
| 1379 | <p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>, |
| 1380 | where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>, |
| 1381 | <tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute |
| 1382 | can only be placed at the end of a method declaration:</p> |
| 1383 | |
| 1384 | <pre> |
| 1385 | - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>; |
| 1386 | </pre> |
| 1387 | |
| 1388 | <p>Users who do not wish to change the conventional meaning of a |
| 1389 | method, and who merely want to document its non-standard retain and |
| 1390 | release semantics, should use the |
| 1391 | <a href="#attr_retain_release">retaining behavior attributes</a> |
| 1392 | described below.</p> |
| 1393 | |
| 1394 | <p>Query for this feature with |
| 1395 | <tt>__has_attribute(objc_method_family)</tt>.</p> |
| 1396 | |
| 1397 | <h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3> |
John McCall | 630b7ae | 2011-01-25 04:26:21 +0000 | [diff] [blame] | 1398 | |
| 1399 | <p>In Objective-C, functions and methods are generally assumed to take |
| 1400 | and return objects with +0 retain counts, with some exceptions for |
| 1401 | special methods like <tt>+alloc</tt> and <tt>init</tt>. However, |
| 1402 | there are exceptions, and so Clang provides attributes to allow these |
| 1403 | exceptions to be documented, which helps the analyzer find leaks (and |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 1404 | ignore non-leaks). Some exceptions may be better described using |
| 1405 | the <a href="#attr_method_family"><tt>objc_method_family</tt></a> |
| 1406 | attribute instead.</p> |
John McCall | 630b7ae | 2011-01-25 04:26:21 +0000 | [diff] [blame] | 1407 | |
| 1408 | <p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>, |
| 1409 | <tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>, |
| 1410 | and <tt>cf_returns_not_retained</tt> attributes can be placed on |
| 1411 | methods and functions that return Objective-C or CoreFoundation |
| 1412 | objects. They are commonly placed at the end of a function prototype |
| 1413 | or method declaration:</p> |
| 1414 | |
| 1415 | <pre> |
| 1416 | id foo() <b>__attribute__((ns_returns_retained))</b>; |
| 1417 | |
| 1418 | - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>; |
| 1419 | </pre> |
| 1420 | |
| 1421 | <p>The <tt>*_returns_retained</tt> attributes specify that the |
| 1422 | returned object has a +1 retain count. |
| 1423 | The <tt>*_returns_not_retained</tt> attributes specify that the return |
| 1424 | object has a +0 retain count, even if the normal convention for its |
| 1425 | selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the |
| 1426 | returned object is +0, but is guaranteed to live at least as long as the |
| 1427 | next flush of an autorelease pool.</p> |
| 1428 | |
| 1429 | <p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt> |
| 1430 | attributes can be placed on an parameter declaration; they specify |
| 1431 | that the argument is expected to have a +1 retain count, which will be |
| 1432 | balanced in some way by the function or method. |
| 1433 | The <tt>ns_consumes_self</tt> attribute can only be placed on an |
| 1434 | Objective-C method; it specifies that the method expects |
| 1435 | its <tt>self</tt> parameter to have a +1 retain count, which it will |
| 1436 | balance in some way.</p> |
| 1437 | |
| 1438 | <pre> |
| 1439 | void <b>foo(__attribute__((ns_consumed))</b> NSString *string); |
| 1440 | |
| 1441 | - (void) bar <b>__attribute__((ns_consumes_self))</b>; |
| 1442 | - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x; |
| 1443 | </pre> |
Ted Kremenek | ed86931 | 2009-04-10 05:03:33 +0000 | [diff] [blame] | 1444 | |
John McCall | 8749401 | 2011-03-18 03:51:49 +0000 | [diff] [blame] | 1445 | <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>, |
| 1446 | <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p> |
| 1447 | |
Kostya Serebryany | ce98c9b | 2011-11-28 20:51:02 +0000 | [diff] [blame] | 1448 | <!-- ======================================================================= --> |
| 1449 | <h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2> |
| 1450 | <!-- ======================================================================= --> |
| 1451 | <h3 id="address_sanitizer">AddressSanitizer</h3> |
| 1452 | <p> Use <code>__has_feature(address_sanitizer)</code> |
| 1453 | to check if the code is being built with <a |
| 1454 | href="AddressSanitizer.html">AddressSanitizer</a>. |
| 1455 | </p> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1456 | |
| 1457 | <!-- ======================================================================= --> |
Caitlin Sadowski | 73cbbc8 | 2011-07-28 18:38:36 +0000 | [diff] [blame] | 1458 | <h2 id="threadsafety">Thread-Safety Annotation Checking</h2> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1459 | <!-- ======================================================================= --> |
| 1460 | |
| 1461 | <p>Clang supports additional attributes for checking basic locking policies in |
| 1462 | multithreaded programs. |
| 1463 | Clang currently parses the following list of attributes, although |
| 1464 | <b>the implementation for these annotations is currently in development.</b> |
| 1465 | For more details, see the |
| 1466 | <a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>. |
| 1467 | </p> |
| 1468 | |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1469 | <h4 id="ts_noanal">no_thread_safety_analysis</h4> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1470 | |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1471 | <p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function |
| 1472 | declaration to specify that the thread safety analysis should not be run on that |
| 1473 | function. This attribute provides an escape hatch (e.g. for situations when it |
| 1474 | is difficult to annotate the locking policy). </p> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1475 | |
| 1476 | <h4 id="ts_lockable">lockable</h4> |
| 1477 | |
| 1478 | <p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify |
| 1479 | that it has a lockable type (e.g. a Mutex class). This annotation is primarily |
| 1480 | used to check consistency.</p> |
| 1481 | |
| 1482 | <h4 id="ts_scopedlockable">scoped_lockable</h4> |
| 1483 | |
| 1484 | <p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to |
| 1485 | specify that it has a "scoped" lockable type. Objects of this type will acquire |
| 1486 | the lock upon construction and release it upon going out of scope. |
| 1487 | This annotation is primarily used to check |
| 1488 | consistency.</p> |
| 1489 | |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1490 | <h4 id="ts_guardedvar">guarded_var</h4> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1491 | |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1492 | <p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to |
| 1493 | specify that the variable must be accessed while holding some lock.</p> |
| 1494 | |
| 1495 | <h4 id="ts_ptguardedvar">pt_guarded_var</h4> |
| 1496 | |
| 1497 | <p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to |
| 1498 | specify that the pointer must be dereferenced while holding some lock.</p> |
| 1499 | |
| 1500 | <h4 id="ts_guardedby">guarded_by(l)</h4> |
| 1501 | |
| 1502 | <p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1503 | specify that the variable must be accessed while holding lock <tt>l</tt>.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1504 | |
| 1505 | <h4 id="ts_ptguardedby">pt_guarded_by(l)</h4> |
| 1506 | |
| 1507 | <p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1508 | specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1509 | |
| 1510 | <h4 id="ts_acquiredbefore">acquired_before(...)</h4> |
| 1511 | |
| 1512 | <p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration |
| 1513 | of a lockable variable to specify that the lock must be acquired before all |
| 1514 | attribute arguments. Arguments must be lockable type, and there must be at |
| 1515 | least one argument.</p> |
| 1516 | |
| 1517 | <h4 id="ts_acquiredafter">acquired_after(...)</h4> |
| 1518 | |
| 1519 | <p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration |
| 1520 | of a lockable variable to specify that the lock must be acquired after all |
| 1521 | attribute arguments. Arguments must be lockable type, and there must be at |
| 1522 | least one argument.</p> |
| 1523 | |
| 1524 | <h4 id="ts_elf">exclusive_lock_function(...)</h4> |
| 1525 | |
| 1526 | <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function |
| 1527 | declaration to specify that the function acquires all listed locks |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1528 | exclusively. This attribute takes zero or more arguments: either of lockable |
| 1529 | type or integers indexing into function parameters of lockable type. If no |
| 1530 | arguments are given, the acquired lock is implicitly <tt>this</tt> of the |
| 1531 | enclosing object.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1532 | |
| 1533 | <h4 id="ts_slf">shared_lock_function(...)</h4> |
| 1534 | |
| 1535 | <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function |
| 1536 | declaration to specify that the function acquires all listed locks, although |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1537 | the locks may be shared (e.g. read locks). This attribute takes zero or more |
| 1538 | arguments: either of lockable type or integers indexing into function |
| 1539 | parameters of lockable type. If no arguments are given, the acquired lock is |
| 1540 | implicitly <tt>this</tt> of the enclosing object.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1541 | |
| 1542 | <h4 id="ts_etf">exclusive_trylock_function(...)</h4> |
| 1543 | |
| 1544 | <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function |
| 1545 | declaration to specify that the function will try (without blocking) to acquire |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1546 | all listed locks exclusively. This attribute takes one or more arguments. The |
| 1547 | first argument is an integer or boolean value specifying the return value of a |
| 1548 | successful lock acquisition. The remaining arugments are either of lockable type |
| 1549 | or integers indexing into function parameters of lockable type. If only one |
| 1550 | argument is given, the acquired lock is implicitly <tt>this</tt> of the |
| 1551 | enclosing object.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1552 | |
| 1553 | <h4 id="ts_stf">shared_trylock_function(...)</h4> |
| 1554 | |
| 1555 | <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function |
| 1556 | declaration to specify that the function will try (without blocking) to acquire |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1557 | all listed locks, although the locks may be shared (e.g. read locks). This |
| 1558 | attribute takes one or more arguments. The first argument is an integer or |
| 1559 | boolean value specifying the return value of a successful lock acquisition. The |
| 1560 | remaining arugments are either of lockable type or integers indexing into |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1561 | function parameters of lockable type. If only one argument is given, the |
| 1562 | acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> |
| 1563 | |
| 1564 | <h4 id="ts_uf">unlock_function(...)</h4> |
| 1565 | |
| 1566 | <p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1567 | declaration to specify that the function release all listed locks. This |
| 1568 | attribute takes zero or more arguments: either of lockable type or integers |
| 1569 | indexing into function parameters of lockable type. If no arguments are given, |
| 1570 | the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1571 | |
| 1572 | <h4 id="ts_lr">lock_returned(l)</h4> |
| 1573 | |
| 1574 | <p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1575 | declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt> |
| 1576 | must be of lockable type). This annotation is used to aid in resolving lock |
| 1577 | expressions.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1578 | |
| 1579 | <h4 id="ts_le">locks_excluded(...)</h4> |
| 1580 | |
| 1581 | <p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration |
Caitlin Sadowski | b51e031 | 2011-08-09 17:59:31 +0000 | [diff] [blame] | 1582 | to specify that the function must not be called with the listed locks. Arguments |
| 1583 | must be lockable type, and there must be at least one argument.</p> |
Caitlin Sadowski | db33e14 | 2011-07-28 20:12:35 +0000 | [diff] [blame] | 1584 | |
| 1585 | <h4 id="ts_elr">exclusive_locks_required(...)</h4> |
| 1586 | |
| 1587 | <p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function |
| 1588 | declaration to specify that the function must be called while holding the listed |
| 1589 | exclusive locks. Arguments must be lockable type, and there must be at |
| 1590 | least one argument.</p> |
| 1591 | |
| 1592 | <h4 id="ts_slr">shared_locks_required(...)</h4> |
| 1593 | |
| 1594 | <p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function |
| 1595 | declaration to specify that the function must be called while holding the listed |
| 1596 | shared locks. Arguments must be lockable type, and there must be at |
| 1597 | least one argument.</p> |
Caitlin Sadowski | fdde9e7 | 2011-07-28 17:21:07 +0000 | [diff] [blame] | 1598 | |
Chris Lattner | 5ce933f | 2009-02-09 08:46:11 +0000 | [diff] [blame] | 1599 | </div> |
| 1600 | </body> |
| 1601 | </html> |