// Copyright (C) 2005-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) | |
// Message Passing Interface 1.1 -- Section 4. MPI Collectives | |
/** @file collectives.hpp | |
* | |
* This header contains MPI collective operations, which implement | |
* various parallel algorithms that require the coordination of all | |
* processes within a communicator. The header @c collectives_fwd.hpp | |
* provides forward declarations for each of these operations. To | |
* include only specific collective algorithms, use the headers @c | |
* boost/mpi/collectives/algorithm_name.hpp. | |
*/ | |
#ifndef BOOST_MPI_COLLECTIVES_HPP | |
#define BOOST_MPI_COLLECTIVES_HPP | |
#include <boost/mpi/communicator.hpp> | |
#include <vector> | |
namespace boost { namespace mpi { | |
/** | |
* @brief Gather the values stored at every process into vectors of | |
* values from each process. | |
* | |
* @c all_gather is a collective algorithm that collects the values | |
* stored at each process into a vector of values indexed by the | |
* process number they came from. The type @c T of the values may be | |
* any type that is serializable or has an associated MPI data type. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Allgather to gather the values. | |
* | |
* @param comm The communicator over which the all-gather will | |
* occur. | |
* | |
* @param in_value The value to be transmitted by each process. To | |
* gather an array of values, @c in_values points to the @c n local | |
* values to be transmitted. | |
* | |
* @param out_values A vector or pointer to storage that will be | |
* populated with the values from each process, indexed by the | |
* process ID number. If it is a vector, the vector will be resized | |
* accordingly. | |
*/ | |
template<typename T> | |
void | |
all_gather(const communicator& comm, const T& in_value, | |
std::vector<T>& out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
all_gather(const communicator& comm, const T& in_value, T* out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
all_gather(const communicator& comm, const T* in_values, int n, | |
std::vector<T>& out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
all_gather(const communicator& comm, const T* in_values, int n, T* out_values); | |
/** | |
* @brief Combine the values stored by each process into a single | |
* value available to all processes. | |
* | |
* @c all_reduce is a collective algorithm that combines the values | |
* stored by each process into a single value available to all | |
* processes. The values are combined in a user-defined way, | |
* specified via a function object. The type @c T of the values may | |
* be any type that is serializable or has an associated MPI data | |
* type. One can think of this operation as a @c all_gather, followed | |
* by an @c std::accumulate() over the gather values and using the | |
* operation @c op. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Allreduce to perform the reduction. If possible, | |
* built-in MPI operations will be used; otherwise, @c all_reduce() | |
* will create a custom MPI_Op for the call to MPI_Allreduce. | |
* | |
* @param comm The communicator over which the reduction will | |
* occur. | |
* | |
* @param in_value The local value to be combined with the local | |
* values of every other process. For reducing arrays, @c in_values | |
* is a pointer to the local values to be reduced and @c n is the | |
* number of values to reduce. See @c reduce for more information. | |
* | |
* @param out_value Will receive the result of the reduction | |
* operation. If this parameter is omitted, the outgoing value will | |
* instead be returned. | |
* | |
* @param op The binary operation that combines two values of type | |
* @c T and returns a third value of type @c T. For types @c T that has | |
* ssociated MPI data types, @c op will either be translated into | |
* an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped | |
* directly to a built-in MPI operation. See @c is_mpi_op in the @c | |
* operations.hpp header for more details on this mapping. For any | |
* non-built-in operation, commutativity will be determined by the | |
* @c is_commmutative trait (also in @c operations.hpp): users are | |
* encouraged to mark commutative operations as such, because it | |
* gives the implementation additional lattitude to optimize the | |
* reduction operation. | |
* | |
* @returns If no @p out_value parameter is supplied, returns the | |
* result of the reduction operation. | |
*/ | |
template<typename T, typename Op> | |
void | |
all_reduce(const communicator& comm, const T& in_value, T& out_value, Op op); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
T all_reduce(const communicator& comm, const T& in_value, Op op); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
void | |
all_reduce(const communicator& comm, const T* in_values, int n, T* out_values, | |
Op op); | |
/** | |
* @brief Send data from every process to every other process. | |
* | |
* @c all_to_all is a collective algorithm that transmits @c p values | |
* from every process to every other process. On process i, jth value | |
* of the @p in_values vector is sent to process j and placed in the | |
* ith position of the @p out_values vector in process @p j. The type | |
* @c T of the values may be any type that is serializable or has an | |
* associated MPI data type. If @c n is provided, then arrays of @p n | |
* values will be transferred from one process to another. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Alltoall to scatter the values. | |
* | |
* @param comm The communicator over which the all-to-all | |
* communication will occur. | |
* | |
* @param in_values A vector or pointer to storage that contains | |
* the values to send to each process, indexed by the process ID | |
* number. | |
* | |
* @param out_values A vector or pointer to storage that will be | |
* updated to contain the values received from other processes. The | |
* jth value in @p out_values will come from the procss with rank j. | |
*/ | |
template<typename T> | |
void | |
all_to_all(const communicator& comm, const std::vector<T>& in_values, | |
std::vector<T>& out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void all_to_all(const communicator& comm, const T* in_values, T* out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
all_to_all(const communicator& comm, const std::vector<T>& in_values, int n, | |
std::vector<T>& out_values); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
all_to_all(const communicator& comm, const T* in_values, int n, T* out_values); | |
/** | |
* @brief Broadcast a value from a root process to all other | |
* processes. | |
* | |
* @c broadcast is a collective algorithm that transfers a value from | |
* an arbitrary @p root process to every other process that is part of | |
* the given communicator. The @c broadcast algorithm can transmit any | |
* Serializable value, values that have associated MPI data types, | |
* packed archives, skeletons, and the content of skeletons; see the | |
* @c send primitive for communicators for a complete list. The type | |
* @c T shall be the same for all processes that are a part of the | |
* communicator @p comm, unless packed archives are being transferred: | |
* with packed archives, the root sends a @c packed_oarchive or @c | |
* packed_skeleton_oarchive whereas the other processes receive a | |
* @c packed_iarchive or @c packed_skeleton_iarchve, respectively. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Bcast to perform the broadcast. | |
* | |
* @param comm The communicator over which the broadcast will | |
* occur. | |
* | |
* @param value The value (or values, if @p n is provided) to be | |
* transmitted (if the rank of @p comm is equal to @p root) or | |
* received (if the rank of @p comm is not equal to @p root). When | |
* the @p value is a @c skeleton_proxy, only the skeleton of the | |
* object will be broadcast. In this case, the @p root will build a | |
* skeleton from the object help in the proxy and all of the | |
* non-roots will reshape the objects held in their proxies based on | |
* the skeleton sent from the root. | |
* | |
* @param n When supplied, the number of values that the pointer @p | |
* values points to, for broadcasting an array of values. The value | |
* of @p n must be the same for all processes in @p comm. | |
* | |
* @param root The rank/process ID of the process that will be | |
* transmitting the value. | |
*/ | |
template<typename T> | |
void broadcast(const communicator& comm, T& value, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void broadcast(const communicator& comm, T* values, int n, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void broadcast(const communicator& comm, skeleton_proxy<T>& value, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
broadcast(const communicator& comm, const skeleton_proxy<T>& value, int root); | |
/** | |
* @brief Gather the values stored at every process into a vector at | |
* the root process. | |
* | |
* @c gather is a collective algorithm that collects the values | |
* stored at each process into a vector of values at the @p root | |
* process. This vector is indexed by the process number that the | |
* value came from. The type @c T of the values may be any type that | |
* is serializable or has an associated MPI data type. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Gather to gather the values. | |
* | |
* @param comm The communicator over which the gather will occur. | |
* | |
* @param in_value The value to be transmitted by each process. For | |
* gathering arrays of values, @c in_values points to storage for | |
* @c n*comm.size() values. | |
* | |
* @param out_values A vector or pointer to storage that will be | |
* populated with the values from each process, indexed by the | |
* process ID number. If it is a vector, it will be resized | |
* accordingly. For non-root processes, this parameter may be | |
* omitted. If it is still provided, however, it will be unchanged. | |
* | |
* @param root The process ID number that will collect the | |
* values. This value must be the same on all processes. | |
*/ | |
template<typename T> | |
void | |
gather(const communicator& comm, const T& in_value, std::vector<T>& out_values, | |
int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
gather(const communicator& comm, const T& in_value, T* out_values, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void gather(const communicator& comm, const T& in_value, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
gather(const communicator& comm, const T* in_values, int n, | |
std::vector<T>& out_values, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
gather(const communicator& comm, const T* in_values, int n, T* out_values, | |
int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void gather(const communicator& comm, const T* in_values, int n, int root); | |
/** | |
* @brief Scatter the values stored at the root to all processes | |
* within the communicator. | |
* | |
* @c scatter is a collective algorithm that scatters the values | |
* stored in the @p root process (inside a vector) to all of the | |
* processes in the communicator. The vector @p out_values (only | |
* significant at the @p root) is indexed by the process number to | |
* which the corresponding value will be sent. The type @c T of the | |
* values may be any type that is serializable or has an associated | |
* MPI data type. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Scatter to scatter the values. | |
* | |
* @param comm The communicator over which the gather will occur. | |
* | |
* @param in_values A vector or pointer to storage that will contain | |
* the values to send to each process, indexed by the process rank. | |
* For non-root processes, this parameter may be omitted. If it is | |
* still provided, however, it will be unchanged. | |
* | |
* @param out_value The value received by each process. When | |
* scattering an array of values, @p out_values points to the @p n | |
* values that will be received by each process. | |
* | |
* @param root The process ID number that will scatter the | |
* values. This value must be the same on all processes. | |
*/ | |
template<typename T> | |
void | |
scatter(const communicator& comm, const std::vector<T>& in_values, T& out_value, | |
int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
scatter(const communicator& comm, const T* in_values, T& out_value, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void scatter(const communicator& comm, T& out_value, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
scatter(const communicator& comm, const std::vector<T>& in_values, | |
T* out_values, int n, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void | |
scatter(const communicator& comm, const T* in_values, T* out_values, int n, | |
int root); | |
/** | |
* \overload | |
*/ | |
template<typename T> | |
void scatter(const communicator& comm, T* out_values, int n, int root); | |
/** | |
* @brief Combine the values stored by each process into a single | |
* value at the root. | |
* | |
* @c reduce is a collective algorithm that combines the values | |
* stored by each process into a single value at the @c root. The | |
* values can be combined arbitrarily, specified via a function | |
* object. The type @c T of the values may be any type that is | |
* serializable or has an associated MPI data type. One can think of | |
* this operation as a @c gather to the @p root, followed by an @c | |
* std::accumulate() over the gathered values and using the operation | |
* @c op. | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Reduce to perform the reduction. If possible, | |
* built-in MPI operations will be used; otherwise, @c reduce() will | |
* create a custom MPI_Op for the call to MPI_Reduce. | |
* | |
* @param comm The communicator over which the reduction will | |
* occur. | |
* | |
* @param in_value The local value to be combined with the local | |
* values of every other process. For reducing arrays, @c in_values | |
* contains a pointer to the local values. In this case, @c n is | |
* the number of values that will be reduced. Reduction occurs | |
* independently for each of the @p n values referenced by @p | |
* in_values, e.g., calling reduce on an array of @p n values is | |
* like calling @c reduce @p n separate times, one for each | |
* location in @p in_values and @p out_values. | |
* | |
* @param out_value Will receive the result of the reduction | |
* operation, but only for the @p root process. Non-root processes | |
* may omit if parameter; if they choose to supply the parameter, | |
* it will be unchanged. For reducing arrays, @c out_values | |
* contains a pointer to the storage for the output values. | |
* | |
* @param op The binary operation that combines two values of type | |
* @c T into a third value of type @c T. For types @c T that has | |
* ssociated MPI data types, @c op will either be translated into | |
* an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped | |
* directly to a built-in MPI operation. See @c is_mpi_op in the @c | |
* operations.hpp header for more details on this mapping. For any | |
* non-built-in operation, commutativity will be determined by the | |
* @c is_commmutative trait (also in @c operations.hpp): users are | |
* encouraged to mark commutative operations as such, because it | |
* gives the implementation additional lattitude to optimize the | |
* reduction operation. | |
* | |
* @param root The process ID number that will receive the final, | |
* combined value. This value must be the same on all processes. | |
*/ | |
template<typename T, typename Op> | |
void | |
reduce(const communicator& comm, const T& in_value, T& out_value, Op op, | |
int root); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
void reduce(const communicator& comm, const T& in_value, Op op, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
void | |
reduce(const communicator& comm, const T* in_values, int n, T* out_values, | |
Op op, int root); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
void | |
reduce(const communicator& comm, const T* in_values, int n, Op op, int root); | |
/** | |
* @brief Compute a prefix reduction of values from all processes in | |
* the communicator. | |
* | |
* @c scan is a collective algorithm that combines the values stored | |
* by each process with the values of all processes with a smaller | |
* rank. The values can be arbitrarily combined, specified via a | |
* function object @p op. The type @c T of the values may be any type | |
* that is serializable or has an associated MPI data type. One can | |
* think of this operation as a @c gather to some process, followed | |
* by an @c std::prefix_sum() over the gathered values using the | |
* operation @c op. The ith process returns the ith value emitted by | |
* @c std::prefix_sum(). | |
* | |
* When the type @c T has an associated MPI data type, this routine | |
* invokes @c MPI_Scan to perform the reduction. If possible, | |
* built-in MPI operations will be used; otherwise, @c scan() will | |
* create a custom @c MPI_Op for the call to MPI_Scan. | |
* | |
* @param comm The communicator over which the prefix reduction | |
* will occur. | |
* | |
* @param in_value The local value to be combined with the local | |
* values of other processes. For the array variant, the @c | |
* in_values parameter points to the @c n local values that will be | |
* combined. | |
* | |
* @param out_value If provided, the ith process will receive the | |
* value @c op(in_value[0], op(in_value[1], op(..., in_value[i]) | |
* ... )). For the array variant, @c out_values contains a pointer | |
* to storage for the @c n output values. The prefix reduction | |
* occurs independently for each of the @p n values referenced by | |
* @p in_values, e.g., calling scan on an array of @p n values is | |
* like calling @c scan @p n separate times, one for each location | |
* in @p in_values and @p out_values. | |
* | |
* @param op The binary operation that combines two values of type | |
* @c T into a third value of type @c T. For types @c T that has | |
* ssociated MPI data types, @c op will either be translated into | |
* an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped | |
* directly to a built-in MPI operation. See @c is_mpi_op in the @c | |
* operations.hpp header for more details on this mapping. For any | |
* non-built-in operation, commutativity will be determined by the | |
* @c is_commmutative trait (also in @c operations.hpp). | |
* | |
* @returns If no @p out_value parameter is provided, returns the | |
* result of prefix reduction. | |
*/ | |
template<typename T, typename Op> | |
void | |
scan(const communicator& comm, const T& in_value, T& out_value, Op op); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
T | |
scan(const communicator& comm, const T& in_value, Op op); | |
/** | |
* \overload | |
*/ | |
template<typename T, typename Op> | |
void | |
scan(const communicator& comm, const T* in_values, int n, T* out_values, Op op); | |
} } // end namespace boost::mpi | |
#endif // BOOST_MPI_COLLECTIVES_HPP | |
#ifndef BOOST_MPI_COLLECTIVES_FORWARD_ONLY | |
// Include implementations of each of the collectives | |
# include <boost/mpi/collectives/all_gather.hpp> | |
# include <boost/mpi/collectives/all_reduce.hpp> | |
# include <boost/mpi/collectives/all_to_all.hpp> | |
# include <boost/mpi/collectives/broadcast.hpp> | |
# include <boost/mpi/collectives/gather.hpp> | |
# include <boost/mpi/collectives/scatter.hpp> | |
# include <boost/mpi/collectives/reduce.hpp> | |
# include <boost/mpi/collectives/scan.hpp> | |
#endif | |