...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::mpi::environment — Initialize, finalize, and query the MPI environment.
// In header: <boost/mpi/environment.hpp> class environment : private noncopyable { public: // public member functions explicit environment(bool = true); explicit environment(threading::level, bool = true); environment(int &, char **&, bool = true); environment(int &, char **&, threading::level, bool = true); ~environment(); // public static functions static void abort(int); static bool initialized(); static bool finalized(); static int max_tag(); static int collectives_tag(); static optional< int > host_rank(); static optional< int > io_rank(); static std::string processor_name(); static threading::level thread_level(); static bool is_main_thread(); static std::pair< int, int > version(); static std::string library_version(); };
The environment
class is used to initialize, finalize, and query the MPI environment. It will typically be used in the main()
function of a program, which will create a single instance of environment
initialized with the arguments passed to the program:
int main(int argc, char* argv[]) { mpi::environment env(argc, argv); }
The instance of environment
will initialize MPI (by calling MPI_Init
) in its constructor and finalize MPI (by calling MPI_Finalize
for normal termination or MPI_Abort
for an uncaught exception) in its destructor.
The use of environment
is not mandatory. Users may choose to invoke MPI_Init
and MPI_Finalize
manually. In this case, no environment
object is needed. If one is created, however, it will do nothing on either construction or destruction.
environment
public member functionsexplicit environment(bool abort_on_exception = true);
Initialize the MPI environment.
If the MPI environment has not already been initialized, initializes MPI with a call to MPI_Init
. Since this constructor does not take command-line arguments (argc
and argv
), it is only available when the underlying MPI implementation supports calling MPI_Init
with NULL
arguments, indicated by the macro BOOST_MPI_HAS_NOARG_INITIALIZATION
.
Parameters: |
|
explicit environment(threading::level mt_level, bool abort_on_exception = true);
Initialize the MPI environment.
If the MPI environment has not already been initialized, initializes MPI with a call to MPI_Init_thread
. Since this constructor does not take command-line arguments (argc
and argv
), it is only available when the underlying MPI implementation supports calling MPI_Init
with NULL
arguments, indicated by the macro BOOST_MPI_HAS_NOARG_INITIALIZATION
.
Parameters: |
|
environment(int & argc, char **& argv, bool abort_on_exception = true);
Initialize the MPI environment.
If the MPI environment has not already been initialized, initializes MPI with a call to MPI_Init
.
Parameters: |
|
environment(int & argc, char **& argv, threading::level mt_level, bool abort_on_exception = true);
Initialize the MPI environment.
If the MPI environment has not already been initialized, initializes MPI with a call to MPI_Init_thread
.
Parameters: |
|
~environment();
Shuts down the MPI environment.
If this environment
object was used to initialize the MPI environment, and the MPI environment has not already been shut down (finalized), this destructor will shut down the MPI environment. Under normal circumstances, this only involves invoking MPI_Finalize
. However, if destruction is the result of an uncaught exception and the abort_on_exception
parameter of the constructor had the value true
, this destructor will invoke MPI_Abort
with MPI_COMM_WORLD
to abort the entire MPI program with a result code of -1.
environment
public static functionsstatic void abort(int errcode);
Abort all MPI processes.
Aborts all MPI processes and returns to the environment. The precise behavior will be defined by the underlying MPI implementation. This is equivalent to a call to MPI_Abort
with MPI_COMM_WORLD
.
Parameters: |
|
||
Returns: |
Will not return. |
static bool initialized();
Determine if the MPI environment has already been initialized.
This routine is equivalent to a call to MPI_Initialized
.
Returns: |
|
static bool finalized();
Determine if the MPI environment has already been finalized.
The routine is equivalent to a call to MPI_Finalized
.
Returns: |
|
static int max_tag();
Retrieves the maximum tag value.
Returns the maximum value that may be used for the tag
parameter of send/receive operations. This value will be somewhat smaller than the value of MPI_TAG_UB
, because the Boost.MPI implementation reserves some tags for collective operations.
Returns: |
the maximum tag value. |
static int collectives_tag();
The tag value used for collective operations.
Returns the reserved tag value used by the Boost.MPI implementation for collective operations. Although users are not permitted to use this tag to send or receive messages, it may be useful when monitoring communication patterns.
Returns: |
the tag value used for collective operations. |
static optional< int > host_rank();
Retrieves the rank of the host process, if one exists.
If there is a host process, this routine returns the rank of that process. Otherwise, it returns an empty optional<int>
. MPI does not define the meaning of a "host" process: consult the documentation for the MPI implementation. This routine examines the MPI_HOST
attribute of MPI_COMM_WORLD
.
Returns: |
The rank of the host process, if one exists. |
static optional< int > io_rank();
Retrieves the rank of a process that can perform input/output.
This routine returns the rank of a process that can perform input/output via the standard C and C++ I/O facilities. If every process can perform I/O using the standard facilities, this routine will return any_source
; if no process can perform I/O, this routine will return no value (an empty optional
). This routine examines the MPI_IO
attribute of MPI_COMM_WORLD
.
Returns: |
the rank of the process that can perform I/O, |
static std::string processor_name();
Retrieve the name of this processor.
This routine returns the name of this processor. The actual form of the name is unspecified, but may be documented by the underlying MPI implementation. This routine is implemented as a call to MPI_Get_processor_name
.
Returns: |
the name of this processor. |
static threading::level thread_level();
Query the current level of thread support.
static bool is_main_thread();
Are we in the main thread?
static std::pair< int, int > version();MPI version.
Returns a pair with the version and sub-version number.
static std::string library_version();MPI library implementation version string.
This routine returns a string with an additional library version information. The actual form of this version string is unspecified, but may be documented by the underlying MPI implementation. This routine is implemented as a call to MPI_Get_library_version
, which is available from MPI-3. On older implementations the empty string will be returned.