From 8dc13957cb1752b6a90e299d016e09bb98b0df54 Mon Sep 17 00:00:00 2001 From: Nick Desaulniers Date: Thu, 1 Jun 2023 11:18:03 -0700 Subject: [PATCH] [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 --- clang/include/clang/Basic/Attr.td | 2 +- clang/include/clang/Basic/AttrDocs.td | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td index e114391..3fdd84d 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]; let Subjects = SubjectList<[LocalVar]>; - let Documentation = [Undocumented]; + let Documentation = [CleanupDocs]; } def CmseNSEntry : InheritableAttr, TargetSpecificAttr { diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index d719f46..e3d8323 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. +}]; +} -- 2.7.4