boost/mpi/environment.hpp

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