diff options
author | George Karpenkov <ekarpenkov@apple.com> | 2019-01-11 18:02:08 +0000 |
---|---|---|
committer | George Karpenkov <ekarpenkov@apple.com> | 2019-01-11 18:02:08 +0000 |
commit | bc7927d208280def86be0f33a509024b46d77f42 (patch) | |
tree | be85e7f3a404d82e17dba7bc44b61a973276943d /include/clang/Basic/AttrDocs.td | |
parent | fb2ad0413c5c2c71e9e96bb7004acd4f4de32bf2 (diff) |
[attributes] Extend os_returns_(not_?)_retained attributes to parameters
When applied to out-parameters, the attributes specify the expected lifetime of the written-into object.
Additionally, introduce OSReturnsRetainedOn(Non)Zero attributes, which
specify that an ownership transfer happens depending on a return code.
Differential Revision: https://reviews.llvm.org/D56292
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@350942 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'include/clang/Basic/AttrDocs.td')
-rw-r--r-- | include/clang/Basic/AttrDocs.td | 15 |
1 files changed, 15 insertions, 0 deletions
diff --git a/include/clang/Basic/AttrDocs.td b/include/clang/Basic/AttrDocs.td index aae2d1ddfc..5773a92c9c 100644 --- a/include/clang/Basic/AttrDocs.td +++ b/include/clang/Basic/AttrDocs.td @@ -888,6 +888,21 @@ Similar to ``__attribute__((ns_consumes_self))``, ``__attribute__((os_consumes_this))`` specifies that the method call consumes the reference to "this" (e.g., when attaching it to a different object supplied as a parameter). +Out parameters (parameters the function is meant to write into, +either via pointers-to-pointers or references-to-pointers) +may be annotated with ``__attribute__((os_returns_retained))`` +or ``__attribute__((os_returns_not_retained))`` which specifies that the object +written into the out parameter should (or respectively should not) be released +after use. +Since often out parameters may or may not be written depending on the exit +code of the function, +annotations ``__attribute__((os_returns_retained_on_zero))`` +and ``__attribute__((os_returns_retained_on_non_zero))`` specify that +an out parameter at ``+1`` is written if and only if the function returns a zero +(respectively non-zero) error code. +Observe that return-code-dependent out parameter annotations are only +available for retained out parameters, as non-retained object do not have to be +released by the callee. These attributes are only used by the Clang Static Analyzer. The family of attributes ``X_returns_X_retained`` can be added to functions, |