diff options
| author | Stephen Hines <srhines@google.com> | 2014-12-01 14:53:08 -0800 |
|---|---|---|
| committer | Stephen Hines <srhines@google.com> | 2014-12-01 14:53:08 -0800 |
| commit | 176edba5311f6eff0cad2631449885ddf4fbc9ea (patch) | |
| tree | f45baf023a7673970fc373bcdd0de5dc919905a1 /docs | |
| parent | 8b939a0498b8d24f4a5d7c6e6ac94ddba75ee933 (diff) | |
| download | clang-176edba5311f6eff0cad2631449885ddf4fbc9ea.tar.gz | |
Update aosp/master Clang for rebase to r222490.
Change-Id: Ic557ac55e97fbf6ee08771c7b7c3594777b0aefd
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AddressSanitizer.rst | 4 | ||||
| -rw-r--r-- | docs/AttributeReference.rst | 5 | ||||
| -rw-r--r-- | docs/ClangFormat.rst | 4 | ||||
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 102 | ||||
| -rw-r--r-- | docs/CrossCompilation.rst | 1 | ||||
| -rw-r--r-- | docs/InternalsManual.rst | 5 | ||||
| -rw-r--r-- | docs/LanguageExtensions.rst | 168 | ||||
| -rw-r--r-- | docs/LibASTMatchersReference.html | 211 | ||||
| -rw-r--r-- | docs/Modules.rst | 73 | ||||
| -rw-r--r-- | docs/RAVFrontendAction.rst | 15 | ||||
| -rw-r--r-- | docs/ReleaseNotes.rst | 76 | ||||
| -rw-r--r-- | docs/ThreadSafetyAnalysis.rst | 663 | ||||
| -rw-r--r-- | docs/UsersManual.rst | 199 | ||||
| -rw-r--r-- | docs/conf.py | 4 |
14 files changed, 1036 insertions, 494 deletions
diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst index 93a6a0ebaa..122b31ab5c 100644 --- a/docs/AddressSanitizer.rst +++ b/docs/AddressSanitizer.rst @@ -165,9 +165,9 @@ problems happening in certain source files or with certain global variables. # Disable out-of-bound checks for global: global:bad_array # Disable out-of-bound checks for global instances of a given class ... - type:class.Namespace::BadClassName + type:Namespace::BadClassName # ... or a given struct. Use wildcard to deal with anonymous namespace. - type:struct.Namespace2::*::BadStructName + type:Namespace2::*::BadStructName # Disable initialization-order checks for globals: global:bad_init_global=init type:*BadInitClassSubstring*=init diff --git a/docs/AttributeReference.rst b/docs/AttributeReference.rst index c12f6d8e1e..115a217c4c 100644 --- a/docs/AttributeReference.rst +++ b/docs/AttributeReference.rst @@ -236,6 +236,11 @@ enable_if "X","","","" +.. Note:: Some features of this attribute are experimental. The meaning of + multiple enable_if attributes on a single declaration is subject to change in + a future version of clang. Also, the ABI is not standardized and the name + mangling may change in future versions. To avoid that, use asm labels. + The ``enable_if`` attribute can be placed on function declarations to control which overload is selected based on the values of the function's arguments. When combined with the ``overloadable`` attribute, this feature is also diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst index 86c5ec5e58..45ea327179 100644 --- a/docs/ClangFormat.rst +++ b/docs/ClangFormat.rst @@ -96,8 +96,8 @@ This can be integrated by adding the following to your `.vimrc`: .. code-block:: vim - map <C-K> :pyf <path-to-this-file>/clang-format.py<CR> - imap <C-K> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i + map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> + imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the second line adds support for INSERT mode. Change "C-K" to another binding if diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index 910192bd34..cef3f24764 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -33,6 +33,43 @@ The ``.clang-format`` file uses YAML format: # A comment. ... +The configuration file can consist of several sections each having different +``Language:`` parameter denoting the programming language this section of the +configuration is targeted at. See the description of the **Language** option +below for the list of supported languages. The first section may have no +language set, it will set the default style options for all lanugages. +Configuration sections for specific language will override options set in the +default section. + +When :program:`clang-format` formats a file, it auto-detects the language using +the file name. When formatting standard input or a file that doesn't have the +extension corresponding to its language, ``-assume-filename=`` option can be +used to override the file name :program:`clang-format` uses to detect the +language. + +An example of a configuration file for multiple languages: + +.. code-block:: yaml + + --- + # We'll use defaults from the LLVM style, but with 4 columns indentation. + BasedOnStyle: LLVM + IndentWidth: 4 + --- + Language: Cpp + # Force pointers to the type for C++. + DerivePointerAlignment: false + PointerAlignment: Left + --- + Language: JavaScript + # Use 100 columns for JS. + ColumnLimit: 100 + --- + Language: Proto + # Don't format .proto files. + DisableFormat: true + ... + An easy way to get a valid ``.clang-format`` file containing all configuration options of a certain predefined style is: @@ -48,6 +85,24 @@ is applied for all input files. The format of the configuration is: -style='{key1: value1, key2: value2, ...}' +Disabling Formatting on a Piece of Code +======================================= + +Clang-format understands also special comments that switch formatting in a +delimited range. The code between a comment ``// clang-format off`` or +``/* clang-format off */`` up to a comment ``// clang-format on`` or +``/* clang-format on */`` will not be formatted. The comments themselves +will be formatted (aligned) normally. + +.. code-block:: c++ + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + + Configuring Style in Code ========================= @@ -111,6 +166,9 @@ the configuration (without a prefix: ``Auto``). E.g., this allows ``if (a) { return; }`` to be put on a single line. +**AllowShortCaseLabelsOnASingleLine** (``bool``) + If ``true``, short case labels will be contracted to a single line. + **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) Dependent on the value, ``int f() { return 0; }`` can be put on a single line. @@ -133,6 +191,13 @@ the configuration (without a prefix: ``Auto``). If ``true``, ``while (true) continue;`` can be put on a single line. +**AlwaysBreakAfterDefinitionReturnType** (``bool``) + If ``true``, always break after function definition return types. + + More truthfully called 'break before the identifier following the type + in a function definition'. PenaltyReturnTypeOnItsOwnLine becomes + irrelevant. + **AlwaysBreakBeforeMultilineStrings** (``bool``) If ``true``, always break before multiline string literals. @@ -140,12 +205,26 @@ the configuration (without a prefix: ``Auto``). If ``true``, always break after the ``template<...>`` of a template declaration. +**BinPackArguments** (``bool``) + If ``false``, a function call's arguments will either be all on the + same line or will have one line each. + **BinPackParameters** (``bool``) - If ``false``, a function call's or function definition's parameters - will either all be on the same line or will have one line each. + If ``false``, a function declaration's or function definition's + parameters will either all be on the same line or will have one line each. + +**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) + The way to wrap binary operators. + + Possible values: + + * ``BOS_None`` (in configuration: ``None``) + Break after operators. + * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) + Break before operators that aren't assignments. + * ``BOS_All`` (in configuration: ``All``) + Break before operators. -**BreakBeforeBinaryOperators** (``bool``) - If ``true``, binary operators will be placed after line breaks. **BreakBeforeBraces** (``BraceBreakingStyle``) The brace breaking style to use. @@ -158,7 +237,7 @@ the configuration (without a prefix: ``Auto``). Like ``Attach``, but break before braces on function, namespace and class definitions. * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) - Like ``Attach``, but break before function definitions. + Like ``Attach``, but break before function definitions, and 'else'. * ``BS_Allman`` (in configuration: ``Allman``) Always break before braces. * ``BS_GNU`` (in configuration: ``GNU``) @@ -213,7 +292,7 @@ the configuration (without a prefix: ``Auto``). **DerivePointerAlignment** (``bool``) If ``true``, analyze the formatted file for the most common - alignment of & and *. ``PointerAlignment`` is then used only as fallback. + alignment of & and \*. ``PointerAlignment`` is then used only as fallback. **DisableFormat** (``bool``) Disables formatting at all. @@ -267,6 +346,8 @@ the configuration (without a prefix: ``Auto``). Do not use. * ``LK_Cpp`` (in configuration: ``Cpp``) Should be used for C, C++, ObjectiveC, ObjectiveC++. + * ``LK_Java`` (in configuration: ``Java``) + Should be used for Java. * ``LK_JavaScript`` (in configuration: ``JavaScript``) Should be used for JavaScript. * ``LK_Proto`` (in configuration: ``Proto``) @@ -290,6 +371,9 @@ the configuration (without a prefix: ``Auto``). Indent in all namespaces. +**ObjCBlockIndentWidth** (``unsigned``) + The number of characters to use for indentation of ObjC blocks. + **ObjCSpaceAfterProperty** (``bool``) Add a space after ``@property`` in Objective-C, i.e. use ``\@property (readonly)`` instead of ``\@property(readonly)``. @@ -330,6 +414,9 @@ the configuration (without a prefix: ``Auto``). Align pointer in the middle. +**SpaceAfterCStyleCast** (``bool``) + If ``true``, a space may be inserted after C style casts. + **SpaceBeforeAssignmentOperators** (``bool``) If ``false``, spaces will be removed before assignment operators. @@ -374,6 +461,9 @@ the configuration (without a prefix: ``Auto``). **SpacesInParentheses** (``bool``) If ``true``, spaces will be inserted after '(' and before ')'. +**SpacesInSquareBrackets** (``bool``) + If ``true``, spaces will be inserted after '[' and before ']'. + **Standard** (``LanguageStandard``) Format compatible with this standard, e.g. use ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03. diff --git a/docs/CrossCompilation.rst b/docs/CrossCompilation.rst index 89f8777ac0..fd42856ec3 100644 --- a/docs/CrossCompilation.rst +++ b/docs/CrossCompilation.rst @@ -201,4 +201,3 @@ uses hard-float), Clang will pick the ``armv7l-linux-gnueabi-ld`` The same is true if you're compiling for different ABIs, like ``gnueabi`` and ``androideabi``, and might even link and run, but produce run-time errors, which are much harder to track down and fix. - diff --git a/docs/InternalsManual.rst b/docs/InternalsManual.rst index 8e047dbdae..50a1943ee2 100644 --- a/docs/InternalsManual.rst +++ b/docs/InternalsManual.rst @@ -1396,10 +1396,7 @@ body by single call to a static class method: .. code-block:: c++ Stmt *FooBody = ... - CFG *FooCFG = CFG::buildCFG(FooBody); - -It is the responsibility of the caller of ``CFG::buildCFG`` to ``delete`` the -returned ``CFG*`` when the CFG is no longer needed. + std::unique_ptr<CFG> FooCFG = CFG::buildCFG(FooBody); Along with providing an interface to iterate over its ``CFGBlocks``, the ``CFG`` class also provides methods that are useful for debugging and diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index ad7821af70..ae298afdee 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -91,7 +91,7 @@ feature) or 0 if not. They can be used like this: .. _langext-has-feature-back-compat: -For backwards compatibility reasons, ``__has_feature`` can also be used to test +For backward compatibility, ``__has_feature`` can also be used to test for support for non-standardized features, i.e. features not prefixed ``c_``, ``cxx_`` or ``objc_``. @@ -109,6 +109,36 @@ 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_cpp_attribute`` +----------------------- + +This function-like macro takes a single argument that is the name of a +C++11-style attribute. The argument can either be a single identifier, or a +scoped identifier. If the attribute is supported, a nonzero value is returned. +If the attribute is a standards-based attribute, this macro returns a nonzero +value based on the year and month in which the attribute was voted into the +working draft. If the attribute is not supported by the current compliation +target, this macro evaluates to 0. It can be used like this: + +.. code-block:: c++ + + #ifndef __has_cpp_attribute // Optional of course. + #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_cpp_attribute(clang::fallthrough) + #define FALLTHROUGH [[clang::fallthrough]] + #else + #define FALLTHROUGH + #endif + ... + +The attribute identifier (but not scope) can also be specified with a preceding +and following ``__`` (double underscore) to avoid interference from a macro with +the same name. For instance, ``gnu::__const__`` can be used instead of +``gnu::const``. + ``__has_attribute`` ------------------- @@ -357,23 +387,27 @@ The table below shows the support for each operation by vector extension. A dash indicates that an operation is not accepted according to a corresponding specification. -============================== ====== ======= === ==== - Opeator OpenCL AltiVec GCC NEON -============================== ====== ======= === ==== -[] yes yes yes -- -unary operators +, -- yes yes yes -- -++, -- -- yes yes yes -- -+,--,*,/,% yes yes yes -- -bitwise operators &,|,^,~ yes yes yes -- ->>,<< yes yes yes -- -!, &&, || no -- -- -- -==, !=, >, <, >=, <= yes yes -- -- -= yes yes yes yes -:? yes -- -- -- -sizeof yes yes yes yes -============================== ====== ======= === ==== - -See also :ref:`langext-__builtin_shufflevector`. +============================== ======= ======= ======= ======= + Opeator OpenCL AltiVec GCC NEON +============================== ======= ======= ======= ======= +[] yes yes yes -- +unary operators +, -- yes yes yes -- +++, -- -- yes yes yes -- ++,--,*,/,% yes yes yes -- +bitwise operators &,|,^,~ yes yes yes -- +>>,<< yes yes yes -- +!, &&, || yes -- -- -- +==, !=, >, <, >=, <= yes yes -- -- += yes yes yes yes +:? yes -- -- -- +sizeof yes yes yes yes +C-style cast yes yes yes no +reinterpret_cast yes no yes no +static_cast yes no yes no +const_cast no no no no +============================== ======= ======= ======= ======= + +See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. Messages on ``deprecated`` and ``unavailable`` Attributes ========================================================= @@ -454,6 +488,13 @@ 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. +Since Clang 3.4, the C++ SD-6 feature test macros are also supported. +These are macros with names of the form ``__cpp_<feature_name>``, and are +intended to be a portable way to query the supported features of the compiler. +See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for +information on the version of SD-6 supported by each Clang release, and the +macros provided by that revision of the recommendations. + C++98 ----- @@ -747,6 +788,13 @@ Use ``__has_feature(cxx_aggregate_nsdmi)`` or ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support for default initializers in aggregate members is enabled. +C++1y digit separators +^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__cpp_digit_separators`` to determine if support for digit separators +using single quotes (for instance, ``10'000``) is enabled. At this time, there +is no corresponding ``__has_feature`` name + C++1y generalized lambda capture ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -815,7 +863,16 @@ C11 atomic operations Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine if support for atomic types using ``_Atomic`` is enabled. Clang also provides :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement -the ``<stdatomic.h>`` operations on ``_Atomic`` types. +the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use +``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header +is available. + +Clang will use the system's ``<stdatomic.h>`` header when one is available, and +will otherwise use its own. When using its own, implementations of the atomic +operations are provided as macros. In the cases where C11 also requires a real +function, this header provides only the declaration of that function (along +with a shadowing macro implementation), and you must link to a library which +provides a definition of the function if you use it instead of the macro. C11 generic selections ^^^^^^^^^^^^^^^^^^^^^^ @@ -1224,8 +1281,9 @@ 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. +``__builtin_assume_aligned``, ``__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 @@ -1235,6 +1293,42 @@ implemented directly in terms of :ref:`extended vector support <langext-vectors>` instead of builtins, in order to reduce the number of builtins that we need to implement. +``__builtin_assume`` +------------------------------ + +``__builtin_assume`` is used to provide the optimizer with a boolean +invariant that is defined to be true. + +**Syntax**: + +.. code-block:: c++ + + __builtin_assume(bool) + +**Example of Use**: + +.. code-block:: c++ + + int foo(int x) { + __builtin_assume(x != 0); + + // The optimizer may short-circuit this check using the invariant. + if (x == 0) + return do_something(); + + return do_something_else(); + } + +**Description**: + +The boolean argument to this function is defined to be true. The optimizer may +analyze the form of the expression provided as the argument and deduce from +that information used to optimize the program. If the condition is violated +during execution, the behavior is undefined. The argument itself is never +evaluated, so any side effects of the expression will be discarded. + +Query for this feature with ``__has_builtin(__builtin_assume)``. + ``__builtin_readcyclecounter`` ------------------------------ @@ -1324,6 +1418,8 @@ indices specified. Query for this feature with ``__has_builtin(__builtin_shufflevector)``. +.. _langext-__builtin_convertvector: + ``__builtin_convertvector`` --------------------------- @@ -1354,7 +1450,7 @@ type must have the same number of elements. // convert from a vector of 4 shorts to a vector of 4 floats. __builtin_convertvector(vs, vector4float) // equivalent to: - (vector4float) { (float) vf[0], (float) vf[1], (float) vf[2], (float) vf[3] } + (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] } **Description**: @@ -1554,12 +1650,14 @@ __c11_atomic builtins Clang provides a set of builtins which are intended to be used to implement C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the ``_explicit`` form of the corresponding C11 operation, and are named with a -``__c11_`` prefix. The supported operations are: +``__c11_`` prefix. The supported operations, and the differences from +the corresponding C11 operations, are: * ``__c11_atomic_init`` * ``__c11_atomic_thread_fence`` * ``__c11_atomic_signal_fence`` -* ``__c11_atomic_is_lock_free`` +* ``__c11_atomic_is_lock_free`` (The argument is the size of the + ``_Atomic(...)`` object, instead of its address) * ``__c11_atomic_store`` * ``__c11_atomic_load`` * ``__c11_atomic_exchange`` @@ -1571,6 +1669,11 @@ C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the * ``__c11_atomic_fetch_or`` * ``__c11_atomic_fetch_xor`` +The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, +``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are +provided, with values corresponding to the enumerators of C11's +``memory_order`` enumeration. + Low-level ARM exclusive memory builtins --------------------------------------- @@ -1634,6 +1737,19 @@ Target-Specific Extensions Clang supports some language features conditionally on some targets. +ARM/AArch64 Language Extensions +------------------------------- + +Memory Barrier Intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^ +Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined +in the `ARM C Language Extensions Release 2.0 +<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_. +Note that these intrinsics are implemented as motion barriers that block +reordering of memory accesses and side effect instructions. Other instructions +like simple arithmatic may be reordered around the intrinsic. If you expect to +have no reordering at all, use inline assembly instead. + X86/X86-64 Language Extensions ------------------------------ @@ -1830,7 +1946,7 @@ iterations. Full unrolling is only possible if the loop trip count is known at compile time. Partial unrolling replicates the loop body within the loop and reduces the trip count. -If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the +If ``unroll(full)`` is specified the unroller will attempt to fully unroll the loop if the trip count is known at compile time. If the loop count is not known or the fully unrolled code size is greater than the limit specified by the `-pragma-unroll-threshold` command line option the loop will be partially @@ -1838,7 +1954,7 @@ unrolled subject to the same limit. .. code-block:: c++ - #pragma clang loop unroll(enable) + #pragma clang loop unroll(full) for(...) { ... } diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html index 49880539bc..2eabff49cf 100644 --- a/docs/LibASTMatchersReference.html +++ b/docs/LibASTMatchersReference.html @@ -246,6 +246,16 @@ Example matches f </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('linkageSpecDecl0')"><a name="linkageSpecDecl0Anchor">linkageSpecDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LinkageSpecDecl.html">LinkageSpecDecl</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="linkageSpecDecl0"><pre>Matches a declaration of a linkage specification. + +Given + extern "C" {} +linkageSpecDecl() + matches "extern "C" {}" +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('methodDecl0')"><a name="methodDecl0Anchor">methodDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>...</td></tr> <tr><td colspan="4" class="doc" id="methodDecl0"><pre>Matches method declarations. @@ -319,6 +329,16 @@ usingDecl() matches using X::x </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('usingDirectiveDecl0')"><a name="usingDirectiveDecl0Anchor">usingDirectiveDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UsingDirectiveDecl.html">UsingDirectiveDecl</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="usingDirectiveDecl0"><pre>Matches using namespace declarations. + +Given + namespace X { int x; } + using namespace X; +usingDirectiveDecl() + matches using namespace X </pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('varDecl0')"><a name="varDecl0Anchor">varDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>...</td></tr> <tr><td colspan="4" class="doc" id="varDecl0"><pre>Matches variable declarations. @@ -355,6 +375,14 @@ nestedNameSpecifier() </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('CUDAKernelCallExpr0')"><a name="CUDAKernelCallExpr0Anchor">CUDAKernelCallExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CUDAKernelCallExpr.html">CUDAKernelCallExpr</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="CUDAKernelCallExpr0"><pre>Matches CUDA kernel call expression. + +Example matches, + kernel<<<i,j>>>(); +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('arraySubscriptExpr0')"><a name="arraySubscriptExpr0Anchor">arraySubscriptExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>>...</td></tr> <tr><td colspan="4" class="doc" id="arraySubscriptExpr0"><pre>Matches array subscript expressions. @@ -711,7 +739,7 @@ Given int a[] = { 1, 2 }; struct B { int x, y; }; B b = { 5, 6 }; -initList() +initListExpr() matches "{ 1, 2 }" and "{ 5, 6 }" </pre></td></tr> @@ -876,6 +904,18 @@ Example matches "abcd", L"abcd" </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('substNonTypeTemplateParmExpr0')"><a name="substNonTypeTemplateParmExpr0Anchor">substNonTypeTemplateParmExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SubstNonTypeTemplateParmExpr.html">SubstNonTypeTemplateParmExpr</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="substNonTypeTemplateParmExpr0"><pre>Matches substitutions of non-type template parameters. + +Given + template <int N> + struct A { static const int n = N; }; + struct B : public A<42> {}; +substNonTypeTemplateParmExpr() + matches "N" in the right-hand side of "static const int n = N;" +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('switchCase0')"><a name="switchCase0Anchor">switchCase</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchCase.html">SwitchCase</a>>...</td></tr> <tr><td colspan="4" class="doc" id="switchCase0"><pre>Matches case and default statements inside switch statements. @@ -980,6 +1020,17 @@ whileStmt() </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('templateArgument0')"><a name="templateArgument0Anchor">templateArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="templateArgument0"><pre>Matches template arguments. + +Given + template <typename T> struct C {}; + C<int> c; +templateArgument() + matches 'int' in C<int>. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('typeLoc0')"><a name="typeLoc0Anchor">typeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>...</td></tr> <tr><td colspan="4" class="doc" id="typeLoc0"><pre>Matches TypeLocs in the clang AST. </pre></td></tr> @@ -1269,6 +1320,7 @@ Given int a[] = { 2, 3 } int b[42]; int c[a[0]]; + } variableArrayType() matches "int c[a[0]]" </pre></td></tr> @@ -1381,26 +1433,6 @@ constructorDecl(hasAnyConstructorInitializer(isWritten())) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('hasOverloadedOperatorName0')"><a name="hasOverloadedOperatorName0Anchor">hasOverloadedOperatorName</a></td><td>StringRef Name</td></tr> -<tr><td colspan="4" class="doc" id="hasOverloadedOperatorName0"><pre>Matches overloaded operator names. - -Matches overloaded operator names specified in strings without the -"operator" prefix: e.g. "<<". - -Given: - class A { int operator*(); }; - const A &operator<<(const A &a, const A &b); - A a; - a << a; <-- This matches - -operatorCallExpr(hasOverloadedOperatorName("<<"))) matches the specified -line and recordDecl(hasMethod(hasOverloadedOperatorName("*"))) matches -the declaration of A. - -Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>> -</pre></td></tr> - - <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isConst0')"><a name="isConst0Anchor">isConst</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isConst0"><pre>Matches if the given method declaration is const. @@ -1470,7 +1502,7 @@ operatorCallExpr(hasOverloadedOperatorName("<<"))) matches the specified line and recordDecl(hasMethod(hasOverloadedOperatorName("*"))) matches the declaration of A. -Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>> +Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>> </pre></td></tr> @@ -1541,6 +1573,17 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Charac </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateSpecializationDecl.html">ClassTemplateSpecializationDecl</a>></td><td class="name" onclick="toggle('templateArgumentCountIs0')"><a name="templateArgumentCountIs0Anchor">templateArgumentCountIs</a></td><td>unsigned N</td></tr> +<tr><td colspan="4" class="doc" id="templateArgumentCountIs0"><pre>Matches if the number of template arguments equals N. + +Given + template<typename T> struct C {}; + C<int> c; +classTemplateSpecializationDecl(templateArgumentCountIs(1)) + matches C<int>. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>></td><td class="name" onclick="toggle('statementCountIs0')"><a name="statementCountIs0Anchor">statementCountIs</a></td><td>unsigned N</td></tr> <tr><td colspan="4" class="doc" id="statementCountIs0"><pre>Checks that a compound statement contains a specific number of child statements. @@ -1601,10 +1644,13 @@ and reference to that variable declaration within a compound statement. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl *Node</td></tr> -<tr><td colspan="4" class="doc" id="equalsNode0"><pre>Matches if a node equals another node. +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('hasAttr0')"><a name="hasAttr0Anchor">hasAttr</a></td><td>attr::Kind AttrKind</td></tr> +<tr><td colspan="4" class="doc" id="hasAttr0"><pre>Matches declaration that has a given attribute. -Decl has pointer identity in the AST. +Given + __attribute__((device)) void f() { ... } +decl(hasAttr(clang::attr::CUDADevice)) matches the function declaration of +f. </pre></td></tr> @@ -1614,6 +1660,19 @@ by the compiler (eg. implicit defaultcopy constructors). </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isInstantiated0')"><a name="isInstantiated0Anchor">isInstantiated</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isInstantiated0"><pre>Matches declarations that are template instantiations or are inside +template instantiations. + +Given + template<typename T> void A(T t) { T i; } + A(0); + A(0U); +functionDecl(isInstantiated()) + matches 'A(int) {...};' and 'A(unsigned) {...}'. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isPrivate0')"><a name="isPrivate0Anchor">isPrivate</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isPrivate0"><pre>Matches private C++ declarations. @@ -1667,6 +1726,26 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Charac </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasOverloadedOperatorName0')"><a name="hasOverloadedOperatorName0Anchor">hasOverloadedOperatorName</a></td><td>StringRef Name</td></tr> +<tr><td colspan="4" class="doc" id="hasOverloadedOperatorName0"><pre>Matches overloaded operator names. + +Matches overloaded operator names specified in strings without the +"operator" prefix: e.g. "<<". + +Given: + class A { int operator*(); }; + const A &operator<<(const A &a, const A &b); + A a; + a << a; <-- This matches + +operatorCallExpr(hasOverloadedOperatorName("<<"))) matches the specified +line and recordDecl(hasMethod(hasOverloadedOperatorName("*"))) matches +the declaration of A. + +Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>> +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isDefinition2')"><a name="isDefinition2Anchor">isDefinition</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isDefinition2"><pre>Matches if a declaration has a body attached. @@ -1682,6 +1761,17 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDec </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isDeleted0')"><a name="isDeleted0Anchor">isDeleted</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isDeleted0"><pre>Matches deleted function declarations. + +Given: + void Func(); + void DeletedFunc() = delete; +functionDecl(isDeleted()) + matches the declaration of DeletedFunc, but not Func. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isExplicitTemplateSpecialization0')"><a name="isExplicitTemplateSpecialization0Anchor">isExplicitTemplateSpecialization</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isExplicitTemplateSpecialization0"><pre>Matches explicit template specializations of function, class, or static member variable template instantiations. @@ -1900,11 +1990,19 @@ and reference to that variable declaration within a compound statement. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt *Node</td></tr> -<tr><td colspan="4" class="doc" id="equalsNode1"><pre>Matches if a node equals another node. - -Stmt has pointer identity in the AST. +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('isInTemplateInstantiation0')"><a name="isInTemplateInstantiation0Anchor">isInTemplateInstantiation</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isInTemplateInstantiation0"><pre>Matches statements inside of a template instantiation. +Given + int j; + template<typename T> void A(T t) { T i; j += 42;} + A(0); + A(0U); +declStmt(isInTemplateInstantiation()) + matches 'int i;' and 'unsigned i'. +unless(stmt(isInTemplateInstantiation())) + will NOT match j += 42; as it's shared between the template definition and + instantiation. </pre></td></tr> @@ -1923,6 +2021,46 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagDec </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('equalsIntegralValue0')"><a name="equalsIntegralValue0Anchor">equalsIntegralValue</a></td><td>std::string Value</td></tr> +<tr><td colspan="4" class="doc" id="equalsIntegralValue0"><pre>Matches a TemplateArgument of integral type with a given value. + +Note that 'Value' is a string as the template argument's value is +an arbitrary precision integer. 'Value' must be euqal to the canonical +representation of that integral value in base 10. + +Given + template<int T> struct A {}; + C<42> c; +classTemplateSpecializationDecl( + hasAnyTemplateArgument(equalsIntegralValue("42"))) + matches the implicit instantiation of C in C<42>. +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('isIntegral0')"><a name="isIntegral0Anchor">isIntegral</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isIntegral0"><pre>Matches a TemplateArgument that is an integral value. + +Given + template<int T> struct A {}; + C<42> c; +classTemplateSpecializationDecl( + hasAnyTemplateArgument(isIntegral())) + matches the implicit instantiation of C in C<42> + with isIntegral() matching 42. +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('templateArgumentCountIs1')"><a name="templateArgumentCountIs1Anchor">templateArgumentCountIs</a></td><td>unsigned N</td></tr> +<tr><td colspan="4" class="doc" id="templateArgumentCountIs1"><pre>Matches if the number of template arguments equals N. + +Given + template<typename T> struct C {}; + C<int> c; +classTemplateSpecializationDecl(templateArgumentCountIs(1)) + matches C<int>. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('equalsBoundNode2')"><a name="equalsBoundNode2Anchor">equalsBoundNode</a></td><td>std::string ID</td></tr> <tr><td colspan="4" class="doc" id="equalsBoundNode2"><pre>Matches if a node equals a previously bound node. @@ -2550,7 +2688,7 @@ given matcher. Example matches y.x() (matcher = callExpr(callee(methodDecl(hasName("x"))))) class Y { public: void x(); }; - void z() { Y y; y.x(); + void z() { Y y; y.x(); } </pre></td></tr> @@ -3448,6 +3586,7 @@ Example matches X &x and const X &y void a(X b) { X &x = b; const X &y = b; + } }; </pre></td></tr> @@ -3582,6 +3721,18 @@ classTemplateSpecializationDecl(hasAnyTemplateArgument( </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('refersToIntegralType0')"><a name="refersToIntegralType0Anchor">refersToIntegralType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr> +<tr><td colspan="4" class="doc" id="refersToIntegralType0"><pre>Matches a TemplateArgument that referes to an integral type. + +Given + template<int T> struct A {}; + C<42> c; +classTemplateSpecializationDecl( + hasAnyTemplateArgument(refersToIntegralType(asString("int")))) + matches the implicit instantiation of C in C<42>. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('refersToType0')"><a name="refersToType0Anchor">refersToType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="refersToType0"><pre>Matches a TemplateArgument that refers to a certain type. diff --git a/docs/Modules.rst b/docs/Modules.rst index ce1e717bc2..df471a45fb 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -2,10 +2,6 @@ Modules ======= -.. warning:: - The functionality described on this page is supported for C and - Objective-C. C++ support is experimental. - .. contents:: :local: @@ -104,7 +100,7 @@ Many programming languages have a module or package system, and because of the v Using Modules ============= -To enable modules, pass the command-line flag ``-fmodules`` [#]_. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later. +To enable modules, pass the command-line flag ``-fmodules``. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later. Objective-C Import declaration ------------------------------ @@ -114,7 +110,7 @@ Objective-C provides syntax for importing a module via an *@import declaration*, @import std; -The @import declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g., +The ``@import`` declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g., .. parsed-literal:: @@ -140,6 +136,19 @@ will be automatically mapped to an import of the module ``std.io``. Even with sp The automatic mapping of ``#include`` to ``import`` also solves an implementation problem: importing a module with a definition of some entity (say, a ``struct Point``) and then parsing a header containing another definition of ``struct Point`` would cause a redefinition error, even if it is the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler can guarantee that it always sees just the already-parsed definition from the module. +While building a module, ``#include_next`` is also supported, with one caveat. +The usual behavior of ``#include_next`` is to search for the specified filename +in the list of include paths, starting from the path *after* the one +in which the current file was found. +Because files listed in module maps are not found through include paths, a +different strategy is used for ``#include_next`` directives in such files: the +list of include paths is searched for the specified header name, to find the +first include path that would refer to the current file. ``#include_next`` is +interpreted as if the current file had been found in that path. +If this search finds a file named by a module map, the ``#include_next`` +directive is translated into an import, just like for a ``#include`` +directive.`` + Module maps ----------- The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports. @@ -163,13 +172,10 @@ Modules maintain references to each of the headers that were part of the module Command-line parameters ----------------------- ``-fmodules`` - Enable the modules feature (EXPERIMENTAL). - -``-fcxx-modules`` - Enable the modules feature for C++ (EXPERIMENTAL and VERY BROKEN). + Enable the modules feature. ``-fmodule-maps`` - Enable interpretation of module maps (EXPERIMENTAL). This option is implied by ``-fmodules``. + Enable interpretation of module maps. This option is implied by ``-fmodules``. ``-fmodules-cache-path=<directory>`` Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default. @@ -208,7 +214,7 @@ Modules are modeled as if each submodule were a separate translation unit, and a .. note:: - This behavior is currently only approximated when building a module. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. + This behavior is currently only approximated when building a module with submodules. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. This behavior is subject to change. As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match. In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule. @@ -216,6 +222,8 @@ As an example, in C, this implies that if two structs are defined in different s Clang currently only performs minimal checking for violations of the One Definition Rule. +If any submodule of a module is imported into any part of a program, the entire top-level module is considered to be part of the program. As a consequence of this, Clang may diagnose conflicts between an entity declared in an unimported submodule and an entity declared in the current translation unit, and Clang may inline or devirtualize based on knowledge from unimported submodules. + Macros ------ @@ -238,6 +246,10 @@ The ``#undef`` overrides the ``#define``, and a source file that imports both mo Module Map Language =================== +.. warning:: + + The module map language is not currently guaranteed to be stable between major revisions of Clang. + The module map language describes the mapping from header files to the logical structure of modules. To enable support for using a library as a module, one must write a ``module.modulemap`` file for that library. The @@ -255,6 +267,12 @@ As an example, the module map file for the C standard library might look a bit l .. parsed-literal:: module std [system] [extern_c] { + module assert { + textual header "assert.h" + header "bits/assert-decls.h" + export * + } + module complex { header "complex.h" export * @@ -287,11 +305,11 @@ Module map files use a simplified form of the C99 lexer, with the same rules for .. parsed-literal:: - ``config_macros`` ``export`` ``module`` + ``config_macros`` ``export`` ``private`` ``conflict`` ``framework`` ``requires`` - ``exclude`` ``header`` ``private`` + ``exclude`` ``header`` ``textual`` ``explicit`` ``link`` ``umbrella`` - ``extern`` ``use`` + ``extern`` ``module`` ``use`` Module map file --------------- @@ -319,7 +337,7 @@ A module declaration describes a module, including the headers that contribute t ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}' ``extern`` ``module`` *module-id* *string-literal* -The *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition. +The *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition. The ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module. @@ -427,11 +445,11 @@ A header declaration specifies that a particular header is associated with the e .. parsed-literal:: *header-declaration*: - ``umbrella``:sub:`opt` ``header`` *string-literal* - ``private`` ``header`` *string-literal* + ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal* + ``umbrella`` ``header`` *string-literal* ``exclude`` ``header`` *string-literal* -A header declaration that does not contain ``exclude`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule. +A header declaration that does not contain ``exclude`` nor ``textual`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule. A header with the ``umbrella`` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the ``#include`` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out ``header`` declarations for every library header. A given directory can only contain a single umbrella header. @@ -443,14 +461,16 @@ A header with the ``umbrella`` specifier is called an umbrella header. An umbrel A header with the ``private`` specifier may not be included from outside the module itself. -A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module. +A header with the ``textual`` specifier will not be included when the module is built, and will be textually included if it is named by a ``#include`` directive. However, it is considered to be part of the module for the purpose of checking *use-declaration*\s. -**Example**: The C header ``assert.h`` is an excellent candidate for an excluded header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings). +A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an ``umbrella`` header or directory would otherwise make it part of the module. + +**Example**: The C header ``assert.h`` is an excellent candidate for a textual header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings). However, declarations within it should typically be split into a separate modular header. .. parsed-literal:: module std [system] { - exclude header "assert.h" + textual header "assert.h" } A given header shall not be referenced by more than one *header-declaration*. @@ -824,20 +844,17 @@ To detect and help address some of these problems, the ``clang-tools-extra`` rep Future Directions ================= -Modules is an experimental feature, and there is much work left to do to make it both real and useful. Here are a few ideas: +Modules support is under active development, and there are many opportunities remaining to improve it. Here are a few ideas: **Detect unused module imports** Unlike with ``#include`` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to remove the useless imports/includes. **Fix-Its for missing imports** - It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang should detect such cases and auto-import the required module (with a Fix-It!). + It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang can detect such cases and auto-import the required module, but should provide a Fix-It to add the import. **Improve modularize** The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you. -**C++ Support** - Modules clearly has to work for C++, or we'll never get to use it for the Clang code base. - Where To Learn More About Modules ================================= The Clang source code provides additional information about modules: @@ -859,8 +876,6 @@ PCHInternals_ .. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available. -.. [#] Modules are only available in C and Objective-C; a separate flag ``-fcxx-modules`` enables modules support for C++, which is even more experimental and broken. - .. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section `Modularizing a Platform`_ describes some of them. .. [#] The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread. diff --git a/docs/RAVFrontendAction.rst b/docs/RAVFrontendAction.rst index 2f60ce9e82..ec5d5d54ff 100644 --- a/docs/RAVFrontendAction.rst +++ b/docs/RAVFrontendAction.rst @@ -25,9 +25,10 @@ unit. class FindNamedClassAction : public clang::ASTFrontendAction { public: - virtual clang::ASTConsumer *CreateASTConsumer( + virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer( clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer; + return std::unique_ptr<clang::ASTConsumer>( + new FindNamedClassConsumer); } }; @@ -111,9 +112,10 @@ freshly created FindNamedClassConsumer: :: - virtual clang::ASTConsumer *CreateASTConsumer( + virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer( clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer(&Compiler.getASTContext()); + return std::unique_ptr<clang::ASTConsumer>( + new FindNamedClassConsumer(&Compiler.getASTContext())); } Now that the ASTContext is available in the RecursiveASTVisitor, we can @@ -185,9 +187,10 @@ Now we can combine all of the above into a small example program: class FindNamedClassAction : public clang::ASTFrontendAction { public: - virtual clang::ASTConsumer *CreateASTConsumer( + virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer( clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer(&Compiler.getASTContext()); + return std::unique_ptr<clang::ASTConsumer>( + new FindNamedClassConsumer(&Compiler.getASTContext())); } }; diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index c99262eb35..daab804b53 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,5 +1,5 @@ ===================================== -Clang 3.5 (In-Progress) Release Notes +Clang 3.6 (In-Progress) Release Notes ===================================== .. contents:: @@ -10,15 +10,15 @@ Written by the `LLVM Team <http://llvm.org/>`_ .. warning:: - These are in-progress notes for the upcoming Clang 3.5 release. You may - prefer the `Clang 3.4 Release Notes - <http://llvm.org/releases/3.4/tools/clang/docs/ReleaseNotes.html>`_. + These are in-progress notes for the upcoming Clang 3.6 release. You may + prefer the `Clang 3.5 Release Notes + <http://llvm.org/releases/3.5/tools/clang/docs/ReleaseNotes.html>`_. Introduction ============ This document contains the release notes for the Clang C/C++/Objective-C -frontend, part of the LLVM Compiler Infrastructure, release 3.5. Here we +frontend, part of the LLVM Compiler Infrastructure, release 3.6. Here we describe the status of Clang in some detail, including major improvements from the previous release and new feature work. For the general LLVM release notes, see `the LLVM @@ -36,7 +36,7 @@ main Clang web page, this document applies to the *next* release, not the current one. To see the release notes for a specific release, please see the `releases page <http://llvm.org/releases/>`_. -What's New in Clang 3.5? +What's New in Clang 3.6? ======================== Some of the major new features and improvements to Clang are listed @@ -47,14 +47,7 @@ sections with improvements to Clang's support for those languages. Major New Features ------------------ -- Clang uses the new MingW ABI - GCC 4.7 changed the mingw ABI. Clang 3.4 and older use the GCC 4.6 - ABI. Clang 3.5 and newer use the GCC 4.7 abi. - -- The __has_attribute feature test is now target-aware. Older versions of Clang - would return true when the attribute spelling was known, regardless of whether - the attribute was available to the specific target. Clang now returns true - only when the attribute pertains to the current compilation target. +- A big one. Improvements to Clang's diagnostics @@ -62,49 +55,26 @@ Improvements to Clang's diagnostics Clang's diagnostics are constantly being improved to catch more issues, explain them more clearly, and provide more accurate source information -about them. The improvements since the 3.4 release include: +about them. The improvements since the 3.5 release include: - ... New Compiler Flags ------------------ -The integrated assembler is now turned on by default on ARM (and Thumb), -so the use of the option `-fintegrated-as` is now redundant on those -architectures. This is an important move to both *eat our own dog food* -and to ease cross-compilation tremendously. - -We are aware of the problems that this may cause for code bases that -rely on specific GNU syntax or extensions, and we're working towards -getting them all fixed. Please, report bugs or feature requests if -you find anything. In the meantime, use `-fno-integrated-as` to revert -back the call to GNU assembler. - -In order to provide better diagnostics, the integrated assembler validates -inline assembly when the integrated assembler is enabled. Because this is -considered a feature of the compiler, it is controlled via the `fintegrated-as` -and `fno-integrated-as` flags which enable and disable the integrated assembler -respectively. `-integrated-as` and `-no-integrated-as` are now considered -legacy flags (but are available as an alias to prevent breaking existing users), -and users are encouraged to switch to the equivalent new feature flag. - -Deprecated flags `-faddress-sanitizer`, `-fthread-sanitizer`, -`-fcatch-undefined-behavior` and `-fbounds-checking` were removed in favor of -`-fsanitize=` family of flags. - -It is now possible to get optimization reports from the major transformation -passes via three new flags: `-Rpass`, `-Rpass-missed` and `-Rpass-analysis`. -These flags take a POSIX regular expression which indicates the name -of the pass (or passes) that should emit optimization remarks. +The option .... + New Pragmas in Clang ----------------------- -Loop optimization hints can be specified using the new `#pragma clang loop` -directive just prior to the desired loop. The directive allows vectorization, -interleaving, and unrolling to be enabled or disabled. Vector width as well -as interleave and unrolling count can be manually specified. See language -extensions for details. +Clang now supports the ... + +Windows Support +--------------- + +Clang's support for building native Windows programs ... + C Language Changes in Clang --------------------------- @@ -139,7 +109,7 @@ OpenCL C Language Changes in Clang Internal API Changes -------------------- -These are major API changes that have happened since the 3.4 release of +These are major API changes that have happened since the 3.5 release of Clang. If upgrading an external codebase that uses Clang as a library, this section should help get you past the largest hurdles of upgrading. @@ -153,16 +123,6 @@ libclang Static Analyzer --------------- -The `-analyzer-config` options are now passed from scan-build through to -ccc-analyzer and then to Clang. - -With the option `-analyzer-config stable-report-filename=true`, -instead of `report-XXXXXX.html`, scan-build/clang analyzer generate -`report-<filename>-<function, method name>-<function position>-<id>.html`. -(id = i++ for several issues found in the same function/method). - -List the function/method name in the index page of scan-build. - ... Core Analysis Improvements diff --git a/docs/ThreadSafetyAnalysis.rst b/docs/ThreadSafetyAnalysis.rst index dfef80b69f..0a1b8049e4 100644 --- a/docs/ThreadSafetyAnalysis.rst +++ b/docs/ThreadSafetyAnalysis.rst @@ -10,8 +10,8 @@ Clang Thread Safety Analysis is a C++ language extension which warns about potential race conditions in code. The analysis is completely static (i.e. compile-time); there is no run-time overhead. The analysis is still under active development, but it is mature enough to be deployed in an -industrial setting. It being developed by Google, and is used extensively -on their internal code base. +industrial setting. It is being developed by Google, in collaboration with +CERT/SEI, and is used extensively in Google's internal code base. Thread safety analysis works very much like a type system for multi-threaded programs. In addition to declaring the *type* of data (e.g. ``int``, ``float``, @@ -21,7 +21,7 @@ controlled in a multi-threaded environment. For example, if ``foo`` is a piece of code reads or writes to ``foo`` without first locking ``mu``. Similarly, if there are particular routines that should only be called by the GUI thread, then the analysis will warn if other threads call those -routines. +routines. Getting Started ---------------- @@ -34,21 +34,21 @@ Getting Started private: Mutex mu; int balance GUARDED_BY(mu); - + void depositImpl(int amount) { balance += amount; // WARNING! Cannot write balance without locking mu. } - - void withdrawImpl(int amount) EXCLUSIVE_LOCKS_REQUIRED(mu) { + + void withdrawImpl(int amount) REQUIRES(mu) { balance -= amount; // OK. Caller must have locked mu. } - + public: void withdraw(int amount) { mu.Lock(); withdrawImpl(amount); // OK. We've locked mu. } // WARNING! Failed to unlock mu. - + void transferFrom(BankAccount& b, int amount) { mu.Lock(); b.withdrawImpl(amount); // WARNING! Calling withdrawImpl() requires locking b.mu. @@ -60,23 +60,23 @@ Getting Started This example demonstrates the basic concepts behind the analysis. The ``GUARDED_BY`` attribute declares that a thread must lock ``mu`` before it can read or write to ``balance``, thus ensuring that the increment and decrement -operations are atomic. Similarly, ``EXCLUSIVE_LOCKS_REQUIRED`` declares that +operations are atomic. Similarly, ``REQUIRES`` declares that the calling thread must lock ``mu`` before calling ``withdrawImpl``. Because the caller is assumed to have locked ``mu``, it is safe to modify ``balance`` within the body of the method. -The ``depositImpl()`` method does not have ``EXCLUSIVE_LOCKS_REQUIRED``, so the +The ``depositImpl()`` method does not have ``REQUIRES``, so the analysis issues a warning. Thread safety analysis is not inter-procedural, so caller requirements must be explicitly declared. There is also a warning in ``transferFrom()``, because although the method locks ``this->mu``, it does not lock ``b.mu``. The analysis understands -that these are two separate mutexes, in two different objects. +that these are two separate mutexes, in two different objects. Finally, there is a warning in the ``withdraw()`` method, because it fails to unlock ``mu``. Every lock must have a corresponding unlock, and the analysis will detect both double locks, and double unlocks. A function is allowed to acquire a lock without releasing it, (or vice versa), but it must be annotated -as such (using ``LOCK``/``UNLOCK_FUNCTION``). +as such (using ``ACQUIRE``/``RELEASE``). Running The Analysis @@ -90,7 +90,7 @@ To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g. Note that this example assumes the presence of a suitably annotated :ref:`mutexheader` that declares which methods perform locking, -unlocking, and so on. +unlocking, and so on. Basic Concepts: Capabilities @@ -106,14 +106,14 @@ Capabilities are associated with named C++ objects which declare specific methods to acquire and release the capability. The name of the object serves to identify the capability. The most common example is a mutex. For example, if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread -to acquire the capability to access data that is protected by ``mu``. Similarly, +to acquire the capability to access data that is protected by ``mu``. Similarly, calling ``mu.Unlock()`` releases that capability. A thread may hold a capability either *exclusively* or *shared*. An exclusive capability can be held by only one thread at a time, while a shared capability can be held by many threads at the same time. This mechanism enforces a multiple-reader, single-writer pattern. Write operations to protected data -require exclusive access, while read operations require only shared access. +require exclusive access, while read operations require only shared access. At any given moment during program execution, a thread holds a specific set of capabilities (e.g. the set of mutexes that it has locked.) These act like keys @@ -121,7 +121,7 @@ or tokens that allow the thread to access a given resource. Just like physical security keys, a thread cannot make copy of a capability, nor can it destroy one. A thread can only release a capability to another thread, or acquire one from another thread. The annotations are deliberately agnostic about the -exact mechanism used to acquire and release capabilities; it assumes that the +exact mechanism used to acquire and release capabilities; it assumes that the underlying implementation (e.g. the Mutex implementation) does the handoff in an appropriate manner. @@ -144,6 +144,11 @@ and data members. Users are *strongly advised* to define macros for the various attributes; example definitions can be found in :ref:`mutexheader`, below. The following documentation assumes the use of macros. +For historical reasons, prior versions of thread safety used macro names that +were very lock-centric. These macros have since been renamed to fit a more +general capability model. The prior names are still in use, and will be +mentioned under the tag *previously* where appropriate. + GUARDED_BY(c) and PT_GUARDED_BY(c) ---------------------------------- @@ -154,47 +159,49 @@ require shared access, while write operations require exclusive access. ``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart pointers. There is no constraint on the data member itself, but the *data that -it points to* is protected by the given capability. +it points to* is protected by the given capability. .. code-block:: c++ Mutex mu; - int *p1 GUARDED_BY(mu); - int *p2 PT_GUARDED_BY(mu); - unique_ptr<int> p3 PT_GUARDED_BY(mu); - + int *p1 GUARDED_BY(mu); + int *p2 PT_GUARDED_BY(mu); + unique_ptr<int> p3 PT_GUARDED_BY(mu); + void test() { p1 = 0; // Warning! - - p2 = new int; // OK. + *p2 = 42; // Warning! - - p3.reset(new int); // OK. + p2 = new int; // OK. + *p3 = 42; // Warning! + p3.reset(new int); // OK. } -EXCLUSIVE_LOCKS_REQUIRED(...), SHARED_LOCKS_REQUIRED(...) ---------------------------------------------------------- +REQUIRES(...), REQUIRES_SHARED(...) +----------------------------------- + +*Previously*: ``EXCLUSIVE_LOCKS_REQUIRED``, ``SHARED_LOCKS_REQUIRED`` -``EXCLUSIVE_LOCKS_REQUIRED`` is an attribute on functions or methods, which +``REQUIRES`` is an attribute on functions or methods, which declares that the calling thread must have exclusive access to the given capabilities. More than one capability may be specified. The capabilities -must be held on entry to the function, *and must still be held on exit*. +must be held on entry to the function, *and must still be held on exit*. -``SHARED_LOCKS_REQUIRED`` is similar, but requires only shared access. +``REQUIRES_SHARED`` is similar, but requires only shared access. .. code-block:: c++ Mutex mu1, mu2; int a GUARDED_BY(mu1); int b GUARDED_BY(mu2); - - void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { + + void foo() REQUIRES(mu1, mu2) { a = 0; b = 0; } - + void test() { mu1.Lock(); foo(); // Warning! Requires mu2. @@ -202,32 +209,36 @@ must be held on entry to the function, *and must still be held on exit*. } -EXCLUSIVE_LOCK_FUNCTION(...), SHARED_LOCK_FUNCTION(...), UNLOCK_FUNCTION(...) ------------------------------------------------------------------------------ +ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...) +-------------------------------------------------------------------- + +*Previously*: ``EXCLUSIVE_LOCK_FUNCTION``, ``SHARED_LOCK_FUNCTION``, +``UNLOCK_FUNCTION`` -``EXCLUSIVE_LOCK_FUNCTION`` is an attribute on functions or methods, which +``ACQUIRE`` is an attribute on functions or methods, which declares that the function acquires a capability, but does not release it. The caller must not hold the given capability on entry, and it will hold the -capability on exit. ``SHARED_LOCK_FUNCTION`` is similar. +capability on exit. ``ACQUIRE_SHARED`` is similar. -``UNLOCK_FUNCTION`` declares that the function releases the given capability. -The caller must hold the capability on entry, and will no longer hold it on -exit. It does not matter whether the given capability is shared or exclusive. +``RELEASE`` and ``RELEASE_SHARED`` declare that the function releases the given +capability. The caller must hold the capability on entry, and will no longer +hold it on exit. It does not matter whether the given capability is shared or +exclusive. .. code-block:: c++ Mutex mu; MyClass myObject GUARDED_BY(mu); - - void lockAndInit() EXCLUSIVE_LOCK_FUNCTION(mu) { + + void lockAndInit() ACQUIRE(mu) { mu.Lock(); myObject.init(); } - - void cleanupAndUnlock() UNLOCK_FUNCTION(mu) { + + void cleanupAndUnlock() RELEASE(mu) { myObject.cleanup(); - } // Warning! Need to unlock mu. - + } // Warning! Need to unlock mu. + void test() { lockAndInit(); myObject.doSomething(); @@ -235,27 +246,27 @@ exit. It does not matter whether the given capability is shared or exclusive. myObject.doSomething(); // Warning, mu is not locked. } -If no argument is passed to ``(UN)LOCK_FUNCTION``, then the argument is assumed -to be ``this``, and the analysis will not check the body of the function. This -pattern is intended for use by classes which hide locking details behind an -abstract interface. E.g. +If no argument is passed to ``ACQUIRE`` or ``RELEASE``, then the argument is +assumed to be ``this``, and the analysis will not check the body of the +function. This pattern is intended for use by classes which hide locking +details behind an abstract interface. For example: .. code-block:: c++ template <class T> - class LOCKABLE Container { + class CAPABILITY("mutex") Container { private: Mutex mu; T* data; - + public: // Hide mu from public interface. - void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu.Lock(); } - void Unlock() UNLOCK_FUNCTION() { mu.Unlock(); } - + void Lock() ACQUIRE() { mu.Lock(); } + void Unlock() RELEASE() { mu.Unlock(); } + T& getElem(int i) { return data[i]; } }; - + void test() { Container<int> c; c.Lock(); @@ -264,33 +275,36 @@ abstract interface. E.g. } -LOCKS_EXCLUDED(...) -------------------- +EXCLUDES(...) +------------- + +*Previously*: ``LOCKS_EXCLUDED`` -``LOCKS_EXCLUDED`` is an attribute on functions or methods, which declares that +``EXCLUDES`` is an attribute on functions or methods, which declares that the caller must *not* hold the given capabilities. This annotation is used to prevent deadlock. Many mutex implementations are not re-entrant, so -deadlock can occur if the function in question acquires the mutex a second time. +deadlock can occur if the function acquires the mutex a second time. .. code-block:: c++ Mutex mu; int a GUARDED_BY(mu); - - void clear() LOCKS_EXCLUDED(mu) { + + void clear() EXCLUDES(mu) { mu.Lock(); a = 0; mu.Unlock(); } - + void reset() { mu.Lock(); clear(); // Warning! Caller cannot hold 'mu'. mu.Unlock(); } -Unlike ``LOCKS_REQUIRED``, ``LOCKS_EXCLUDED`` is optional. The analysis will -not issue a warning if the attribute is missing. See :ref:`limitations`. +Unlike ``REQUIRES``, ``EXCLUDES`` is optional. The analysis will not issue a +warning if the attribute is missing, which can lead to false negatives in some +cases. This issue is discussed further in :ref:`negative`. NO_THREAD_SAFETY_ANALYSIS @@ -307,16 +321,23 @@ thread-safe, but too complicated for the analysis to understand. Reasons for class Counter { Mutex mu; int a GUARDED_BY(mu); - + void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; } }; +Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the +interface of a function, and should thus be placed on the function definition +(in the ``.cc`` or ``.cpp`` file) rather than on the function declaration +(in the header). -LOCK_RETURNED(c) ----------------- -``LOCK_RETURNED`` is an attribute on functions or methods, which declares that -the function returns a reference to the given capability. It is used to +RETURN_CAPABILITY(c) +-------------------- + +*Previously*: ``LOCK_RETURNED`` + +``RETURN_CAPABILITY`` is an attribute on functions or methods, which declares +that the function returns a reference to the given capability. It is used to annotate getter methods that return mutexes. .. code-block:: c++ @@ -325,12 +346,12 @@ annotate getter methods that return mutexes. private: Mutex mu; int a GUARDED_BY(mu); - + public: - Mutex* getMu() LOCK_RETURNED(mu) { return μ } - + Mutex* getMu() RETURN_CAPABILITY(mu) { return μ } + // analysis knows that getMu() == mu - void clear() EXCLUSIVE_LOCKS_REQUIRED(getMu()) { a = 0; } + void clear() REQUIRES(getMu()) { a = 0; } }; @@ -346,11 +367,11 @@ acquired, in order to prevent deadlock. Mutex m1; Mutex m2 ACQUIRED_AFTER(m1); - + // Alternative declaration // Mutex m2; // Mutex m1 ACQUIRED_BEFORE(m2); - + void foo() { m2.Lock(); m1.Lock(); // Warning! m2 must be acquired after m1. @@ -359,36 +380,45 @@ acquired, in order to prevent deadlock. } -LOCKABLE --------- +CAPABILITY(<string>) +-------------------- -``LOCKABLE`` is an attribute on classes, which specifies that objects of the -class can be used as a capability. See the ``Container`` example given above, -or the ``Mutex`` class in :ref:`mutexheader`. +*Previously*: ``LOCKABLE`` +``CAPABILITY`` is an attribute on classes, which specifies that objects of the +class can be used as a capability. The string argument specifies the kind of +capability in error messages, e.g. ``"mutex"``. See the ``Container`` example +given above, or the ``Mutex`` class in :ref:`mutexheader`. -SCOPED_LOCKABLE ---------------- -``SCOPED_LOCKABLE`` is an attribute on classes that implement RAII-style +SCOPED_CAPABILITY +----------------- + +*Previously*: ``SCOPED_LOCKABLE`` + +``SCOPED_CAPABILITY`` is an attribute on classes that implement RAII-style locking, in which a capability is acquired in the constructor, and released in the destructor. Such classes require special handling because the constructor and destructor refer to the capability via different names; see the ``MutexLocker`` class in :ref:`mutexheader`, below. -EXCLUSIVE_TRYLOCK_FUNCTION(<bool>, ...), SHARED_TRYLOCK_FUNCTION(<bool>, ...) ------------------------------------------------------------------------------ +TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...) +--------------------------------------------------------- + +*Previously:* ``EXCLUSIVE_TRYLOCK_FUNCTION``, ``SHARED_TRYLOCK_FUNCTION`` These are attributes on a function or method that tries to acquire the given capability, and returns a boolean value indicating success or failure. The first argument must be ``true`` or ``false``, to specify which return value indicates success, and the remaining arguments are interpreted in the same way -as ``(UN)LOCK_FUNCTION``. See :ref:`mutexheader`, below, for example uses. +as ``ACQUIRE``. See :ref:`mutexheader`, below, for example uses. -ASSERT_EXCLUSIVE_LOCK(...) and ASSERT_SHARED_LOCK(...) ------------------------------------------------------- +ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...) +-------------------------------------------------------- + +*Previously:* ``ASSERT_EXCLUSIVE_LOCK``, ``ASSERT_SHARED_LOCK`` These are attributes on a function or method that does a run-time test to see whether the calling thread holds the given capability. The function is assumed @@ -410,13 +440,104 @@ Warning flags + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax. + ``-Wthread-safety-analysis``: The core analysis. + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely. - This warning can be disabled for code which has a lot of aliases. + This warning can be disabled for code which has a lot of aliases. + + ``-Wthread-safety-reference``: Checks when guarded members are passed by reference. + + +:ref:`negative` are an experimental feature, which are enabled with: + +* ``-Wthread-safety-negative``: Negative capabilities. Off by default. When new features and checks are added to the analysis, they can often introduce additional warnings. Those warnings are initially released as *beta* warnings -for a period of time, after which they are migrated to the standard analysis. +for a period of time, after which they are migrated into the standard analysis. + +* ``-Wthread-safety-beta``: New features. Off by default. + + +.. _negative: -* ``-Wthread-safety-beta``: New features. Off by default. +Negative Capabilities +===================== + +Thread Safety Analysis is designed to prevent both race conditions and +deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by +ensuring that a capability is held before reading or writing to guarded data, +and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is +*not* held. + +However, EXCLUDES is an optional attribute, and does not provide the same +safety guarantee as REQUIRES. In particular: + + * A function which acquires a capability does not have to exclude it. + * A function which calls a function that excludes a capability does not + have transitively exclude that capability. + +As a result, EXCLUDES can easily produce false negatives: + +.. code-block:: c++ + + class Foo { + Mutex mu; + + void foo() { + mu.Lock(); + bar(); // No warning. + baz(); // No warning. + mu.Unlock(); + } + + void bar() { // No warning. (Should have EXCLUDES(mu)). + mu.Lock(); + // ... + mu.Unlock(); + } + + void baz() { + bif(); // No warning. (Should have EXCLUDES(mu)). + } + + void bif() EXCLUDES(mu); + }; + + +Negative requirements are an alternative EXCLUDES that provide +a stronger safety guarantee. A negative requirement uses the REQUIRES +attribute, in conjunction with the ``!`` operator, to indicate that a capability +should *not* be held. + +For example, using ``REQUIRES(!mu)`` instead of ``EXCLUDES(mu)`` will produce +the appropriate warnings: + +.. code-block:: c++ + + class FooNeg { + Mutex mu; + + void foo() REQUIRES(!mu) { // foo() now requires !mu. + mu.Lock(); + bar(); + baz(); + mu.Unlock(); + } + + void bar() { + mu.Lock(); // WARNING! Missing REQUIRES(!mu). + // ... + mu.Unlock(); + } + + void baz() { + bif(); // WARNING! Missing REQUIRES(!mu). + } + + void bif() REQUIRES(!mu); + }; + + +Negative requirements are an experimental feature which is off by default, +because it will produce many warnings in existing code. It can be enabled +by passing ``-Wthread-safety-negative``. .. _faq: @@ -426,7 +547,10 @@ Frequently Asked Questions (Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file? -(A) Attributes should always go in the header. +(A) Attributes are part of the formal interface of a function, and should +always go in the header, where they are visible to anything that includes +the header. Attributes in the .cpp file are not visible outside of the +immediate translation unit, which leads to false negatives and false positives. (Q) "*Mutex is not locked on every path through here?*" What does that mean? @@ -436,7 +560,7 @@ Frequently Asked Questions .. _limitations: -Known Limitations +Known Limitations ================= Lexical scope @@ -448,14 +572,14 @@ capabilities must be declared before they can be used in an attribute. Use-before-declaration is okay within a single class, because attributes are parsed at the same time as method bodies. (C++ delays parsing of method bodies until the end of the class.) However, use-before-declaration is not allowed -between classes, as illustrated below. +between classes, as illustrated below. .. code-block:: c++ class Foo; class Bar { - void bar(Foo* f) EXCLUSIVE_LOCKS_REQUIRED(f->mu); // Error: mu undeclared. + void bar(Foo* f) REQUIRES(f->mu); // Error: mu undeclared. }; class Foo { @@ -474,9 +598,9 @@ Thread safety attributes follow normal C++ access restrictions, so if ``mu`` is a private member of ``c``, then it is an error to write ``c.mu`` in an attribute. -One workround is to (ab)use the ``LOCK_RETURNED`` attribute to provide a public -*name* for a private mutex, without actually exposing the underlying mutex. -For example: +One workaround is to (ab)use the ``RETURN_CAPABILITY`` attribute to provide a +public *name* for a private mutex, without actually exposing the underlying +mutex. For example: .. code-block:: c++ @@ -486,12 +610,12 @@ For example: public: // For thread safety analysis only. Does not actually return mu. - Mutex* getMu() LOCK_RETURNED(mu) { return 0; } + Mutex* getMu() RETURN_CAPABILITY(mu) { return 0; } - void doSomething() EXCLUSIVE_LOCKS_REQUIRED(mu); + void doSomething() REQUIRES(mu); }; - void doSomethingTwice(MyClass& c) EXCLUSIVE_LOCKS_REQUIRED(c.getMu()) { + void doSomethingTwice(MyClass& c) REQUIRES(c.getMu()) { // The analysis thinks that c.getMu() == c.mu c.doSomething(); c.doSomething(); @@ -506,43 +630,6 @@ as a fake getter method, which is provided only for the benefit of thread safety analysis. -False negatives on pass by reference. -------------------------------------- - -The current version of the analysis only checks operations which refer to -guarded data members directly by name. If the data members are accessed -indirectly, via a pointer or reference, then no warning is generated. Thus, -no warnings will be generated for the following code: - -.. code-block:: c++ - - Mutex mu; - int a GUARDED_BY(mu); - - void clear(int& ra) { ra = 0; } - - void test() { - int *p = &a; - *p = 0; // No warning. *p is an alias to a. - - clear(a); // No warning. 'a' is passed by reference. - } - -This issue is by far the biggest source of false negatives in the current -version of the analysis. At a fundamental level, the -false negatives are caused by the fact that annotations are attached to data -members, rather than types. The type of ``&a`` should really be -``int GUARDED_BY(mu)*``, rather than ``int*``, and the statement ``p = &a`` -should thus generate a type error. However, attaching attributes to types -would be an invasive change to the C++ type system, with potential -ramifications with respect to template instantation, function overloading, -and so on. Thus, a complete solution to this issue is simply not feasible. - -Future versions of the analysis will include better support for pointer -alias analysis, along with limited checking of guarded types, in order to -reduce the number of false negatives. - - .. _conditional_locks: No conditionally held locks. @@ -557,7 +644,7 @@ generate spurious warnings (false positives). For example: void foo() { bool b = needsToLock(); if (b) mu.Lock(); - ... // Warning! Mutex 'mu' is not held on every path through here. + ... // Warning! Mutex 'mu' is not held on every path through here. if (b) mu.Unlock(); } @@ -567,7 +654,7 @@ No checking inside constructors and destructors. The analysis currently does not do any checking inside constructors or destructors. In other words, every constructor and destructor is treated as -if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``. +if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``. The reason for this is that during initialization, only one thread typically has access to the object which is being initialized, and it is thus safe (and common practice) to initialize guarded members without acquiring any locks. @@ -577,15 +664,15 @@ Ideally, the analysis would allow initialization of guarded members inside the object being initialized or destroyed, while still enforcing the usual access restrictions on everything else. However, this is difficult to enforce in practice, because in complex pointer-based data structures, it is hard to -determine what data is "owned by" the enclosing object. +determine what data is owned by the enclosing object. No inlining. ------------ Thread safety analysis is strictly intra-procedural, just like ordinary type checking. It relies only on the declared attributes of a function, and will -not attempt to "step inside", or inline any method calls. As a result, code -such as the following will not work: +not attempt to inline any method calls. As a result, code such as the +following will not work: .. code-block:: c++ @@ -593,7 +680,7 @@ such as the following will not work: class AutoCleanup { T* object; void (T::*mp)(); - + public: AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { } ~AutoCleanup() { (object->*mp)(); } @@ -602,8 +689,8 @@ such as the following will not work: Mutex mu; void foo() { mu.Lock(); - AutoCleanup<Mutex>(&mu, &Mutex::Unlock); - ... + AutoCleanup<Mutex>(&mu, &Mutex::Unlock); + // ... } // Warning, mu is not unlocked. In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so @@ -611,42 +698,14 @@ the warning is bogus. However, thread safety analysis cannot see the unlock, because it does not attempt to inline the destructor. Moreover, there is no way to annotate the destructor, because the destructor is calling a function that is not statically known. -This pattern is simply not supported. - - -LOCKS_EXCLUDED is not transitive. ---------------------------------- - -A function which calls a method marked with LOCKS_EXCLUDED is not required to -put LOCKS_EXCLUDED in its own interface. LOCKS_EXCLUDED behaves differently -from LOCKS_REQUIRED in this respect, and it can result in false negatives: - -.. code-block:: c++ - - class Foo { - Mutex mu; - - void foo() { - mu.Lock(); - bar(); // No warning - mu.Unlock(); - } - - void bar() { baz(); } // No warning. (Should have LOCKS_EXCLUDED(mu).) - - void baz() LOCKS_EXCLUDED(mu); - }; - -The lack of transitivity is due to the fact that LOCKS_EXCLUDED can easily -break encapsulation; it would be a bad idea to require functions to list the -names private locks which happen to be acquired internally. +This pattern is simply not supported. No alias analysis. ------------------ The analysis currently does not track pointer aliases. Thus, there can be -false positives if two pointers both point to the same mutex. +false positives if two pointers both point to the same mutex. .. code-block:: c++ @@ -655,13 +714,13 @@ false positives if two pointers both point to the same mutex. Mutex* mu; public: - MutexUnlocker(Mutex* m) UNLOCK_FUNCTION(m) : mu(m) { mu->Unlock(); } - ~MutexUnlocker() EXCLUSIVE_LOCK_FUNCTION(mu) { mu->Lock(); } + MutexUnlocker(Mutex* m) RELEASE(m) : mu(m) { mu->Unlock(); } + ~MutexUnlocker() ACQUIRE(mu) { mu->Lock(); } }; Mutex mutex; - void test() EXCLUSIVE_LOCKS_REQUIRED(mutex) { - { + void test() REQUIRES(mutex) { + { MutexUnlocker munl(&mutex); // unlocks mutex doSomeIO(); } // Warning: locks munl.mu @@ -669,14 +728,14 @@ false positives if two pointers both point to the same mutex. The MutexUnlocker class is intended to be the dual of the MutexLocker class, defined in :ref:`mutexheader`. However, it doesn't work because the analysis -doesn't know that munl.mu == mutex. The SCOPED_LOCKABLE attribute handles -aliasing +doesn't know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles +aliasing for MutexLocker, but does so only for that particular pattern. ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented. ------------------------------------------------------------------------- -To be fixed in a future update. +To be fixed in a future update. .. _mutexheader: @@ -688,14 +747,15 @@ Thread safety analysis can be used with any threading library, but it does require that the threading API be wrapped in classes and methods which have the appropriate annotations. The following code provides ``mutex.h`` as an example; these methods should be filled in to call the appropriate underlying -implementation. +implementation. .. code-block:: c++ + #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H #define THREAD_SAFETY_ANALYSIS_MUTEX_H - + // Enable thread safety attributes only with clang. // The attributes can be safely erased when compiling with other compilers. #if defined(__clang__) && (!defined(SWIG)) @@ -703,116 +763,185 @@ implementation. #else #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op #endif - + #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) - + + #define CAPABILITY(x) \ + THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) + + #define SCOPED_CAPABILITY \ + THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) + #define GUARDED_BY(x) \ THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) - - #define GUARDED_VAR \ - THREAD_ANNOTATION_ATTRIBUTE__(guarded) - + #define PT_GUARDED_BY(x) \ THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) - - #define PT_GUARDED_VAR \ - THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded) - - #define ACQUIRED_AFTER(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__)) - + #define ACQUIRED_BEFORE(...) \ THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__)) - - #define EXCLUSIVE_LOCKS_REQUIRED(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) - - #define SHARED_LOCKS_REQUIRED(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) - - #define LOCKS_EXCLUDED(...) \ + + #define ACQUIRED_AFTER(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__)) + + #define REQUIRES(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__)) + + #define REQUIRES_SHARED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__)) + + #define ACQUIRE(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__)) + + #define ACQUIRE_SHARED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__)) + + #define RELEASE(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__)) + + #define RELEASE_SHARED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__)) + + #define TRY_ACQUIRE(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__)) + + #define TRY_ACQUIRE_SHARED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__)) + + #define EXCLUDES(...) \ THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__)) - - #define LOCK_RETURNED(x) \ + + #define ASSERT_CAPABILITY(x) \ + THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) + + #define ASSERT_SHARED_CAPABILITY(x) \ + THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) + + #define RETURN_CAPABILITY(x) \ THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) - - #define LOCKABLE \ - THREAD_ANNOTATION_ATTRIBUTE__(lockable) - - #define SCOPED_LOCKABLE \ - THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) - - #define EXCLUSIVE_LOCK_FUNCTION(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) - - #define SHARED_LOCK_FUNCTION(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) - - #define ASSERT_EXCLUSIVE_LOCK(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__)) - - #define ASSERT_SHARED_LOCK(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__)) - - #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) - - #define SHARED_TRYLOCK_FUNCTION(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) - - #define UNLOCK_FUNCTION(...) \ - THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) - + #define NO_THREAD_SAFETY_ANALYSIS \ THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) - - + + // Defines an annotated interface for mutexes. // These methods can be implemented to use any internal mutex implementation. - class LOCKABLE Mutex { + class CAPABILITY("mutex") Mutex { public: // Acquire/lock this mutex exclusively. Only one thread can have exclusive // access at any one time. Write operations to guarded data require an // exclusive lock. - void Lock() EXCLUSIVE_LOCK_FUNCTION(); - + void Lock() ACQUIRE(); + // Acquire/lock this mutex for read operations, which require only a shared // lock. This assumes a multiple-reader, single writer semantics. Multiple - // threads may acquire the mutex simultaneously as readers, but a writer must - // wait for all of them to release the mutex before it can acquire it - // exclusively. - void ReaderLock() SHARED_LOCK_FUNCTION(); - - // Release/unlock the mutex, regardless of whether it is exclusive or shared. - void Unlock() UNLOCK_FUNCTION(); - + // threads may acquire the mutex simultaneously as readers, but a writer + // must wait for all of them to release the mutex before it can acquire it + // exclusively. + void ReaderLock() ACQUIRE_SHARED(); + + // Release/unlock an exclusive mutex. + void Unlock() RELEASE(); + + // Release/unlock a shared mutex. + void ReaderUnlock() RELEASE_SHARED(); + // Try to acquire the mutex. Returns true on success, and false on failure. - bool TryLock() EXCLUSIVE_TRYLOCK_FUNCTION(true); - + bool TryLock() TRY_ACQUIRE(true); + // Try to acquire the mutex for read operations. - bool ReaderTryLock() SHARED_TRYLOCK_FUNCTION(true); - + bool ReaderTryLock() TRY_ACQUIRE_SHARED(true); + // Assert that this mutex is currently held by the calling thread. - void AssertHeld() ASSERT_EXCLUSIVE_LOCK(); - - // Assert that is mutex is currently held for read operations. - void AssertReaderHeld() ASSERT_SHARED_LOCK(); + void AssertHeld() ASSERT_CAPABILITY(this); + + // Assert that is mutex is currently held for read operations. + void AssertReaderHeld() ASSERT_SHARED_CAPABILITY(this); }; - - + + // MutexLocker is an RAII class that acquires a mutex in its constructor, and - // releases it in its destructor. - class SCOPED_LOCKABLE MutexLocker { + // releases it in its destructor. + class SCOPED_CAPABILITY MutexLocker { private: Mutex* mut; - + public: - MutexLocker(Mutex *mu) EXCLUSIVE_LOCK_FUNCTION(mu) : mut(mu) { + MutexLocker(Mutex *mu) ACQUIRE(mu) : mut(mu) { mu->Lock(); - } - ~MutexLocker() UNLOCK_FUNCTION() { + } + ~MutexLocker() RELEASE() { mut->Unlock(); } }; - + + + #ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES + // The original version of thread safety analysis the following attribute + // definitions. These use a lock-based terminology. They are still in use + // by existing thread safety code, and will continue to be supported. + + // Deprecated. + #define PT_GUARDED_VAR \ + THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded) + + // Deprecated. + #define GUARDED_VAR \ + THREAD_ANNOTATION_ATTRIBUTE__(guarded) + + // Replaced by REQUIRES + #define EXCLUSIVE_LOCKS_REQUIRED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) + + // Replaced by REQUIRES_SHARED + #define SHARED_LOCKS_REQUIRED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) + + // Replaced by CAPABILITY + #define LOCKABLE \ + THREAD_ANNOTATION_ATTRIBUTE__(lockable) + + // Replaced by SCOPED_CAPABILITY + #define SCOPED_LOCKABLE \ + THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) + + // Replaced by ACQUIRE + #define EXCLUSIVE_LOCK_FUNCTION(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) + + // Replaced by ACQUIRE_SHARED + #define SHARED_LOCK_FUNCTION(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) + + // Replaced by RELEASE and RELEASE_SHARED + #define UNLOCK_FUNCTION(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) + + // Replaced by TRY_ACQUIRE + #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) + + // Replaced by TRY_ACQUIRE_SHARED + #define SHARED_TRYLOCK_FUNCTION(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) + + // Replaced by ASSERT_CAPABILITY + #define ASSERT_EXCLUSIVE_LOCK(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__)) + + // Replaced by ASSERT_SHARED_CAPABILITY + #define ASSERT_SHARED_LOCK(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__)) + + // Replaced by EXCLUDE_CAPABILITY. + #define LOCKS_EXCLUDED(...) \ + THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__)) + + // Replaced by RETURN_CAPABILITY + #define LOCK_RETURNED(x) \ + THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) + + #endif // USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES + #endif // THREAD_SAFETY_ANALYSIS_MUTEX_H + diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 90a0e53b50..9d8e978ed3 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -73,7 +73,7 @@ Basic Usage Intro to how to use a C compiler for newbies. compile + link compile then link debug info enabling optimizations -picking a language to use, defaults to C99 by default. Autosenses based +picking a language to use, defaults to C11 by default. Autosenses based on extension. using a makefile Command Line Options @@ -481,7 +481,7 @@ TODO: Generate this from tblgen. Define one anchor per warning group. Warn about an unusable copy constructor when binding a reference to a temporary. - This option, which defaults to on, enables warnings about binding a + This option enables warnings about binding a reference to a temporary when the temporary doesn't have a usable copy constructor. For example: @@ -577,17 +577,12 @@ feature. Current limitations ^^^^^^^^^^^^^^^^^^^ -1. For :option:`-Rpass` to provide column information, you - need to enable it explicitly. That is, you need to add - :option:`-gcolumn-info`. If you omit this, remarks will only show - line information. - -2. Optimization remarks that refer to function names will display the +1. Optimization remarks that refer to function names will display the mangled name of the function. Since these remarks are emitted by the back end of the compiler, it does not know anything about the input language, nor its mangling rules. -3. Some source locations are not displayed correctly. The front end has +2. Some source locations are not displayed correctly. The front end has a more detailed source location tracking than the locations included in the debug info (e.g., the front end can locate code inside macro expansions). However, the locations used by :option:`-Rpass` are @@ -982,6 +977,8 @@ are listed below. - ``-fsanitize=function``: Indirect call of a function through a function pointer of the wrong type (Linux, C++ and x86/x86_64 only). - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. + - ``-fsanitize=nonnull-attribute``: Passing null pointer as a function + parameter which is declared to never be null. - ``-fsanitize=null``: Use of a null pointer or creation of a null reference. - ``-fsanitize=object-size``: An attempt to use bytes which the @@ -991,6 +988,8 @@ are listed below. more problems at higher optimization levels. - ``-fsanitize=return``: In C++, reaching the end of a value-returning function without returning a value. + - ``-fsanitize=returns-nonnull-attribute``: Returning null pointer + from a function which is declared to never return null. - ``-fsanitize=shift``: Shift operators where the amount shifted is greater or equal to the promoted bit-width of the left hand side or less than zero, or where the left hand side is negative. For a @@ -1116,6 +1115,37 @@ are listed below. This option restricts the generated code to use general registers only. This only applies to the AArch64 architecture. +**-f[no-]max-unknown-pointer-align=[number]** + Instruct the code generator to not enforce a higher alignment than the given + number (of bytes) when accessing memory via an opaque pointer or reference. + This cap is ignored when directly accessing a variable or when the pointee + type has an explicit “aligned” attribute. + + The value should usually be determined by the properties of the system allocator. + Some builtin types, especially vector types, have very high natural alignments; + when working with values of those types, Clang usually wants to use instructions + that take advantage of that alignment. However, many system allocators do + not promise to return memory that is more than 8-byte or 16-byte-aligned. Use + this option to limit the alignment that the compiler can assume for an arbitrary + pointer, which may point onto the heap. + + This option does not affect the ABI alignment of types; the layout of structs and + unions and the value returned by the alignof operator remain the same. + + This option can be overridden on a case-by-case basis by putting an explicit + “aligned” alignment on a struct, union, or typedef. For example: + + .. code-block:: console + + #include <immintrin.h> + // Make an aligned typedef of the AVX-512 16-int vector type. + typedef __v16si __aligned_v16si __attribute__((aligned(64))); + + void initialize_vector(__aligned_v16si *v) { + // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the + // value of -fmax-unknown-pointer-align. + } + Profile Guided Optimization --------------------------- @@ -1444,9 +1474,12 @@ Differences between various standard modes ------------------------------------------ clang supports the -std option, which changes what language mode clang -uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and -various aliases for those modes. If no -std option is specified, clang -defaults to gnu99 mode. +uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, +gnu11, and various aliases for those modes. If no -std option is +specified, clang defaults to gnu11 mode. Many C99 and C11 features are +supported in earlier modes as a conforming extension, with a warning. Use +``-pedantic-errors`` to request an error if a feature from a later standard +revision is used in an earlier mode. Differences between all ``c*`` and ``gnu*`` modes: @@ -1484,6 +1517,11 @@ Differences between ``*89`` and ``*99`` modes: in ``*89`` modes. - Some warnings are different. +Differences between ``*99`` and ``*11`` modes: + +- Warnings for use of C11 features are disabled. +- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. + c94 mode is identical to c89 mode except that digraphs are enabled in c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). @@ -1811,55 +1849,94 @@ Execute ``clang-cl /?`` to see a list of supported options: :: - /? Display available options - /c Compile only - /D <macro[=value]> Define macro - /fallback Fall back to cl.exe if clang-cl fails to compile - /FA Output assembly code file during compilation - /Fa<file or directory> Output assembly code to this file during compilation - /Fe<file or directory> Set output executable file or directory (ends in / or \) - /FI<value> Include file before parsing - /Fo<file or directory> Set output object file, or directory (ends in / or \) - /GF- Disable string pooling - /GR- Disable RTTI - /GR Enable RTTI - /help Display available options - /I <dir> Add directory to include search path - /J Make char type unsigned - /LDd Create debug DLL - /LD Create DLL - /link <options> Forward options to the linker - /MDd Use DLL debug run-time - /MD Use DLL run-time - /MTd Use static debug run-time - /MT Use static run-time - /Ob0 Disable inlining - /Od Disable optimization - /Oi- Disable use of builtin functions - /Oi Enable use of builtin functions - /Os Optimize for size - /Ot Optimize for speed - /Ox Maximum optimization - /Oy- Disable frame pointer omission - /Oy Enable frame pointer omission - /O<n> Optimization level - /P Only run the preprocessor - /showIncludes Print info about included files to stderr - /TC Treat all source files as C - /Tc <filename> Specify a C source file - /TP Treat all source files as C++ - /Tp <filename> Specify a C++ source file - /U <macro> Undefine macro - /W0 Disable all warnings - /W1 Enable -Wall - /W2 Enable -Wall - /W3 Enable -Wall - /W4 Enable -Wall - /Wall Enable -Wall - /WX- Do not treat warnings as errors - /WX Treat warnings as errors - /w Disable all warnings - /Zs Syntax-check only + CL.EXE COMPATIBILITY OPTIONS: + /? Display available options + /arch:<value> Set architecture for code generation + /C Don't discard comments when preprocessing + /c Compile only + /D <macro[=value]> Define macro + /EH<value> Exception handling model + /EP Disable linemarker output and preprocess to stdout + /E Preprocess to stdout + /fallback Fall back to cl.exe if clang-cl fails to compile + /FA Output assembly code file during compilation + /Fa<file or directory> Output assembly code to this file during compilation + /Fe<file or directory> Set output executable file or directory (ends in / or \) + /FI <value> Include file before parsing + /Fi<file> Set preprocess output file name + /Fo<file or directory> Set output object file, or directory (ends in / or \) + /GF- Disable string pooling + /GR- Disable emission of RTTI data + /GR Enable emission of RTTI data + /Gw- Don't put each data item in its own section + /Gw Put each data item in its own section + /Gy- Don't put each function in its own section + /Gy Put each function in its own section + /help Display available options + /I <dir> Add directory to include search path + /J Make char type unsigned + /LDd Create debug DLL + /LD Create DLL + /link <options> Forward options to the linker + /MDd Use DLL debug run-time + /MD Use DLL run-time + /MTd Use static debug run-time + /MT Use static run-time + /Ob0 Disable inlining + /Od Disable optimization + /Oi- Disable use of builtin functions + /Oi Enable use of builtin functions + /Os Optimize for size + /Ot Optimize for speed + /Ox Maximum optimization + /Oy- Disable frame pointer omission + /Oy Enable frame pointer omission + /O<n> Optimization level + /P Preprocess to file + /showIncludes Print info about included files to stderr + /TC Treat all source files as C + /Tc <filename> Specify a C source file + /TP Treat all source files as C++ + /Tp <filename> Specify a C++ source file + /U <macro> Undefine macro + /vd<value> Control vtordisp placement + /vmb Use a best-case representation method for member pointers + /vmg Use a most-general representation for member pointers + /vmm Set the default most-general representation to multiple inheritance + /vms Set the default most-general representation to single inheritance + /vmv Set the default most-general representation to virtual inheritance + /W0 Disable all warnings + /W1 Enable -Wall + /W2 Enable -Wall + /W3 Enable -Wall + /W4 Enable -Wall + /Wall Enable -Wall + /WX- Do not treat warnings as errors + /WX Treat warnings as errors + /w Disable all warnings + /Zi Enable debug information + /Zp Set the default maximum struct packing alignment to 1 + /Zp<value> Specify the default maximum struct packing alignment + /Zs Syntax-check only + + OPTIONS: + -### Print (but do not run) the commands to run for this compilation + -fms-compatibility-version=<value> + Dot-separated value representing the Microsoft compiler version + number to report in _MSC_VER (0 = don't define it (default)) + -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't + define it (default)) + -fsanitize-blacklist=<value> + Path to blacklist file for sanitizers + -fsanitize=<check> Enable runtime instrumentation for bug detection: address (memory + errors) | thread (race detection) | undefined (miscellaneous + undefined behavior) + -mllvm <value> Additional arguments to forward to LLVM's option processing + -Qunused-arguments Don't emit warning for unused driver arguments + --target=<value> Generate code for the given target + -v Show commands to run and use verbose output + -W<warning> Enable the specified warning + -Xclang <arg> Pass <arg> to the clang compiler The /fallback Option ^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/conf.py b/docs/conf.py index 1963a05385..7c2ef2aed0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2007-2014, The Clang Team' # built documents. # # The short X.Y version. -version = '3.5' +version = '3.6' # The full version, including alpha/beta/rc tags. -release = '3.5' +release = '3.6' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. |