corecel/sys/MpiCommunicator.hh

0001 //------------------------------- -*- C++ -*- -------------------------------//
0002 // Copyright Celeritas contributors: see top-level COPYRIGHT file for details
0003 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0004 //---------------------------------------------------------------------------//
0005 //! \file corecel/sys/MpiCommunicator.hh
0006 //! \note Including this file requires linking against the corecel_mpi target
0007 //---------------------------------------------------------------------------//
0008 #pragma once
0009
0010 #include "detail/MpiCommunicatorImpl.hh"  // IWYU pragma: keep
0011
0012 namespace celeritas
0013 {
0014 //---------------------------------------------------------------------------//
0015 /*!
0016  * Wrap an MPI communicator.
0017  *
0018  * This class uses \c ScopedMpiInit to determine whether MPI is available
0019  * and enabled. As many instances as desired can be created, but Celeritas by
0020  * default will share the instance returned by \c comm_world , which defaults
0021  * to \c MPI_COMM_WORLD if MPI has been initialized, or a "self" comm if it has
0022  * not.
0023  *
0024  * A "null" communicator (the default) does not use MPI calls and can be
0025  * constructed without calling \c MPI_Init or having MPI compiled. It will act
0026  * like \c MPI_Comm_Self but will not actually use MPI calls.
0027  *
0028  * \note This does not perform any copying or freeing of MPI communiators.
0029  */
0030 class MpiCommunicator
0031 {
0032   public:
0033     //!@{
0034     //! \name Type aliases
0035     using MpiComm = detail::MpiComm;
0036     //!@}
0037
0038   public:
0039     // Construct a communicator with MPI_COMM_SELF
0040     inline static MpiCommunicator self();
0041
0042     // Construct a communicator with MPI_COMM_WORLD
0043     inline static MpiCommunicator world();
0044
0045     // Construct a communicator with MPI_COMM_WORLD or null if disabled
0046     static MpiCommunicator world_if_enabled();
0047
0048     //// CONSTRUCTORS ////
0049
0050     // Construct with a null communicator (MPI is disabled)
0051     MpiCommunicator() = default;
0052
0053     // Construct with a native MPI communicator
0054     explicit MpiCommunicator(MpiComm comm);
0055
0056     //// ACCESSORS ////
0057
0058     //! Get the MPI communicator for low-level MPI calls
0059     MpiComm mpi_comm() const { return comm_; }
0060
0061     //! Get the local process ID
0062     int rank() const { return rank_; }
0063
0064     //! Get the number of total processors
0065     int size() const { return size_; }
0066
0067     //! True if non-null communicator
0068     explicit operator bool() const { return comm_ != detail::mpi_comm_null(); }
0069
0070   private:
0071     MpiComm comm_ = detail::mpi_comm_null();
0072     int rank_ = 0;
0073     int size_ = 1;
0074 };
0075
0076 //---------------------------------------------------------------------------//
0077 // FREE FUNCTIONS
0078 //---------------------------------------------------------------------------//
0079
0080 // Shared "world" Celeritas communicator
0081 MpiCommunicator const& comm_world();
0082
0083 //---------------------------------------------------------------------------//
0084 // INLINE DEFINITIONS
0085 //---------------------------------------------------------------------------//
0086 /*!
0087  * Construct a communicator with MPI_COMM_SELF.
0088  *
0089  * Each process sees itself as rank zero in size zero, thus operating
0090  * independently.
0091  */
0092 MpiCommunicator MpiCommunicator::self()
0093 {
0094     return MpiCommunicator{detail::mpi_comm_self()};
0095 }
0096
0097 //---------------------------------------------------------------------------//
0098 /*!
0099  * Construct a communicator with MPI_COMM_WORLD.
0100  *
0101  * Each process sees every other process in MPI's domain, operating at the
0102  * maximum level of interprocess cooperation.
0103  */
0104 MpiCommunicator MpiCommunicator::world()
0105 {
0106     return MpiCommunicator{detail::mpi_comm_world()};
0107 }
0108
0109 //---------------------------------------------------------------------------//
0110 }  // namespace celeritas