From 222e2a7620e6520ffaf4fc4e69d79c18da31542e Mon Sep 17 00:00:00 2001 From: "Zancanaro; Carlo" Date: Mon, 24 Sep 2012 09:58:17 +1000 Subject: Add the clang library to the repo (with some of my changes, too). --- clang/docs/LanguageExtensions.html | 1810 ++++++++++++++++++++++++++++++++++++ 1 file changed, 1810 insertions(+) create mode 100644 clang/docs/LanguageExtensions.html (limited to 'clang/docs/LanguageExtensions.html') diff --git a/clang/docs/LanguageExtensions.html b/clang/docs/LanguageExtensions.html new file mode 100644 index 0000000..68f0afc --- /dev/null +++ b/clang/docs/LanguageExtensions.html @@ -0,0 +1,1810 @@ + + + + + + Clang Language Extensions + + + + + + + + +
+ +

Clang Language Extensions

+ + + + +

Introduction

+ + +

This document describes the language extensions provided by Clang. In +addition to the language extensions listed here, Clang aims to support a broad +range of GCC extensions. Please see the GCC manual for +more information on these extensions.

+ + +

Feature Checking Macros

+ + +

Language extensions can be very useful, but only if you know you can depend +on them. In order to allow fine-grain features checks, we support three builtin +function-like macros. This allows you to directly test for a feature in your +code without having to resort to something like autoconf or fragile "compiler +version checks".

+ + +

__has_builtin

+ + +

This function-like macro takes a single identifier argument that is the name +of a builtin function. It evaluates to 1 if the builtin is supported or 0 if +not. It can be used like this:

+ +
+
+#ifndef __has_builtin         // Optional of course.
+  #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_builtin(__builtin_trap)
+  __builtin_trap();
+#else
+  abort();
+#endif
+...
+
+
+ + + +

__has_feature and __has_extension

+ + +

These function-like macros take a single identifier argument that is the +name of a feature. __has_feature evaluates to 1 if the feature +is both supported by Clang and standardized in the current language standard +or 0 if not (but see below), while +__has_extension evaluates to 1 if the feature is supported by +Clang in the current language (either as a language extension or a standard +language feature) or 0 if not. They can be used like this:

+ +
+
+#ifndef __has_feature         // Optional of course.
+  #define __has_feature(x) 0  // Compatibility with non-clang compilers.
+#endif
+#ifndef __has_extension
+  #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
+#endif
+
+...
+#if __has_feature(cxx_rvalue_references)
+// This code will only be compiled with the -std=c++11 and -std=gnu++11
+// options, because rvalue references are only standardized in C++11.
+#endif
+
+#if __has_extension(cxx_rvalue_references)
+// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
+// and -std=gnu++98 options, because rvalue references are supported as a
+// language extension in C++98.
+#endif
+
+
+ +

For backwards compatibility reasons, +__has_feature can also be used to test for support for +non-standardized features, i.e. features not prefixed c_, +cxx_ or objc_.

+ +

+Another use of __has_feature is to check for compiler features +not related to the language standard, such as e.g. +AddressSanitizer. + +

If the -pedantic-errors option is given, +__has_extension is equivalent to __has_feature.

+ +

The feature tag is described along with the language feature below.

+ +

The feature name or extension name can also be specified with a preceding and +following __ (double underscore) to avoid interference from a macro +with the same name. For instance, __cxx_rvalue_references__ can be +used instead of cxx_rvalue_references.

+ + +

__has_attribute

+ + +

This function-like macro takes a single identifier argument that is the name +of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It +can be used like this:

+ +
+
+#ifndef __has_attribute         // Optional of course.
+  #define __has_attribute(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_attribute(always_inline)
+#define ALWAYS_INLINE __attribute__((always_inline))
+#else
+#define ALWAYS_INLINE
+#endif
+...
+
+
+ +

The attribute name can also be specified with a preceding and +following __ (double underscore) to avoid interference from a macro +with the same name. For instance, __always_inline__ can be used +instead of always_inline.

+ + +

Include File Checking Macros

+ + +

Not all developments systems have the same include files. +The __has_include and +__has_include_next macros allow you to +check for the existence of an include file before doing +a possibly failing #include directive.

+ + +

__has_include

+ + +

This function-like macro takes a single file name string argument that +is the name of an include file. It evaluates to 1 if the file can +be found using the include paths, or 0 otherwise:

+ +
+
+// Note the two possible file name string formats.
+#if __has_include("myinclude.h") && __has_include(<stdint.h>)
+# include "myinclude.h"
+#endif
+
+// To avoid problem with non-clang compilers not having this macro.
+#if defined(__has_include) && __has_include("myinclude.h")
+# include "myinclude.h"
+#endif
+
+
+ +

To test for this feature, use #if defined(__has_include).

+ + +

__has_include_next

+ + +

This function-like macro takes a single file name string argument that +is the name of an include file. It is like __has_include except that it +looks for the second instance of the given file found in the include +paths. It evaluates to 1 if the second instance of the file can +be found using the include paths, or 0 otherwise:

+ +
+
+// Note the two possible file name string formats.
+#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
+# include_next "myinclude.h"
+#endif
+
+// To avoid problem with non-clang compilers not having this macro.
+#if defined(__has_include_next) && __has_include_next("myinclude.h")
+# include_next "myinclude.h"
+#endif
+
+
+ +

Note that __has_include_next, like the GNU extension +#include_next directive, is intended for use in headers only, +and will issue a warning if used in the top-level compilation +file. A warning will also be issued if an absolute path +is used in the file argument.

+ + + +

__has_warning

+ + +

This function-like macro takes a string literal that represents a command + line option for a warning and returns true if that is a valid warning + option.

+ +
+
+#if __has_warning("-Wformat")
+...
+#endif
+
+
+ + +

Builtin Macros

+ + +
+
__BASE_FILE__
+
Defined to a string that contains the name of the main input + file passed to Clang.
+ +
__COUNTER__
+
Defined to an integer value that starts at zero and is + incremented each time the __COUNTER__ macro is + expanded.
+ +
__INCLUDE_LEVEL__
+
Defined to an integral value that is the include depth of the + file currently being translated. For the main file, this value is + zero.
+ +
__TIMESTAMP__
+
Defined to the date and time of the last modification of the + current source file.
+ +
__clang__
+
Defined when compiling with Clang
+ +
__clang_major__
+
Defined to the major marketing version number of Clang (e.g., the + 2 in 2.0.1). Note that marketing version numbers should not be used to + check for language features, as different vendors use different numbering + schemes. Instead, use the feature checking + macros.
+ +
__clang_minor__
+
Defined to the minor version number of Clang (e.g., the 0 in + 2.0.1). Note that marketing version numbers should not be used to + check for language features, as different vendors use different numbering + schemes. Instead, use the feature checking + macros.
+ +
__clang_patchlevel__
+
Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
+ +
__clang_version__
+
Defined to a string that captures the Clang marketing version, including + the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".
+
+ + +

Vectors and Extended Vectors

+ + +

Supports the GCC, OpenCL, AltiVec and NEON vector extensions.

+ +

OpenCL vector types are created using ext_vector_type attribute. It +support for V.xyzw syntax and other tidbits as seen in OpenCL. An +example is:

+ +
+
+typedef float float4 __attribute__((ext_vector_type(4)));
+typedef float float2 __attribute__((ext_vector_type(2)));
+
+float4 foo(float2 a, float2 b) {
+  float4 c;
+  c.xz = a;
+  c.yw = b;
+  return c;
+}
+
+
+ +

Query for this feature with +__has_extension(attribute_ext_vector_type).

+ +

Giving -faltivec option to clang enables support for AltiVec vector +syntax and functions. For example:

+ +
+
+vector float foo(vector int a) { 
+  vector int b;
+  b = vec_add(a, a) + a; 
+  return (vector float)b;
+}
+
+
+ +

NEON vector types are created using neon_vector_type and +neon_polyvector_type attributes. For example:

+ +
+
+typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
+typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
+
+int8x8_t foo(int8x8_t a) {
+  int8x8_t v;
+  v = a;
+  return v;
+}
+
+
+ + +

Vector Literals

+ + +

Vector literals can be used to create vectors from a set of scalars, or +vectors. Either parentheses or braces form can be used. In the parentheses form +the number of literal values specified must be one, i.e. referring to a scalar +value, or must match the size of the vector type being created. If a single +scalar literal value is specified, the scalar literal value will be replicated +to all the components of the vector type. In the brackets form any number of +literals can be specified. For example:

+ +
+
+typedef int v4si __attribute__((__vector_size__(16)));
+typedef float float4 __attribute__((ext_vector_type(4)));
+typedef float float2 __attribute__((ext_vector_type(2)));
+
+v4si vsi = (v4si){1, 2, 3, 4};
+float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
+vector int vi1 = (vector int)(1);    // vi1 will be (1, 1, 1, 1).
+vector int vi2 = (vector int){1};    // vi2 will be (1, 0, 0, 0).
+vector int vi3 = (vector int)(1, 2); // error
+vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
+vector int vi5 = (vector int)(1, 2, 3, 4);
+float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
+
+
+ + +

Vector Operations

+ + +

The table below shows the support for each operation by vector extension. +A dash indicates that an operation is not accepted according to a corresponding +specification.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorOpenCLAltiVecGCCNEON
[]yesyesyes-
unary operators +, -yesyesyes-
++, --yesyes--
+, -, *, /, %yesyesyes-
bitwise operators &, |, ^, ~yesyesyes-
>>, <<yesyesyes-
!, &&,||no---
==,!=, >, <, >=, <=yesyes--
=yesyesyesyes
:?yes---
sizeofyesyesyesyes
+ +

See also __builtin_shufflevector.

+ + +

Messages on deprecated and unavailable Attributes

+ + +

An optional string message can be added to the deprecated +and unavailable attributes. For example:

+ +
+
void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
+
+ +

If the deprecated or unavailable declaration is used, the message +will be incorporated into the appropriate diagnostic:

+ +
+
harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
+      [-Wdeprecated-declarations]
+  explode();
+  ^
+
+ +

Query for this feature +with __has_extension(attribute_deprecated_with_message) +and __has_extension(attribute_unavailable_with_message).

+ + +

Attributes on Enumerators

+ + +

Clang allows attributes to be written on individual enumerators. +This allows enumerators to be deprecated, made unavailable, etc. The +attribute must appear after the enumerator name and before any +initializer, like so:

+ +
+
enum OperationMode {
+  OM_Invalid,
+  OM_Normal,
+  OM_Terrified __attribute__((deprecated)),
+  OM_AbortOnError __attribute__((deprecated)) = 4
+};
+
+ +

Attributes on the enum declaration do not apply to +individual enumerators.

+ +

Query for this feature with __has_extension(enumerator_attributes).

+ + +

'User-Specified' System Frameworks

+ + +

Clang provides a mechanism by which frameworks can be built in such a way +that they will always be treated as being 'system frameworks', even if they are +not present in a system framework directory. This can be useful to system +framework developers who want to be able to test building other applications +with development builds of their framework, including the manner in which the +compiler changes warning behavior for system headers.

+ +

Framework developers can opt-in to this mechanism by creating a +'.system_framework' file at the top-level of their framework. That is, the +framework should have contents like:

+ +
+ .../TestFramework.framework
+ .../TestFramework.framework/.system_framework
+ .../TestFramework.framework/Headers
+ .../TestFramework.framework/Headers/TestFramework.h
+ ...
+
+ +

Clang will treat the presence of this file as an indicator that the framework +should be treated as a system framework, regardless of how it was found in the +framework search path. For consistency, we recommend that such files never be +included in installed versions of the framework.

+ + +

Availability attribute

+ +

Clang introduces the availability attribute, which can +be placed on declarations to describe the lifecycle of that +declaration relative to operating system versions. Consider the function declaration for a hypothetical function f:

+ +
+void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+ +

The availability attribute states that f was introduced in Mac OS X 10.4, deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information is used by Clang to determine when it is safe to use f: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to f() succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call succeeds but Clang emits a warning specifying that the function is deprecated. Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call fails because f() is no longer available.

+ +

The availablility attribute is a comma-separated list starting with the platform name and then including clauses specifying important milestones in the declaration's lifetime (in any order) along with additional information. Those clauses can be:

+ +
+
introduced=version
+
The first version in which this declaration was introduced.
+ +
deprecated=version
+
The first version in which this declaration was deprecated, meaning that users should migrate away from this API.
+ +
obsoleted=version
+
The first version in which this declaration was obsoleted, meaning that it was removed completely and can no longer be used.
+ +
unavailable
+
This declaration is never available on this platform.
+ +
message=string-literal
+
Additional message text that Clang will provide when emitting a warning or error about use of a deprecated or obsoleted declaration. Useful to direct users to replacement APIs.
+
+ +

Multiple availability attributes can be placed on a declaration, which may correspond to different platforms. Only the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are:

+ +
+
ios
+
Apple's iOS operating system. The minimum deployment target is specified by the -mios-version-min=version or -miphoneos-version-min=version command-line arguments.
+ +
macosx
+
Apple's Mac OS X operating system. The minimum deployment target is specified by the -mmacosx-version-min=version command-line argument.
+
+ +

A declaration can be used even when deploying back to a platform +version prior to when the declaration was introduced. When this +happens, the declaration is weakly +linked, as if the weak_import attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.

+ + +

Checks for Standard Language Features

+ + +

The __has_feature macro can be used to query if certain standard +language features are enabled. The __has_extension macro can be used +to query if language features are available as an extension when compiling for +a standard which does not provide them. The features which can be tested are +listed here.

+ +

C++98

+ +

The features listed below are part of the C++98 standard. These features are +enabled by default when compiling C++ code.

+ +

C++ exceptions

+ +

Use __has_feature(cxx_exceptions) to determine if C++ exceptions have been enabled. For +example, compiling code with -fno-exceptions disables C++ exceptions.

+ +

C++ RTTI

+ +

Use __has_feature(cxx_rtti) to determine if C++ RTTI has been enabled. For example, +compiling code with -fno-rtti disables the use of RTTI.

+ +

C++11

+ +

The features listed below are part of the C++11 standard. As a result, all +these features are enabled with the -std=c++11 or -std=gnu++11 +option when compiling C++ code.

+ +

C++11 SFINAE includes access control

+ +

Use __has_feature(cxx_access_control_sfinae) or __has_extension(cxx_access_control_sfinae) to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per C++ DR1170.

+ +

C++11 alias templates

+ +

Use __has_feature(cxx_alias_templates) or +__has_extension(cxx_alias_templates) to determine if support for +C++11's alias declarations and alias templates is enabled.

+ +

C++11 alignment specifiers

+ +

Use __has_feature(cxx_alignas) or +__has_extension(cxx_alignas) to determine if support for alignment +specifiers using alignas is enabled.

+ +

C++11 attributes

+ +

Use __has_feature(cxx_attributes) or +__has_extension(cxx_attributes) to determine if support for attribute +parsing with C++11's square bracket notation is enabled.

+ +

C++11 generalized constant expressions

+ +

Use __has_feature(cxx_constexpr) to determine if support +for generalized constant expressions (e.g., constexpr) is +enabled.

+ +

C++11 decltype()

+ +

Use __has_feature(cxx_decltype) or +__has_extension(cxx_decltype) to determine if support for the +decltype() specifier is enabled. C++11's decltype +does not require type-completeness of a function call expression. +Use __has_feature(cxx_decltype_incomplete_return_types) +or __has_extension(cxx_decltype_incomplete_return_types) +to determine if support for this feature is enabled.

+ +

C++11 default template arguments in function templates

+ +

Use __has_feature(cxx_default_function_template_args) or +__has_extension(cxx_default_function_template_args) to determine +if support for default template arguments in function templates is enabled.

+ +

C++11 defaulted functions

+ +

Use __has_feature(cxx_defaulted_functions) or +__has_extension(cxx_defaulted_functions) to determine if support for +defaulted function definitions (with = default) is enabled.

+ +

C++11 delegating constructors

+ +

Use __has_feature(cxx_delegating_constructors) to determine if +support for delegating constructors is enabled.

+ +

C++11 deleted functions

+ +

Use __has_feature(cxx_deleted_functions) or +__has_extension(cxx_deleted_functions) to determine if support for +deleted function definitions (with = delete) is enabled.

+ +

C++11 explicit conversion functions

+

Use __has_feature(cxx_explicit_conversions) to determine if support for explicit conversion functions is enabled.

+ +

C++11 generalized initializers

+ +

Use __has_feature(cxx_generalized_initializers) to determine if +support for generalized initializers (using braced lists and +std::initializer_list) is enabled.

+ +

C++11 implicit move constructors/assignment operators

+ +

Use __has_feature(cxx_implicit_moves) to determine if Clang will +implicitly generate move constructors and move assignment operators where needed.

+ +

C++11 inheriting constructors

+ +

Use __has_feature(cxx_inheriting_constructors) to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.

+ +

C++11 inline namespaces

+ +

Use __has_feature(cxx_inline_namespaces) or +__has_extension(cxx_inline_namespaces) to determine if support for +inline namespaces is enabled.

+ +

C++11 lambdas

+ +

Use __has_feature(cxx_lambdas) or +__has_extension(cxx_lambdas) to determine if support for lambdas +is enabled.

+ +

C++11 local and unnamed types as template arguments

+ +

Use __has_feature(cxx_local_type_template_args) or +__has_extension(cxx_local_type_template_args) to determine if +support for local and unnamed types as template arguments is enabled.

+ +

C++11 noexcept

+ +

Use __has_feature(cxx_noexcept) or +__has_extension(cxx_noexcept) to determine if support for noexcept +exception specifications is enabled.

+ +

C++11 in-class non-static data member initialization

+ +

Use __has_feature(cxx_nonstatic_member_init) to determine whether in-class initialization of non-static data members is enabled.

+ +

C++11 nullptr

+ +

Use __has_feature(cxx_nullptr) or +__has_extension(cxx_nullptr) to determine if support for +nullptr is enabled.

+ +

C++11 override control

+ +

Use __has_feature(cxx_override_control) or +__has_extension(cxx_override_control) to determine if support for +the override control keywords is enabled.

+ +

C++11 reference-qualified functions

+

Use __has_feature(cxx_reference_qualified_functions) or +__has_extension(cxx_reference_qualified_functions) to determine +if support for reference-qualified functions (e.g., member functions with +& or && applied to *this) +is enabled.

+ +

C++11 range-based for loop

+ +

Use __has_feature(cxx_range_for) or +__has_extension(cxx_range_for) to determine if support for the +range-based for loop is enabled.

+ +

C++11 raw string literals

+

Use __has_feature(cxx_raw_string_literals) to determine if support +for raw string literals (e.g., R"x(foo\bar)x") is enabled.

+ +

C++11 rvalue references

+ +

Use __has_feature(cxx_rvalue_references) or +__has_extension(cxx_rvalue_references) to determine if support for +rvalue references is enabled.

+ +

C++11 static_assert()

+ +

Use __has_feature(cxx_static_assert) or +__has_extension(cxx_static_assert) to determine if support for +compile-time assertions using static_assert is enabled.

+ +

C++11 type inference

+ +

Use __has_feature(cxx_auto_type) or +__has_extension(cxx_auto_type) to determine C++11 type inference is +supported using the auto specifier. If this is disabled, auto +will instead be a storage class specifier, as in C or C++98.

+ +

C++11 strongly typed enumerations

+ +

Use __has_feature(cxx_strong_enums) or +__has_extension(cxx_strong_enums) to determine if support for +strongly typed, scoped enumerations is enabled.

+ +

C++11 trailing return type

+ +

Use __has_feature(cxx_trailing_return) or +__has_extension(cxx_trailing_return) to determine if support for the +alternate function declaration syntax with trailing return type is enabled.

+ +

C++11 Unicode string literals

+

Use __has_feature(cxx_unicode_literals) to determine if +support for Unicode string literals is enabled.

+ +

C++11 unrestricted unions

+ +

Use __has_feature(cxx_unrestricted_unions) to determine if support for unrestricted unions is enabled.

+ +

C++11 user-defined literals

+ +

Use __has_feature(cxx_user_literals) to determine if support for user-defined literals is enabled.

+ +

C++11 variadic templates

+ +

Use __has_feature(cxx_variadic_templates) or +__has_extension(cxx_variadic_templates) to determine if support +for variadic templates is enabled.

+ +

C11

+ +

The features listed below are part of the C11 standard. As a result, all +these features are enabled with the -std=c11 or -std=gnu11 +option when compiling C code. Additionally, because these features are all +backward-compatible, they are available as extensions in all language modes.

+ +

C11 alignment specifiers

+ +

Use __has_feature(c_alignas) or __has_extension(c_alignas) +to determine if support for alignment specifiers using _Alignas +is enabled.

+ +

C11 atomic operations

+ +

Use __has_feature(c_atomic) or __has_extension(c_atomic) +to determine if support for atomic types using _Atomic is enabled. +Clang also provides a set of builtins which can be +used to implement the <stdatomic.h> operations on _Atomic +types.

+ +

C11 generic selections

+ +

Use __has_feature(c_generic_selections) or +__has_extension(c_generic_selections) to determine if support for +generic selections is enabled.

+ +

As an extension, the C11 generic selection expression is available in all +languages supported by Clang. The syntax is the same as that given in the +C11 standard.

+ +

In C, type compatibility is decided according to the rules given in the +appropriate standard, but in C++, which lacks the type compatibility rules +used in C, types are considered compatible only if they are equivalent.

+ +

C11 _Static_assert()

+ +

Use __has_feature(c_static_assert) or +__has_extension(c_static_assert) to determine if support for +compile-time assertions using _Static_assert is enabled.

+ + +

Checks for Type Traits

+ + +

Clang supports the GNU C++ type traits and a subset of the Microsoft Visual C++ Type traits. For each supported type trait __X, __has_extension(X) indicates the presence of the type trait. For example: +

+
+#if __has_extension(is_convertible_to)
+template<typename From, typename To>
+struct is_convertible_to {
+  static const bool value = __is_convertible_to(From, To);
+};
+#else
+// Emulate type trait
+#endif
+
+
+ +

The following type traits are supported by Clang:

+ + + +

Blocks

+ + +

The syntax and high level language feature description is in BlockLanguageSpec.txt. Implementation and ABI +details for the clang implementation are in Block-ABI-Apple.txt.

+ + +

Query for this feature with __has_extension(blocks).

+ + +

Objective-C Features

+ + +

Related result types

+ +

According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:

+ +
+
+@interface NSObject
++ (id)alloc;
+- (id)init;
+@end
+
+@interface NSArray : NSObject
+@end
+
+
+ +

and this common initialization pattern

+ +
+
+NSArray *array = [[NSArray alloc] init];
+
+
+ +

the type of the expression [NSArray alloc] is +NSArray* because alloc implicitly has a +related result type. Similarly, the type of the expression +[[NSArray alloc] init] is NSArray*, since +init has a related result type and its receiver is known +to have the type NSArray *. If neither alloc nor init had a related result type, the expressions would have had type id, as declared in the method signature.

+ +

A method with a related result type can be declared by using the +type instancetype as its result type. instancetype +is a contextual keyword that is only permitted in the result type of +an Objective-C method, e.g.

+ +
+@interface A
++ (instancetype)constructAnA;
+@end
+
+ +

The related result type can also be inferred for some methods. +To determine whether a method has an inferred related result type, the first +word in the camel-case selector (e.g., "init" in "initWithObjects") is +considered, and the method will have a related result type if its return +type is compatible with the type of its class and if

+ + + +

If a method with a related result type is overridden by a subclass +method, the subclass method must also return a type that is compatible +with the subclass type. For example:

+ +
+
+@interface NSString : NSObject
+- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
+@end
+
+
+ +

Related result types only affect the type of a message send or +property access via the given method. In all other respects, a method +with a related result type is treated the same way as method that +returns id.

+ +

Use __has_feature(objc_instancetype) to determine whether +the instancetype contextual keyword is available.

+ + +

Automatic reference counting

+ + +

Clang provides support for automated reference counting in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: __has_feature(objc_arc) indicates the availability of automated reference counting in general, while __has_feature(objc_arc_weak) indicates that automated reference counting also includes support for __weak pointers to Objective-C objects.

+ + +

Enumerations with a fixed underlying type

+ + +

Clang provides support for C++11 enumerations with a fixed +underlying type within Objective-C. For example, one can write an +enumeration type as:

+ +
+typedef enum : unsigned char { Red, Green, Blue } Color;
+
+ +

This specifies that the underlying type, which is used to store the +enumeration value, is unsigned char.

+ +

Use __has_feature(objc_fixed_enum) to determine whether +support for fixed underlying types is available in Objective-C.

+ + +

Interoperability with C++11 lambdas

+ + +

Clang provides interoperability between C++11 lambdas and +blocks-based APIs, by permitting a lambda to be implicitly converted +to a block pointer with the corresponding signature. For example, +consider an API such as NSArray's array-sorting +method:

+ +
 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
+ +

NSComparator is simply a typedef for the block pointer +NSComparisonResult (^)(id, id), and parameters of this +type are generally provided with block literals as arguments. However, +one can also use a C++11 lambda so long as it provides the same +signature (in this case, accepting two parameters of type +id and returning an NSComparisonResult):

+ +
+  NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
+                     @"String 02"];
+  const NSStringCompareOptions comparisonOptions
+    = NSCaseInsensitiveSearch | NSNumericSearch |
+      NSWidthInsensitiveSearch | NSForcedOrderingSearch;
+  NSLocale *currentLocale = [NSLocale currentLocale];
+  NSArray *sorted 
+    = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
+               NSRange string1Range = NSMakeRange(0, [s1 length]);
+               return [s1 compare:s2 options:comparisonOptions 
+                          range:string1Range locale:currentLocale];
+       }];
+  NSLog(@"sorted: %@", sorted);
+
+ +

This code relies on an implicit conversion from the type of the +lambda expression (an unnamed, local class type called the closure +type) to the corresponding block pointer type. The conversion +itself is expressed by a conversion operator in that closure type +that produces a block pointer with the same signature as the lambda +itself, e.g.,

+ +
+  operator NSComparisonResult (^)(id, id)() const;
+
+ +

This conversion function returns a new block that simply forwards +the two parameters to the lambda object (which it captures by copy), +then returns the result. The returned block is first copied (with +Block_copy) and then autoreleased. As an optimization, if a +lambda expression is immediately converted to a block pointer (as in +the first example, above), then the block is not copied and +autoreleased: rather, it is given the same lifetime as a block literal +written at that point in the program, which avoids the overhead of +copying a block to the heap in the common case.

+ +

The conversion from a lambda to a block pointer is only available +in Objective-C++, and not in C++ with blocks, due to its use of +Objective-C memory management (autorelease).

+ + +

Object Literals and Subscripting

+ + +

Clang provides support for Object Literals and Subscripting in Objective-C, which simplifies common Objective-C programming patterns, makes programs more concise, and improves the safety of container creation. There are several feature macros associated with object literals and subscripting: __has_feature(objc_array_literals) tests the availability of array literals; __has_feature(objc_dictionary_literals) tests the availability of dictionary literals; __has_feature(objc_subscripting) tests the availability of object subscripting.

+ + +

Function Overloading in C

+ + +

Clang provides support for C++ function overloading in C. Function +overloading in C is introduced using the overloadable attribute. For +example, one might provide several overloaded versions of a tgsin +function that invokes the appropriate standard function computing the sine of a +value with float, double, or long double +precision:

+ +
+
+#include <math.h>
+float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+
+ +

Given these declarations, one can call tgsin with a +float value to receive a float result, with a +double to receive a double result, etc. Function +overloading in C follows the rules of C++ function overloading to pick +the best overload given the call arguments, with a few C-specific +semantics:

+ + +

The declaration of overloadable functions is restricted to +function declarations and definitions. Most importantly, if any +function with a given name is given the overloadable +attribute, then all function declarations and definitions with that +name (and in that scope) must have the overloadable +attribute. This rule even applies to redeclarations of functions whose original +declaration had the overloadable attribute, e.g.,

+ +
+
+int f(int) __attribute__((overloadable));
+float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+int g(int) __attribute__((overloadable));
+int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+
+ +

Functions marked overloadable must have +prototypes. Therefore, the following code is ill-formed:

+ +
+
+int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+
+ +

However, overloadable functions are allowed to use a +ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the unavailable attribute:

+ +
+
+void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+
+ +

Functions declared with the overloadable attribute have +their names mangled according to the same rules as C++ function +names. For example, the three tgsin functions in our +motivating example get the mangled names _Z5tgsinf, +_Z5tgsind, and _Z5tgsine, respectively. There are two +caveats to this use of name mangling:

+ + + +

Query for this feature with __has_extension(attribute_overloadable).

+ + +

Initializer lists for complex numbers in C

+ + +

clang supports an extension which allows the following in C:

+ +
+
+#include <math.h>
+#include <complex.h>
+complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
+
+
+ +

This construct is useful because there is no way to separately +initialize the real and imaginary parts of a complex variable in +standard C, given that clang does not support _Imaginary. +(clang also supports the __real__ and __imag__ +extensions from gcc, which help in some cases, but are not usable in +static initializers.) + +

Note that this extension does not allow eliding the braces; the +meaning of the following two lines is different:

+ +
+
+complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
+complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
+
+
+ +

This extension also works in C++ mode, as far as that goes, but does not + apply to the C++ std::complex. (In C++11, list + initialization allows the same syntax to be used with + std::complex with the same meaning.) + + +

Builtin Functions

+ + +

Clang supports a number of builtin library functions with the same syntax as +GCC, including things like __builtin_nan, +__builtin_constant_p, __builtin_choose_expr, +__builtin_types_compatible_p, __sync_fetch_and_add, etc. In +addition to the GCC builtins, Clang supports a number of builtins that GCC does +not, which are listed here.

+ +

Please note that Clang does not and will not support all of the GCC builtins +for vector operations. Instead of using builtins, you should use the functions +defined in target-specific header files like <xmmintrin.h>, which +define portable wrappers for these. Many of the Clang versions of these +functions are implemented directly in terms of extended +vector support instead of builtins, in order to reduce the number of +builtins that we need to implement.

+ + +

__builtin_shufflevector

+ + +

__builtin_shufflevector is used to express generic vector +permutation/shuffle/swizzle operations. This builtin is also very important for +the implementation of various target-specific header files like +<xmmintrin.h>. +

+ +

Syntax:

+ +
+__builtin_shufflevector(vec1, vec2, index1, index2, ...)
+
+ +

Examples:

+ +
+  // Identity operation - return 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
+
+  // "Splat" element 0 of V1 into a 4-element result.
+  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
+
+  // Reverse 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
+
+  // Concatenate every other element of 4-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
+
+  // Concatenate every other element of 8-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
+
+ +

Description:

+ +

The first two arguments to __builtin_shufflevector are vectors that have the +same element type. The remaining arguments are a list of integers that specify +the elements indices of the first two vectors that should be extracted and +returned in a new vector. These element indices are numbered sequentially +starting with the first vector, continuing into the second vector. Thus, if +vec1 is a 4-element vector, index 5 would refer to the second element of vec2. +

+ +

The result of __builtin_shufflevector is a vector +with the same element type as vec1/vec2 but that has an element count equal to +the number of indices specified. +

+ +

Query for this feature with __has_builtin(__builtin_shufflevector).

+ + +

__builtin_unreachable

+ + +

__builtin_unreachable is used to indicate that a specific point in +the program cannot be reached, even if the compiler might otherwise think it +can. This is useful to improve optimization and eliminates certain warnings. +For example, without the __builtin_unreachable in the example below, +the compiler assumes that the inline asm can fall through and prints a "function +declared 'noreturn' should not return" warning. +

+ +

Syntax:

+ +
+__builtin_unreachable()
+
+ +

Example of Use:

+ +
+void myabort(void) __attribute__((noreturn));
+void myabort(void) {
+    asm("int3");
+    __builtin_unreachable();
+}
+
+ +

Description:

+ +

The __builtin_unreachable() builtin has completely undefined behavior. Since +it has undefined behavior, it is a statement that it is never reached and the +optimizer can take advantage of this to produce better code. This builtin takes +no arguments and produces a void result. +

+ +

Query for this feature with __has_builtin(__builtin_unreachable).

+ + +

__sync_swap

+ + +

__sync_swap is used to atomically swap integers or pointers in +memory. +

+ +

Syntax:

+ +
+type __sync_swap(type *ptr, type value, ...)
+
+ +

Example of Use:

+ +
+int old_value = __sync_swap(&value, new_value);
+
+ +

Description:

+ +

The __sync_swap() builtin extends the existing __sync_*() family of atomic +intrinsics to allow code to atomically swap the current value with the new +value. More importantly, it helps developers write more efficient and correct +code by avoiding expensive loops around __sync_bool_compare_and_swap() or +relying on the platform specific implementation details of +__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier. +

+ + +

__c11_atomic builtins

+ + +

Clang provides a set of builtins which are intended to be used to implement +C11's <stdatomic.h> header. These builtins provide the semantics +of the _explicit form of the corresponding C11 operation, and are named +with a __c11_ prefix. The supported operations are:

+ + + + + +

Target-Specific Extensions

+ + +

Clang supports some language features conditionally on some targets.

+ + +

X86/X86-64 Language Extensions

+ + +

The X86 backend has these language extensions:

+ + +

Memory references off the GS segment

+ + +

Annotating a pointer with address space #256 causes it to be code generated +relative to the X86 GS segment register, and address space #257 causes it to be +relative to the X86 FS segment. Note that this is a very very low-level +feature that should only be used if you know what you're doing (for example in +an OS kernel).

+ +

Here is an example:

+ +
+#define GS_RELATIVE __attribute__((address_space(256)))
+int foo(int GS_RELATIVE *P) {
+  return *P;
+}
+
+ +

Which compiles to (on X86-32):

+ +
+_foo:
+	movl	4(%esp), %eax
+	movl	%gs:(%eax), %eax
+	ret
+
+ + +

Static Analysis-Specific Extensions

+ + +

Clang supports additional attributes that are useful for documenting program +invariants and rules for static analysis tools. The extensions documented here +are used by the path-sensitive static analyzer +engine that is part of Clang's Analysis library.

+ +

The analyzer_noreturn attribute

+ +

Clang's static analysis engine understands the standard noreturn +attribute. This attribute, which is typically affixed to a function prototype, +indicates that a call to a given function never returns. Function prototypes for +common functions like exit are typically annotated with this attribute, +as well as a variety of common assertion handlers. Users can educate the static +analyzer about their own custom assertion handles (thus cutting down on false +positives due to false paths) by marking their own "panic" functions +with this attribute.

+ +

While useful, noreturn is not applicable in all cases. Sometimes +there are special functions that for all intents and purposes should be +considered panic functions (i.e., they are only called when an internal program +error occurs) but may actually return so that the program can fail gracefully. +The analyzer_noreturn attribute allows one to annotate such functions +as being interpreted as "no return" functions by the analyzer (thus +pruning bogus paths) but will not affect compilation (as in the case of +noreturn).

+ +

Usage: The analyzer_noreturn attribute can be placed in the +same places where the noreturn attribute can be placed. It is commonly +placed at the end of function prototypes:

+ +
+  void foo() __attribute__((analyzer_noreturn));
+
+ +

Query for this feature with +__has_attribute(analyzer_noreturn).

+ +

The objc_method_family attribute

+ +

Many methods in Objective-C have conventional meanings determined +by their selectors. For the purposes of static analysis, it is +sometimes useful to be able to mark a method as having a particular +conventional meaning despite not having the right selector, or as not +having the conventional meaning that its selector would suggest. +For these use cases, we provide an attribute to specifically describe +the method family that a method belongs to.

+ +

Usage: __attribute__((objc_method_family(X))), +where X is one of none, alloc, copy, +init, mutableCopy, or new. This attribute +can only be placed at the end of a method declaration:

+ +
+  - (NSString*) initMyStringValue __attribute__((objc_method_family(none)));
+
+ +

Users who do not wish to change the conventional meaning of a +method, and who merely want to document its non-standard retain and +release semantics, should use the +retaining behavior attributes +described below.

+ +

Query for this feature with +__has_attribute(objc_method_family).

+ +

Objective-C retaining behavior attributes

+ +

In Objective-C, functions and methods are generally assumed to take +and return objects with +0 retain counts, with some exceptions for +special methods like +alloc and init. However, +there are exceptions, and so Clang provides attributes to allow these +exceptions to be documented, which helps the analyzer find leaks (and +ignore non-leaks). Some exceptions may be better described using +the objc_method_family +attribute instead.

+ +

Usage: The ns_returns_retained, ns_returns_not_retained, +ns_returns_autoreleased, cf_returns_retained, +and cf_returns_not_retained attributes can be placed on +methods and functions that return Objective-C or CoreFoundation +objects. They are commonly placed at the end of a function prototype +or method declaration:

+ +
+  id foo() __attribute__((ns_returns_retained));
+
+  - (NSString*) bar: (int) x __attribute__((ns_returns_retained));
+
+ +

The *_returns_retained attributes specify that the +returned object has a +1 retain count. +The *_returns_not_retained attributes specify that the return +object has a +0 retain count, even if the normal convention for its +selector would be +1. ns_returns_autoreleased specifies that the +returned object is +0, but is guaranteed to live at least as long as the +next flush of an autorelease pool.

+ +

Usage: The ns_consumed and cf_consumed +attributes can be placed on an parameter declaration; they specify +that the argument is expected to have a +1 retain count, which will be +balanced in some way by the function or method. +The ns_consumes_self attribute can only be placed on an +Objective-C method; it specifies that the method expects +its self parameter to have a +1 retain count, which it will +balance in some way.

+ +
+  void foo(__attribute__((ns_consumed)) NSString *string);
+
+  - (void) bar __attribute__((ns_consumes_self));
+  - (void) baz: (id) __attribute__((ns_consumed)) x;
+
+ +

Query for these features with __has_attribute(ns_consumed), +__has_attribute(ns_returns_retained), etc.

+ + +

Dynamic Analysis-Specific Extensions

+ +

AddressSanitizer

+

Use __has_feature(address_sanitizer) +to check if the code is being built with AddressSanitizer. +

+

Use __attribute__((no_address_safety_analysis)) on a function +declaration to specify that address safety instrumentation (e.g. +AddressSanitizer) should not be applied to that function. +

+ + +

Thread-Safety Annotation Checking

+ + +

Clang supports additional attributes for checking basic locking policies in +multithreaded programs. +Clang currently parses the following list of attributes, although +the implementation for these annotations is currently in development. +For more details, see the +GCC implementation. +

+ +

no_thread_safety_analysis

+ +

Use __attribute__((no_thread_safety_analysis)) on a function +declaration to specify that the thread safety analysis should not be run on that +function. This attribute provides an escape hatch (e.g. for situations when it +is difficult to annotate the locking policy).

+ +

lockable

+ +

Use __attribute__((lockable)) on a class definition to specify +that it has a lockable type (e.g. a Mutex class). This annotation is primarily +used to check consistency.

+ +

scoped_lockable

+ +

Use __attribute__((scoped_lockable)) on a class definition to +specify that it has a "scoped" lockable type. Objects of this type will acquire +the lock upon construction and release it upon going out of scope. + This annotation is primarily used to check +consistency.

+ +

guarded_var

+ +

Use __attribute__((guarded_var)) on a variable declaration to +specify that the variable must be accessed while holding some lock.

+ +

pt_guarded_var

+ +

Use __attribute__((pt_guarded_var)) on a pointer declaration to +specify that the pointer must be dereferenced while holding some lock.

+ +

guarded_by(l)

+ +

Use __attribute__((guarded_by(l))) on a variable declaration to +specify that the variable must be accessed while holding lock l.

+ +

pt_guarded_by(l)

+ +

Use __attribute__((pt_guarded_by(l))) on a pointer declaration to +specify that the pointer must be dereferenced while holding lock l.

+ +

acquired_before(...)

+ +

Use __attribute__((acquired_before(...))) on a declaration +of a lockable variable to specify that the lock must be acquired before all +attribute arguments. Arguments must be lockable type, and there must be at +least one argument.

+ +

acquired_after(...)

+ +

Use __attribute__((acquired_after(...))) on a declaration +of a lockable variable to specify that the lock must be acquired after all +attribute arguments. Arguments must be lockable type, and there must be at +least one argument.

+ +

exclusive_lock_function(...)

+ +

Use __attribute__((exclusive_lock_function(...))) on a function +declaration to specify that the function acquires all listed locks +exclusively. This attribute takes zero or more arguments: either of lockable +type or integers indexing into function parameters of lockable type. If no +arguments are given, the acquired lock is implicitly this of the +enclosing object.

+ +

shared_lock_function(...)

+ +

Use __attribute__((shared_lock_function(...))) on a function +declaration to specify that the function acquires all listed locks, although + the locks may be shared (e.g. read locks). This attribute takes zero or more +arguments: either of lockable type or integers indexing into function +parameters of lockable type. If no arguments are given, the acquired lock is +implicitly this of the enclosing object.

+ +

exclusive_trylock_function(...)

+ +

Use __attribute__((exclusive_lock_function(...))) on a function +declaration to specify that the function will try (without blocking) to acquire +all listed locks exclusively. This attribute takes one or more arguments. The +first argument is an integer or boolean value specifying the return value of a +successful lock acquisition. The remaining arugments are either of lockable type +or integers indexing into function parameters of lockable type. If only one +argument is given, the acquired lock is implicitly this of the +enclosing object.

+ +

shared_trylock_function(...)

+ +

Use __attribute__((shared_lock_function(...))) on a function +declaration to specify that the function will try (without blocking) to acquire +all listed locks, although the locks may be shared (e.g. read locks). This +attribute takes one or more arguments. The first argument is an integer or +boolean value specifying the return value of a successful lock acquisition. The +remaining arugments are either of lockable type or integers indexing into +function parameters of lockable type. If only one argument is given, the +acquired lock is implicitly this of the enclosing object.

+ +

unlock_function(...)

+ +

Use __attribute__((unlock_function(...))) on a function +declaration to specify that the function release all listed locks. This +attribute takes zero or more arguments: either of lockable type or integers +indexing into function parameters of lockable type. If no arguments are given, +the acquired lock is implicitly this of the enclosing object.

+ +

lock_returned(l)

+ +

Use __attribute__((lock_returned(l))) on a function +declaration to specify that the function returns lock l (l +must be of lockable type). This annotation is used to aid in resolving lock +expressions.

+ +

locks_excluded(...)

+ +

Use __attribute__((locks_excluded(...))) on a function declaration +to specify that the function must not be called with the listed locks. Arguments +must be lockable type, and there must be at least one argument.

+ +

exclusive_locks_required(...)

+ +

Use __attribute__((exclusive_locks_required(...))) on a function +declaration to specify that the function must be called while holding the listed +exclusive locks. Arguments must be lockable type, and there must be at +least one argument.

+ +

shared_locks_required(...)

+ +

Use __attribute__((shared_locks_required(...))) on a function +declaration to specify that the function must be called while holding the listed +shared locks. Arguments must be lockable type, and there must be at +least one argument.

+ +
+ + -- cgit v1.2.3