Class environment

boost::mpi::environment — Initialize, finalize, and query the MPI environment.

Synopsis

// In header: <boost/mpi/environment.hpp>


class environment : private noncopyable {
public:
  // construct/copy/destruct
  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();
};

Description

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 construct/copy/destruct

```
explicit 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:

abort_on_exception

When true, this object will abort the program if it is destructed due to an uncaught exception.
```
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:

abort_on_exception

When true, this object will abort the program if it is destructed due to an uncaught exception.

mt_level

the required level of threading support.

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:

`abort_on_exception`	When true, this object will abort the program if it is destructed due to an uncaught exception.
`argc`	The number of arguments provided in `argv`, as passed into the program's `main` function.
`argv`	The array of argument strings passed to the program via `main`.

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:

`abort_on_exception`	When true, this object will abort the program if it is destructed due to an uncaught exception.
`argc`	The number of arguments provided in `argv`, as passed into the program's `main` function.
`argv`	The array of argument strings passed to the program via `main`.
`mt_level`	the required level of threading support

```
~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 functions

```
static 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:

errcode

The error code to return to the environment.

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:

true if the MPI environment has been initialized.
```
static bool finalized();
```
Determine if the MPI environment has already been finalized.

The routine is equivalent to a call to MPI_Finalized.

Returns:

true if the MPI environment has been finalized.
```
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, any_source if every process can perform I/O, or no value if no process 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.