From: Wolfgang Bangerth Date: Fri, 24 Nov 2023 23:54:46 +0000 (-0700) Subject: Document instrumenting functions. X-Git-Tag: relicensing~280^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6c0cd4894183967bad6a37f6a2764e3197448038;p=dealii.git Document instrumenting functions. --- diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index 0693e98fb9..3fba7c475f 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -94,7 +94,7 @@ identity_operator(const LinearOperator &); * * But, in contrast to a usual matrix object, the domain and range of the * linear operator are also bound to the LinearOperator class on the type - * level. Because of this, LinearOperator has two + * level. Because of this, `LinearOperator` has two * additional function objects * @code * std::function reinit_range_vector; @@ -169,9 +169,31 @@ identity_operator(const LinearOperator &); * for linear operators have been provided within the respective * TrilinosWrappers (and, in the future, PETScWrappers) namespaces. * - * @note The step-20 tutorial program has a detailed usage example of the + *

Examples of use

+ * The step-20 tutorial program has a detailed usage example of the * LinearOperator class. * + *

Instrumenting operations

+ * It is sometimes useful to know when functions are called, or to inject + * additional operations. In such cases, what one wants is to replace, for + * example, the `vmult` object of this class with one that does the additional + * operations and then calls what was originally supposed to happen. This + * can be done with commands such as the following: + * @code + * auto A_inv = inverse_operator(A, solver_A, preconditioner_A); + * A_inv.vmult = [base_vmult = A_inv.vmult](Vector &dst, + * const Vector &src) { + * std::cout << "Calling A_inv.vmult()" << std::endl; + * base_vmult(dst, src); + * }; + * @endcode + * Here, we replace `A_inv.vmult` with a lambda function that first captures + * the previous value of `A_inv.vmult` and stores it in the `base_vmult` + * object. The newly installed `A_inv.vmult` function then first outputs some + * status information, and then calls the original functionality. + * + * This approach works for all of the other function objects mentioned above + * as well. * * @ingroup LAOperators */