Author: Richard Smith Date: 2021-03-22T15:03:42-07:00 New Revision: 5fab60377c1afec872235747d99ef6b7c508e4f8
URL: https://github.com/llvm/llvm-project/commit/5fab60377c1afec872235747d99ef6b7c508e4f8 DIFF: https://github.com/llvm/llvm-project/commit/5fab60377c1afec872235747d99ef6b7c508e4f8.diff LOG: Attempt to further improve the documentation for the [[clang::lifetimebound]] attribute. Differential Revision: https://reviews.llvm.org/D99117 Added: Modified: clang/include/clang/Basic/AttrDocs.td Removed: ################################################################################ diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index 7f30c6300e91..4e4d419bd03b 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -3026,19 +3026,31 @@ It is only supported when using the Microsoft C++ ABI. def LifetimeBoundDocs : Documentation { let Category = DocCatFunction; let Content = [{ -The ``lifetimebound`` attribute indicates that a resource owned by -a function parameter or implicit object parameter -is retained by the return value of the annotated function -(or, for a parameter of a constructor, in the value of the constructed object). -It is only supported in C++. - -This attribute causes warnings to be produced if a temporary object does not -live long enough. For example: +The ``lifetimebound`` attribute on a function parameter or implicit object +parameter indicates that objects that are referred to by that parameter may +also be referred to by the return value of the annotated function (or, for a +parameter of a constructor, by the value of the constructed object). It is only +supported in C++. + +By default, a reference is considered to refer to its referenced object, a +pointer is considered to refer to its pointee, a ``std::initializer_list<T>`` +is considered to refer to its underlying array, and aggregates (arrays and +simple ``struct``s) are considered to refer to all objects that their +subobjects refer to, recursively. + +Clang warns if it is able to detect that an object or reference refers to +another object with a shorter lifetime. For example, Clang will warn if a +function returns a reference to a local variable, or if a reference is bound to +a temporary object whose lifetime is not extended. By using the +``lifetimebound`` attribute, this determination can be extended to look through +user-declared functions. For example: .. code-block:: c++ + // Returns m[key] if key is present, or default_value if not. template<typename T, typename U> - const U &get_or_default(std::map<T, U> &m, const T &key, + const U &get_or_default(const std::map<T, U> &m [[clang::lifetimebound]], + const T &key, /* note, not lifetimebound */ const U &default_value [[clang::lifetimebound]]); std::map<std::string, std::string> m; @@ -3046,11 +3058,9 @@ live long enough. For example: // will be destroyed at the end of the full-expression const std::string &val = get_or_default(m, "foo"s, "bar"s); -When applied to a reference parameter, the referenced object is assumed to be -retained by the return value of the function. When applied to a non-reference -parameter (for example, a pointer or a class type), all temporaries referenced -by the parameter are assumed to be retained by the return value of the -function. + // No warning in this case. + std::string def_val = "bar"s; + const std::string &val = get_or_default(m, "foo"s, def_val); The attribute can be applied to the implicit ``this`` parameter of a member function by writing the attribute after the function type: _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits