| 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 |