2 .TH control 3 "28 April 2023" "Straylight/Edgeware" "FINALLY macro package"
4 FINALLY \- defer execution until scope exit
7 .B "#include <finally.h>"
10 .BI FINALLY_TAGGED( tag ", " stmt );
15 .SS "General usage of FINALLY"
18 macro arranges that the statement
20 should be executed when control leaves the immediately enclosing scope,
21 whether this is by just running off the end, or by explicit control
28 If a scope contains multiple
30 calls, then the statements are executed in reverse order.
32 In particular, if the macro call is placed at top-level within a
35 is executed when the function returns, either as a result of a
37 statement, or by running off the end of the function body.
39 With GNU-like compilers, you can arrange for the statement to be
40 executed when control escapes the scope as the result of a C++ exception
47 be executed if control leaves the scope as a result of
49 or similar. It also won't be executed if control `leaves' as a result
52 or similar; but that's almost certainly what you want.
56 macro's expansion is syntactically one or more declarations. In C89
57 code, therefore, it must appear at the head of a block, before any
58 statements. In C99 or later, it may appear anywhere in a block.
59 However, because it may expand to more than one declaration, it is not
64 .SS "Macros and FINALLY_TAGGED"
67 can occur on any given line of source code. In particular, this
68 rule forbids macros which expand into more than one use of
70 since the macro expansions will cause them all to be credited to the
71 line holding the original expansion site. To avoid trouble, macro
76 on the same source line must have a distinct
78 argument, which may be any identifier.
80 .SS "Nonlocal transfers, and thread and process exits"
83 be executed if control leaves the scope as a result of
85 or similar. It also won't be executed if control `leaves' as a result
96 time. Almost all uses of
98 are to release process-local resources such as memory, file descriptors
99 or locks, or something else similar. The kernel will release these by
100 itself when the process exits, because leaking resources when processes
101 crash would just be too awful to consider. All you'd achieve by
102 carefully freeing memory prior to
104 would be to waste time.
106 .SS "Setup and configuration"
109 macro uses compiler-specific techniques. Not only does it need
110 different implementations on different compilers, but it may require
111 unusual compiler options and runtime support libraries to work.
115 header can work portably under C++11 or later, using RAII and lambdas:
116 idiomatic C++ doesn't benefit much from this, but the facility is there
117 anyway. If the header detects that such a compiler is in use (the macro
119 is defined to a value greater than or equal to 201103), then it will use
120 the C++-specific implementation.
122 Otherwise, the header checks the value of
123 .BR FINALLY_CONFIG_FLAVOUR :
124 it should be one of the following options.
127 No support. An error is reported (using
130 .B GCC_NESTED_FUNCTIONS
131 Use the GNU C Compiler's support for nested functions and the
133 function attribute. Note that this use of nested functions does not
134 involve the use of trampolines, and does not require an executable
135 stack. (This is verified as part of the package tests.)
138 .B FINALLY_CONFIG_FLAVOUR
141 guesses one of these flavours based on the compiler version and other
142 predefined macros. This guess may be wrong, and things may not work
143 anyway because necessary compiler options or libraries aren't available.
145 The best way to set everything up correctly is to use the provided
147 Autoconf macro. It will define
148 .B FINALLY_CONFIG_FLAVOUR
149 to a suitable value, and also report necessary compiler flags and
154 makefile variables. See the
156 file's internal documentation for the details.
159 The selection of supported compilers is extremely limited.
162 Mark Wooding, <mdw@distorted.org.uk>