Debian Codegraph @

include/deal.II/base/scope_exit.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_scope_exit_h
16 #define dealii_scope_exit_h
17
18 #include <deal.II/base/config.h>
19
20 #include <functional>
21
22
23 DEAL_II_NAMESPACE_OPEN
24
25 /**
26 * A class that stores a function object (typically a lambda function)
27 * that is executed in the destructor of the current object. Such
28 * a class is useful to execute an action *whenever* the function in
29 * which the object is declared exits, whether that is by falling
30 * off the end of the function, an explicit `return` statement, or
31 * because an exception is thrown. In all of these cases, the
32 * destructors of all local objects are run, and the destructor
33 * of the ScopeExit object then executes the stored action.
34 *
35 * The typical use case is that we want to perform a clean-up
36 * action. For example, let's say that we want to print to the
37 * console that we're leaving a long-running and potentially
38 * complicated function. This could be achieved as follows:
39 * @code
40 * void long_running_and_complex_function ()
41 * {
42 * ScopeExit scope_exit_action ([]() { std::cout << "Leaving the long
43 * running function!\n"; });
44 *
45 * for (...)
46 * {
47 * // some 800 lines of complex code
48 * }
49 * @endcode
50 * The point here is that in order to have the message printed, we do not
51 * need to go through the 800 lines of complex code and find all places
52 * where either there is an explicit `return` statement, or where a
53 * function that is called may throw an exception that we do not explicitly
54 * catch: *Any* way the current function is exited will lead to the
55 * message being printed.
56 *
57 * A perhaps more instructive example is the following (from some past
58 * iteration of the implementation of SUNDIALS::KINSOL::solve()):
59 * @code
60 * status = KINSol(kinsol_mem, solution, data.strategy, u_scale, f_scale);
61 *
62 * if (pending_exception)
63 * {
64 * try
65 * {
66 * std::rethrow_exception(pending_exception);
67 * }
68 * catch (const RecoverableUserCallbackError &exc)
69 * {
70 * pending_exception = nullptr;
71 * if (status == 0)
72 * ; // just eat the exception
73 * else
74 * throw;
75 * }
76 * catch (...)
77 * {
78 * pending_exception = nullptr;
79 * throw;
80 * }
81 * }
82 * AssertKINSOL(status);
83 *
84 * internal::copy(initial_guess_and_solution, solution);
85 * // Free the vectors which are no longer used.
86 * #ifdef DEAL_II_WITH_MPI
87 * if (is_serial_vector<VectorType>::value == false)
88 * {
89 * N_VDestroy_Parallel(solution);
90 * N_VDestroy_Parallel(u_scale);
91 * N_VDestroy_Parallel(f_scale);
92 * }
93 * else
94 * #endif
95 * {
96 * N_VDestroy_Serial(solution);
97 * N_VDestroy_Serial(u_scale);
98 * N_VDestroy_Serial(f_scale);
99 * }
100 * long nniters;
101 * status = KINGetNumNonlinSolvIters(kinsol_mem, &nniters);
102 * AssertKINSOL(status);
103 * if (J != nullptr)
104 * SUNMatDestroy(J);
105 * if (LS != nullptr)
106 * SUNLinSolFree(LS);
107 * KINFree(&kinsol_mem);
108 * return static_cast<unsigned int>(nniters);
109 * @endcode
110 *
111 * This code has a bug: At the bottom, it contains clean-up code
112 * that destroys a variety of objects created throughout the life of
113 * the function we are looking at. Because SUNDIALS is a library
114 * written in C, objects such as `solution`, `u_scale`, `J`, `LS`,
115 * etc., are really just regular pointers that need to be explicitly
116 * freed. But this does not happen in the places higher up where we
117 * `throw` an exception and don't catch it again immediately. One
118 * might be tempted to just copy the clean-up code to right before the
119 * `std::rethrow_exception` statement, but there is a path through the
120 * `catch` clauses marked with "just eat the exception" that ends up
121 * returning control flow back to the regular path, and if we hit this
122 * path, we would call the clean-up functions *twice* -- also not what
123 * we want. The upshot of this kind of example is that there are cases
124 * where it is quite difficult to say where exactly a function will
125 * exit and where the clean-up code needs to be placed; it is far
126 * easier to write it only once and let the compiler determine where
127 * it needs to be called, via a class such as the current one.
128 *
129 * The function is conceptually very similar to the
130 * [std::experimental::scope_exit](https://en.cppreference.com/w/cpp/experimental/scope_exit)
131 * class template that may find its way into a future C++ standard.
132 */
133 class ScopeExit
134 {
135 public:
136 /**
137 * Constructor. Takes a function object that is to be executed at the
138 * place where the current object goes out of scope as argument.
139 */
140 explicit ScopeExit(const std::function<void()> &exit_function);
141
142 /**
143 * Copy constructor. These kinds of objects cannot be copied, so the
144 * constructor is deleted.
145 */
146 ScopeExit(const ScopeExit &) = delete;
147
148 /**
149 * Destructor. Execute the stored action.
150 */
151 ~ScopeExit();
152
153 /**
154 * Copy operator. These kinds of objects cannot be copied, so the
155 * operator is deleted.
156 */
157 ScopeExit &
158 operator=(const ScopeExit &) = delete;
159
160 private:
161 /**
162 * A copy of the function to be executed.
163 */
164 const std::function<void()> exit_function;
165 };
166
167
168
169 inline ScopeExit::ScopeExit(const std::function<void()> &exit_function)
170 : exit_function(exit_function)
171 {}
172
173
174
175 inline ScopeExit::~ScopeExit()
176 {
177 // Actually trigger the stored function
178 exit_function();
179 }
180
181
182 DEAL_II_NAMESPACE_CLOSE
183
184 #endif