corecel/sys/MpiCommunicator.hh

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