| // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com> |
| |
| // Use, modification and distribution is subject to the Boost Software |
| // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at |
| // http://www.boost.org/LICENSE_1_0.txt) |
| |
| /** @file environment.hpp |
| * |
| * This header provides the @c environment class, which provides |
| * routines to initialize, finalization, and query the status of the |
| * Boost MPI environment. |
| */ |
| #ifndef BOOST_MPI_ENVIRONMENT_HPP |
| #define BOOST_MPI_ENVIRONMENT_HPP |
| |
| #include <boost/mpi/config.hpp> |
| #include <boost/noncopyable.hpp> |
| #include <boost/optional.hpp> |
| #include <string> |
| |
| namespace boost { namespace mpi { |
| |
| /** @brief Initialize, finalize, and query the MPI environment. |
| * |
| * The @c environment class is used to initialize, finalize, and |
| * query the MPI environment. It will typically be used in the @c |
| * main() function of a program, which will create a single instance |
| * of @c environment initialized with the arguments passed to the |
| * program: |
| * |
| * @code |
| * int main(int argc, char* argv[]) |
| * { |
| * mpi::environment env(argc, argv); |
| * } |
| * @endcode |
| * |
| * The instance of @c environment will initialize MPI (by calling @c |
| * MPI_Init) in its constructor and finalize MPI (by calling @c |
| * MPI_Finalize for normal termination or @c MPI_Abort for an |
| * uncaught exception) in its destructor. |
| * |
| * The use of @c environment is not mandatory. Users may choose to |
| * invoke @c MPI_Init and @c MPI_Finalize manually. In this case, no |
| * @c environment object is needed. If one is created, however, it |
| * will do nothing on either construction or destruction. |
| */ |
| class BOOST_MPI_DECL environment : noncopyable { |
| public: |
| #ifdef BOOST_MPI_HAS_NOARG_INITIALIZATION |
| /** Initialize the MPI environment. |
| * |
| * If the MPI environment has not already been initialized, |
| * initializes MPI with a call to @c MPI_Init. Since this |
| * constructor does not take command-line arguments (@c argc and @c |
| * argv), it is only available when the underlying MPI |
| * implementation supports calling @c MPI_Init with @c NULL |
| * arguments, indicated by the macro @c |
| * BOOST_MPI_HAS_NOARG_INITIALIZATION. |
| * |
| * @param abort_on_exception When true, this object will abort the |
| * program if it is destructed due to an uncaught exception. |
| */ |
| explicit environment(bool abort_on_exception = true); |
| #endif |
| |
| /** Initialize the MPI environment. |
| * |
| * If the MPI environment has not already been initialized, |
| * initializes MPI with a call to @c MPI_Init. |
| * |
| * @param argc The number of arguments provided in @p argv, as |
| * passed into the program's @c main function. |
| * |
| * @param argv The array of argument strings passed to the program |
| * via @c main. |
| * |
| * @param abort_on_exception When true, this object will abort the |
| * program if it is destructed due to an uncaught exception. |
| */ |
| environment(int& argc, char** &argv, bool abort_on_exception = true); |
| |
| /** Shuts down the MPI environment. |
| * |
| * If this @c 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 @c MPI_Finalize. However, if destruction is the result |
| * of an uncaught exception and the @c abort_on_exception parameter |
| * of the constructor had the value @c true, this destructor will |
| * invoke @c MPI_Abort with @c MPI_COMM_WORLD to abort the entire |
| * MPI program with a result code of -1. |
| */ |
| ~environment(); |
| |
| /** 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 @c MPI_Abort |
| * with @c MPI_COMM_WORLD. |
| * |
| * @param errcode The error code to return to the environment. |
| * @returns Will not return. |
| */ |
| static void abort(int errcode); |
| |
| /** Determine if the MPI environment has already been initialized. |
| * |
| * This routine is equivalent to a call to @c MPI_Initialized. |
| * |
| * @returns @c true if the MPI environment has been initialized. |
| */ |
| static bool initialized(); |
| |
| /** Determine if the MPI environment has already been finalized. |
| * |
| * The routine is equivalent to a call to @c MPI_Finalized. |
| * |
| * @returns @c true if the MPI environment has been finalized. |
| */ |
| static bool finalized(); |
| |
| /** Retrieves the maximum tag value. |
| * |
| * Returns the maximum value that may be used for the @c tag |
| * parameter of send/receive operations. This value will be |
| * somewhat smaller than the value of @c MPI_TAG_UB, because the |
| * Boost.MPI implementation reserves some tags for collective |
| * operations. |
| * |
| * @returns the maximum tag value. |
| */ |
| static int max_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 int collectives_tag(); |
| |
| /** 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 @c |
| * optional<int>. MPI does not define the meaning of a "host" |
| * process: consult the documentation for the MPI |
| * implementation. This routine examines the @c MPI_HOST attribute |
| * of @c MPI_COMM_WORLD. |
| * |
| * @returns The rank of the host process, if one exists. |
| */ |
| static optional<int> host_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 @c any_source; if no process can perform |
| * I/O, this routine will return no value (an empty @c |
| * optional). This routine examines the @c MPI_IO attribute of @c |
| * MPI_COMM_WORLD. |
| * |
| * @returns the rank of the process that can perform I/O, @c |
| * any_source if every process can perform I/O, or no value if no |
| * process can perform I/O. |
| */ |
| static optional<int> io_rank(); |
| |
| /** 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 @c MPI_Get_processor_name. |
| * |
| * @returns the name of this processor. |
| */ |
| static std::string processor_name(); |
| |
| private: |
| /// Whether this environment object called MPI_Init |
| bool i_initialized; |
| |
| /// Whether we should abort if the destructor is |
| bool abort_on_exception; |
| |
| /// The number of reserved tags. |
| static const int num_reserved_tags = 1; |
| }; |
| |
| } } // end namespace boost::mpi |
| |
| #endif // BOOST_MPI_ENVIRONMENT_HPP |