boost/mpi/environment.hpp

0001 // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com>
0002
0003 // Use, modification and distribution is subject to the Boost Software
0004 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 /** @file environment.hpp
0008  *
0009  *  This header provides the @c environment class, which provides
0010  *  routines to initialize, finalization, and query the status of the
0011  *  Boost MPI environment.
0012  */
0013 #ifndef BOOST_MPI_ENVIRONMENT_HPP
0014 #define BOOST_MPI_ENVIRONMENT_HPP
0015
0016 #include <boost/mpi/config.hpp>
0017 #include <boost/noncopyable.hpp>
0018 #include <boost/optional.hpp>
0019 #include <string>
0020 #include <iosfwd>
0021
0022 namespace boost { namespace mpi {
0023 namespace threading {
0024 /** @brief specify the supported threading level.
0025  *
0026  * Based on MPI 2 standard/8.7.3
0027  */
0028 enum level {
0029   /** Only one thread will execute.
0030    */
0031   single,
0032   /** Only main thread will do MPI calls.
0033    *
0034    * The process may be multi-threaded, but only the main
0035    * thread will make MPI calls (all MPI calls are ``funneled''
0036    * to the main thread).
0037    */
0038   funneled,
0039   /** Only one thread at the time do MPI calls.
0040    *
0041    * The process may be multi-threaded, and multiple
0042    * threads may make MPI calls, but only one at a time:
0043    * MPI calls are not made concurrently from two distinct
0044    * threads (all MPI calls are ``serialized'').
0045    */
0046   serialized,
0047   /** Multiple thread may do MPI calls.
0048    *
0049    * Multiple threads may call MPI, with no restrictions.
0050    */
0051   multiple
0052 };
0053
0054 /** Formated output for threading level. */
0055 std::ostream& operator<<(std::ostream& out, level l);
0056
0057 /** Formated input for threading level. */
0058 std::istream& operator>>(std::istream& in, level& l);
0059 } // namespace threading
0060 /** @brief Initialize, finalize, and query the MPI environment.
0061  *
0062  *  The @c environment class is used to initialize, finalize, and
0063  *  query the MPI environment. It will typically be used in the @c
0064  *  main() function of a program, which will create a single instance
0065  *  of @c environment initialized with the arguments passed to the
0066  *  program:
0067  *
0068  *  @code
0069  *  int main(int argc, char* argv[])
0070  *  {
0071  *    mpi::environment env(argc, argv);
0072  *  }
0073  *  @endcode
0074  *
0075  *  The instance of @c environment will initialize MPI (by calling @c
0076  *  MPI_Init) in its constructor and finalize MPI (by calling @c
0077  *  MPI_Finalize for normal termination or @c MPI_Abort for an
0078  *  uncaught exception) in its destructor.
0079  *
0080  *  The use of @c environment is not mandatory. Users may choose to
0081  *  invoke @c MPI_Init and @c MPI_Finalize manually. In this case, no
0082  *  @c environment object is needed. If one is created, however, it
0083  *  will do nothing on either construction or destruction.
0084  */
0085 class BOOST_MPI_DECL environment : noncopyable {
0086 public:
0087 #ifdef BOOST_MPI_HAS_NOARG_INITIALIZATION
0088   /** Initialize the MPI environment.
0089    *
0090    *  If the MPI environment has not already been initialized,
0091    *  initializes MPI with a call to @c MPI_Init. Since this
0092    *  constructor does not take command-line arguments (@c argc and @c
0093    *  argv), it is only available when the underlying MPI
0094    *  implementation supports calling @c MPI_Init with @c NULL
0095    *  arguments, indicated by the macro @c
0096    *  BOOST_MPI_HAS_NOARG_INITIALIZATION.
0097    *
0098    *  @param abort_on_exception When true, this object will abort the
0099    *  program if it is destructed due to an uncaught exception.
0100    */
0101   explicit environment(bool abort_on_exception = true);
0102   /** Initialize the MPI environment.
0103    *
0104    *  If the MPI environment has not already been initialized,
0105    *  initializes MPI with a call to @c MPI_Init_thread. Since this
0106    *  constructor does not take command-line arguments (@c argc and @c
0107    *  argv), it is only available when the underlying MPI
0108    *  implementation supports calling @c MPI_Init with @c NULL
0109    *  arguments, indicated by the macro @c
0110    *  BOOST_MPI_HAS_NOARG_INITIALIZATION.
0111    *
0112    *  @param mt_level the required level of threading support.
0113    *
0114    *  @param abort_on_exception When true, this object will abort the
0115    *  program if it is destructed due to an uncaught exception.
0116    */
0117   explicit environment(threading::level mt_level, bool abort_on_exception = true);
0118 #endif
0119
0120   /** Initialize the MPI environment.
0121    *
0122    *  If the MPI environment has not already been initialized,
0123    *  initializes MPI with a call to @c MPI_Init.
0124    *
0125    *  @param argc The number of arguments provided in @p argv, as
0126    *  passed into the program's @c main function.
0127    *
0128    *  @param argv The array of argument strings passed to the program
0129    *  via @c main.
0130    *
0131    *  @param abort_on_exception When true, this object will abort the
0132    *  program if it is destructed due to an uncaught exception.
0133    */
0134   environment(int& argc, char** &argv, bool abort_on_exception = true);
0135
0136   /** Initialize the MPI environment.
0137    *
0138    *  If the MPI environment has not already been initialized,
0139    *  initializes MPI with a call to @c MPI_Init_thread.
0140    *
0141    *  @param argc The number of arguments provided in @p argv, as
0142    *  passed into the program's @c main function.
0143    *
0144    *  @param argv The array of argument strings passed to the program
0145    *  via @c main.
0146    *
0147    *  @param mt_level the required level of threading support
0148    *
0149    *  @param abort_on_exception When true, this object will abort the
0150    *  program if it is destructed due to an uncaught exception.
0151    */
0152   environment(int& argc, char** &argv, threading::level mt_level,
0153               bool abort_on_exception = true);
0154
0155   /** Shuts down the MPI environment.
0156    *
0157    *  If this @c environment object was used to initialize the MPI
0158    *  environment, and the MPI environment has not already been shut
0159    *  down (finalized), this destructor will shut down the MPI
0160    *  environment. Under normal circumstances, this only involves
0161    *  invoking @c MPI_Finalize. However, if destruction is the result
0162    *  of an uncaught exception and the @c abort_on_exception parameter
0163    *  of the constructor had the value @c true, this destructor will
0164    *  invoke @c MPI_Abort with @c MPI_COMM_WORLD to abort the entire
0165    *  MPI program with a result code of -1.
0166    */
0167   ~environment();
0168
0169   /** Abort all MPI processes.
0170    *
0171    *  Aborts all MPI processes and returns to the environment. The
0172    *  precise behavior will be defined by the underlying MPI
0173    *  implementation. This is equivalent to a call to @c MPI_Abort
0174    *  with @c MPI_COMM_WORLD.
0175    *
0176    *  @param errcode The error code to return to the environment.
0177    *  @returns Will not return.
0178    */
0179   [[noreturn]] static void abort(int errcode);
0180
0181   /** Determine if the MPI environment has already been initialized.
0182    *
0183    *  This routine is equivalent to a call to @c MPI_Initialized.
0184    *
0185    *  @returns @c true if the MPI environment has been initialized.
0186    */
0187   static bool initialized();
0188
0189   /** Determine if the MPI environment has already been finalized.
0190    *
0191    *  The routine is equivalent to a call to @c MPI_Finalized.
0192    *
0193    *  @returns @c true if the MPI environment has been finalized.
0194    */
0195   static bool finalized();
0196
0197   /** Retrieves the maximum tag value.
0198    *
0199    *  Returns the maximum value that may be used for the @c tag
0200    *  parameter of send/receive operations. This value will be
0201    *  somewhat smaller than the value of @c MPI_TAG_UB, because the
0202    *  Boost.MPI implementation reserves some tags for collective
0203    *  operations.
0204    *
0205    *  @returns the maximum tag value.
0206    */
0207   static int max_tag();
0208
0209   /** The tag value used for collective operations.
0210    *
0211    *  Returns the reserved tag value used by the Boost.MPI
0212    *  implementation for collective operations. Although users are not
0213    *  permitted to use this tag to send or receive messages, it may be
0214    *  useful when monitoring communication patterns.
0215    *
0216    * @returns the tag value used for collective operations.
0217    */
0218   static int collectives_tag();
0219
0220   /** Retrieves the rank of the host process, if one exists.
0221    *
0222    *  If there is a host process, this routine returns the rank of
0223    *  that process. Otherwise, it returns an empty @c
0224    *  optional<int>. MPI does not define the meaning of a "host"
0225    *  process: consult the documentation for the MPI
0226    *  implementation. This routine examines the @c MPI_HOST attribute
0227    *  of @c MPI_COMM_WORLD.
0228    *
0229    *  @returns The rank of the host process, if one exists.
0230    */
0231   static optional<int> host_rank();
0232
0233   /** Retrieves the rank of a process that can perform input/output.
0234    *
0235    *  This routine returns the rank of a process that can perform
0236    *  input/output via the standard C and C++ I/O facilities. If every
0237    *  process can perform I/O using the standard facilities, this
0238    *  routine will return @c any_source; if no process can perform
0239    *  I/O, this routine will return no value (an empty @c
0240    *  optional). This routine examines the @c MPI_IO attribute of @c
0241    *  MPI_COMM_WORLD.
0242    *
0243    *  @returns the rank of the process that can perform I/O, @c
0244    *  any_source if every process can perform I/O, or no value if no
0245    *  process can perform I/O.
0246    */
0247   static optional<int> io_rank();
0248
0249   /** Retrieve the name of this processor.
0250    *
0251    *  This routine returns the name of this processor. The actual form
0252    *  of the name is unspecified, but may be documented by the
0253    *  underlying MPI implementation. This routine is implemented as a
0254    *  call to @c MPI_Get_processor_name.
0255    *
0256    *  @returns the name of this processor.
0257    */
0258   static std::string processor_name();
0259
0260   /** Query the current level of thread support.
0261    */
0262   static threading::level thread_level();
0263
0264   /** Are we in the main thread?
0265    */
0266   static bool is_main_thread();
0267
0268   /** @brief MPI version.
0269    *
0270    * Returns a pair with the version and sub-version number.
0271    */
0272   static std::pair<int, int> version();
0273
0274   /** @brief MPI library implementation version string.
0275    *
0276    * This routine returns a string with an additional library version
0277    * information. The actual form of this version string is unspecified,
0278    * but may be documented by the underlying MPI implementation.
0279    * This routine is implemented as a call to @c MPI_Get_library_version,
0280    * which is available from MPI-3. On older implementations the empty
0281    * string will be returned.
0282    */
0283   static std::string library_version();
0284
0285 private:
0286   /// Whether this environment object called MPI_Init
0287   bool i_initialized;
0288
0289   /// Whether we should abort if the destructor is
0290   bool abort_on_exception;
0291
0292   /// The number of reserved tags.
0293   static const int num_reserved_tags = 1;
0294 };
0295
0296 } } // end namespace boost::mpi
0297
0298 #endif // BOOST_MPI_ENVIRONMENT_HPP