]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Improve documentation of Utilities::MPI::Future. 18567/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Wed, 18 Jun 2025 15:45:58 +0000 (09:45 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Wed, 18 Jun 2025 21:04:13 +0000 (15:04 -0600)
include/deal.II/base/mpi.h

index 423f26627fe2bff0d4ac467482a0b91f7b4a9a63..6d40c494b34b437f6f708f83c14687aa9504325e 100644 (file)
@@ -419,7 +419,7 @@ namespace Utilities
      * An object that acts like a
      * [std::future](https://en.cppreference.com/w/cpp/thread/future)
      * object except that it does not encode the operation of waiting
-     * for an operation to finish that may be happening on a different
+     * for an operation to finish what may be happening on a different
      * thread, but for an "immediate" MPI operation such as
      * `MPI_Isend` or `MPI_Irecv`. An object of this kind is returned,
      * for example, by the isend() and irecv() functions in this
@@ -486,6 +486,34 @@ namespace Utilities
 
       /**
        * Destructor.
+       *
+       * If the current object has not been the right hand side of a move
+       * operation, and if get() has not been called on the current object,
+       * then the destructor blocks until the operation is completed so that
+       * the clean-up operations can be performed. As a consequence, if you
+       * write code such as
+       * @code
+       *   Utilities::MPI::isend(data, mpi_communicator, receiver, tag);
+       * @endcode
+       * where you do not capture the isend() functions' returned object,
+       * then the destructor of the returned object will run immediately at the
+       * end of executing this line, and this implies waiting for the isend()
+       * function's operations to finish -- in other words, you are turning
+       * the "immediate send" into a "waiting send" where the line only
+       * terminates once the data has been sent and the send buffer is no
+       * longer needed. (Note, however, that that is not the same as MPI's
+       * concept of a "synchronous send" in which the function only returns
+       * once the data has been *received*.)
+       *
+       * Of course, the same happens if you write
+       * @code
+       * {
+       *   Utilities::MPI::Future<void> future
+       *     = Utilities::MPI::isend(data, mpi_communicator, receiver, tag);
+       * }
+       * @endcode
+       * where you do capture the returned object, but the destructor is run
+       * at the closing brace -- also immediately after returning from isend().
        */
       ~Future();
 

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.