| Home | Libraries | People | FAQ | More

## 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();
    };

## 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

1.     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.

2.     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.

3.     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`.

4.     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

5.     ~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

1.     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.

2.     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.

3.     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.

4.     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.

5.     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.

6.     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.

7.     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.

8.     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.

9.     static threading::level thread_level();

   Query the current level of thread support.

10.     static bool is_main_thread();

    Are we in the main thread?