Interface updates allowing client to provide MPI communicator.

[alexxy/gromacs.git] / api / gmxapi / include / gmxapi / context.h

diff --git a/api/gmxapi/include/gmxapi/context.h b/api/gmxapi/include/gmxapi/context.h
index c705d08a432d0d4015dee2d0d930b31451f2341a..ec434059af419517dcccae5dc632a11ce2bd8a8d 100644 (file)
--- a/api/gmxapi/include/gmxapi/context.h
+++ b/api/gmxapi/include/gmxapi/context.h
@@ -39,6 +39,24 @@
  *
  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  * \ingroup gmxapi
+ *
+ * # Notes on scope
+ *
+ * Client owns Context and MultiProcessingResources, which exist entirely in client scope.
+ *
+ * Note that MpiContextManager and Session live in library scope.
+ *
+ * # MPI-enabled clients
+ *
+ * When an MPI toolchain is compatible with the GROMACS build
+ * (see [#3672](https://gitlab.com/gromacs/gromacs/-/issues/3672)),
+ * multi-process clients may determine how processes are allocated to GROMACS
+ * simulations by providing Contexts with specific MPI Communicators to
+ * createContext(const MultiProcessingResources& resources)
+ *
+ * MultiProcessingResources is an opaque type of library-internal resources.
+ * Clients acquire such resources with the assignResource() template helper.
+ * See gmxapi_mpi.h
  */
 
 #include <memory>
@@ -168,6 +186,45 @@ private:
     std::shared_ptr<ContextImpl> impl_;
 };
 
+// Forward declaration for interoperation with the library.
+// Client code implements a concrete ResourceAssignment indirectly by instantiating
+// assignResource() through the gmxapi_mpi.h template header.
+class ResourceAssignment;
+
+// See template header gmxapi_mpi.h
+template<typename CommT>
+std::unique_ptr<ResourceAssignment> assignResource(CommT communicator);
+
+/*!
+ * \brief Initialize a new API Context to manage resources and software environment.
+ *
+ * The client is responsible for keeping the Context instance alive for at least
+ * as long as any API objects initialized from it. We allow this responsibility
+ * to be placed on the client (rather than using a global Singleton) because the
+ * library is theoretically reentrant, and multiple Context objects may exist.
+ *
+ * Client may explicitly assign run time computing resources for use within the Context.
+ * Otherwise, the library will try to automatically detect and allocate computing resources.
+ *
+ * Currently, only MPI communication scope can be assigned explicitly.
+ * Future development is needed before this interface can influence the subdivision
+ * of available GPUs or thread-based processor allocation. See #3650 and #3688.
+ *
+ * \return Initialized Context instance.
+ *
+ * \internal
+ * Use cases:
+ *
+ * 1. tMPI and client-provided comm: provide a place for safety checks, then construct a suitable
+ * dummy MpiContextManager.
+ * 2. tMPI and no client-provided comm: construct suitable dummy MpiContextManager
+ * 3. MPI and client-provided comm: use compatible comm. error if COMM_NULL
+ * 4. MPI and no client-provided comm: generate MpiContextManager with COMM_WORLD
+ *
+ */
+Context createContext();
+Context createContext(const ResourceAssignment& resources);
+
 } // end namespace gmxapi
 
 #endif // header guard