1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
// 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
|
