environment.hpp 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202
  1. // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com>
  2. // Use, modification and distribution is subject to the Boost Software
  3. // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
  4. // http://www.boost.org/LICENSE_1_0.txt)
  5. /** @file environment.hpp
  6. *
  7. * This header provides the @c environment class, which provides
  8. * routines to initialize, finalization, and query the status of the
  9. * Boost MPI environment.
  10. */
  11. #ifndef BOOST_MPI_ENVIRONMENT_HPP
  12. #define BOOST_MPI_ENVIRONMENT_HPP
  13. #include <boost/mpi/config.hpp>
  14. #include <boost/noncopyable.hpp>
  15. #include <boost/optional.hpp>
  16. #include <string>
  17. namespace boost { namespace mpi {
  18. /** @brief Initialize, finalize, and query the MPI environment.
  19. *
  20. * The @c environment class is used to initialize, finalize, and
  21. * query the MPI environment. It will typically be used in the @c
  22. * main() function of a program, which will create a single instance
  23. * of @c environment initialized with the arguments passed to the
  24. * program:
  25. *
  26. * @code
  27. * int main(int argc, char* argv[])
  28. * {
  29. * mpi::environment env(argc, argv);
  30. * }
  31. * @endcode
  32. *
  33. * The instance of @c environment will initialize MPI (by calling @c
  34. * MPI_Init) in its constructor and finalize MPI (by calling @c
  35. * MPI_Finalize for normal termination or @c MPI_Abort for an
  36. * uncaught exception) in its destructor.
  37. *
  38. * The use of @c environment is not mandatory. Users may choose to
  39. * invoke @c MPI_Init and @c MPI_Finalize manually. In this case, no
  40. * @c environment object is needed. If one is created, however, it
  41. * will do nothing on either construction or destruction.
  42. */
  43. class BOOST_MPI_DECL environment : noncopyable {
  44. public:
  45. #ifdef BOOST_MPI_HAS_NOARG_INITIALIZATION
  46. /** Initialize the MPI environment.
  47. *
  48. * If the MPI environment has not already been initialized,
  49. * initializes MPI with a call to @c MPI_Init. Since this
  50. * constructor does not take command-line arguments (@c argc and @c
  51. * argv), it is only available when the underlying MPI
  52. * implementation supports calling @c MPI_Init with @c NULL
  53. * arguments, indicated by the macro @c
  54. * BOOST_MPI_HAS_NOARG_INITIALIZATION.
  55. *
  56. * @param abort_on_exception When true, this object will abort the
  57. * program if it is destructed due to an uncaught exception.
  58. */
  59. explicit environment(bool abort_on_exception = true);
  60. #endif
  61. /** Initialize the MPI environment.
  62. *
  63. * If the MPI environment has not already been initialized,
  64. * initializes MPI with a call to @c MPI_Init.
  65. *
  66. * @param argc The number of arguments provided in @p argv, as
  67. * passed into the program's @c main function.
  68. *
  69. * @param argv The array of argument strings passed to the program
  70. * via @c main.
  71. *
  72. * @param abort_on_exception When true, this object will abort the
  73. * program if it is destructed due to an uncaught exception.
  74. */
  75. environment(int& argc, char** &argv, bool abort_on_exception = true);
  76. /** Shuts down the MPI environment.
  77. *
  78. * If this @c environment object was used to initialize the MPI
  79. * environment, and the MPI environment has not already been shut
  80. * down (finalized), this destructor will shut down the MPI
  81. * environment. Under normal circumstances, this only involves
  82. * invoking @c MPI_Finalize. However, if destruction is the result
  83. * of an uncaught exception and the @c abort_on_exception parameter
  84. * of the constructor had the value @c true, this destructor will
  85. * invoke @c MPI_Abort with @c MPI_COMM_WORLD to abort the entire
  86. * MPI program with a result code of -1.
  87. */
  88. ~environment();
  89. /** Abort all MPI processes.
  90. *
  91. * Aborts all MPI processes and returns to the environment. The
  92. * precise behavior will be defined by the underlying MPI
  93. * implementation. This is equivalent to a call to @c MPI_Abort
  94. * with @c MPI_COMM_WORLD.
  95. *
  96. * @param errcode The error code to return to the environment.
  97. * @returns Will not return.
  98. */
  99. static void abort(int errcode);
  100. /** Determine if the MPI environment has already been initialized.
  101. *
  102. * This routine is equivalent to a call to @c MPI_Initialized.
  103. *
  104. * @returns @c true if the MPI environment has been initialized.
  105. */
  106. static bool initialized();
  107. /** Determine if the MPI environment has already been finalized.
  108. *
  109. * The routine is equivalent to a call to @c MPI_Finalized.
  110. *
  111. * @returns @c true if the MPI environment has been finalized.
  112. */
  113. static bool finalized();
  114. /** Retrieves the maximum tag value.
  115. *
  116. * Returns the maximum value that may be used for the @c tag
  117. * parameter of send/receive operations. This value will be
  118. * somewhat smaller than the value of @c MPI_TAG_UB, because the
  119. * Boost.MPI implementation reserves some tags for collective
  120. * operations.
  121. *
  122. * @returns the maximum tag value.
  123. */
  124. static int max_tag();
  125. /** The tag value used for collective operations.
  126. *
  127. * Returns the reserved tag value used by the Boost.MPI
  128. * implementation for collective operations. Although users are not
  129. * permitted to use this tag to send or receive messages, it may be
  130. * useful when monitoring communication patterns.
  131. *
  132. * @returns the tag value used for collective operations.
  133. */
  134. static int collectives_tag();
  135. /** Retrieves the rank of the host process, if one exists.
  136. *
  137. * If there is a host process, this routine returns the rank of
  138. * that process. Otherwise, it returns an empty @c
  139. * optional<int>. MPI does not define the meaning of a "host"
  140. * process: consult the documentation for the MPI
  141. * implementation. This routine examines the @c MPI_HOST attribute
  142. * of @c MPI_COMM_WORLD.
  143. *
  144. * @returns The rank of the host process, if one exists.
  145. */
  146. static optional<int> host_rank();
  147. /** Retrieves the rank of a process that can perform input/output.
  148. *
  149. * This routine returns the rank of a process that can perform
  150. * input/output via the standard C and C++ I/O facilities. If every
  151. * process can perform I/O using the standard facilities, this
  152. * routine will return @c any_source; if no process can perform
  153. * I/O, this routine will return no value (an empty @c
  154. * optional). This routine examines the @c MPI_IO attribute of @c
  155. * MPI_COMM_WORLD.
  156. *
  157. * @returns the rank of the process that can perform I/O, @c
  158. * any_source if every process can perform I/O, or no value if no
  159. * process can perform I/O.
  160. */
  161. static optional<int> io_rank();
  162. /** Retrieve the name of this processor.
  163. *
  164. * This routine returns the name of this processor. The actual form
  165. * of the name is unspecified, but may be documented by the
  166. * underlying MPI implementation. This routine is implemented as a
  167. * call to @c MPI_Get_processor_name.
  168. *
  169. * @returns the name of this processor.
  170. */
  171. static std::string processor_name();
  172. private:
  173. /// Whether this environment object called MPI_Init
  174. bool i_initialized;
  175. /// Whether we should abort if the destructor is
  176. bool abort_on_exception;
  177. /// The number of reserved tags.
  178. static const int num_reserved_tags = 1;
  179. };
  180. } } // end namespace boost::mpi
  181. #endif // BOOST_MPI_ENVIRONMENT_HPP