Author: Nick Desaulniers Date: 2023-06-01T11:24:53-07:00 New Revision: 8dc13957cb1752b6a90e299d016e09bb98b0df54
URL: https://github.com/llvm/llvm-project/commit/8dc13957cb1752b6a90e299d016e09bb98b0df54 DIFF: https://github.com/llvm/llvm-project/commit/8dc13957cb1752b6a90e299d016e09bb98b0df54.diff LOG: [clang][docs] document __attribute__((cleanup())) GNU C extension Provide an example of how to use this extension and more importantly, document that cleanup functions are run in reverse nested order. Reviewed By: erichkeane Differential Revision: https://reviews.llvm.org/D151732 Added: Modified: clang/include/clang/Basic/Attr.td clang/include/clang/Basic/AttrDocs.td Removed: ################################################################################ diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td index e11439158fc0..3fdd84d2b13b 100644 --- a/clang/include/clang/Basic/Attr.td +++ b/clang/include/clang/Basic/Attr.td @@ -1097,7 +1097,7 @@ def Cleanup : InheritableAttr { let Spellings = [GCC<"cleanup">]; let Args = [DeclArgument<Function, "FunctionDecl">]; let Subjects = SubjectList<[LocalVar]>; - let Documentation = [Undocumented]; + let Documentation = [CleanupDocs]; } def CmseNSEntry : InheritableAttr, TargetSpecificAttr<TargetARM> { diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index d719f4691251..e3d83234b316 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -7023,3 +7023,30 @@ This attribute may be attached to a function pointer type, where it modifies its underlying representation to be a WebAssembly ``funcref``. }]; } + +def CleanupDocs : Documentation { + let Category = DocCatType; + let Content = [{ +This attribute allows a function to be run when a local variable goes out of +scope. The attribute takes the identifier of a function with a parameter type +that is a pointer to the type with the attribute. + +.. code-block:: c + + static void foo (int *) { ... } + static void bar (int *) { ... } + void baz (void) { + int x __attribute__((cleanup(foo))); + { + int y __attribute__((cleanup(bar))); + } + } + +The above example will result in a call to ``bar`` being passed the address of +`y`` when ``y`` goes out of scope, then a call to ``foo`` being passed the +address of ``x`` when ``x`` goes out of scope. If two or more variables share +the same scope, their ``cleanup`` callbacks are invoked in the reverse order +the variables were declared in. It is not possible to check the return value +(if any) of these ``cleanup`` callback functions. +}]; +} _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
