boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Tutorial</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../mpi.html" title="Chapter 20. Boost.MPI"> <link rel="prev" href="getting_started.html" title="Getting started"> <link rel="next" href="reference.html" title="Reference"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="getting_started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../mpi.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="mpi.tutorial"></a>Tutorial</h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="tutorial.html#mpi.point_to_point">Point-to-Point communication</a></dt> <dt><a href="tutorial.html#mpi.collectives">Collective operations</a></dt> <dt><a href="tutorial.html#mpi.communicators">Managing communicators</a></dt> <dt><a href="tutorial.html#mpi.skeleton_and_content">Separating structure from content</a></dt> <dt><a href="tutorial.html#mpi.performance_optimizations">Performance optimizations</a></dt> <dt><a href="tutorial.html#mpi.c_mapping">Mapping from C MPI to Boost.MPI</a></dt> </dl></div> A Boost.MPI program consists of many cooperating processes (possibly running on different computers) that communicate among themselves by passing messages. Boost.MPI is a library (as is the lower-level MPI), not a language, so the first step in a Boost.MPI is to create an <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code> object that initializes the MPI environment and enables communication among the processes. The <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code> object is initialized with the program arguments (which it may modify) in your main program. The creation of this object initializes MPI, and its destruction will finalize MPI. In the vast majority of Boost.MPI programs, an instance of <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code> will be declared in <code class="computeroutput">main</code> at the very beginning of the program. Communication with MPI always occurs over a communicator, which can be created be simply default-constructing an object of type <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">mpi::communicator</a></code>. This communicator can then be queried to determine how many processes are running (the "size" of the communicator) and to give a unique number to each process, from zero to the size of the communicator (i.e., the "rank" of the process): <pre class="programlisting">#include <boost/mpi/environment.hpp> #include <boost/mpi/communicator.hpp> #include <iostream> namespace mpi = boost::mpi; int main() { mpi::environment env; mpi::communicator world; std::cout << "I am process " << world.rank() << " of " << world.size() << "." << std::endl; return 0; } </pre> If you run this program with 7 processes, for instance, you will receive output such as: <pre class="programlisting">I am process 5 of 7. I am process 0 of 7. I am process 1 of 7. I am process 6 of 7. I am process 2 of 7. I am process 4 of 7. I am process 3 of 7. </pre> Of course, the processes can execute in a different order each time, so the ranks might not be strictly increasing. More interestingly, the text could come out completely garbled, because one process can start writing "I am a process" before another process has finished writing "of 7.". If you should still have an MPI library supporting only MPI 1.1 you will need to pass the command line arguments to the environment constructor as shown in this example: <pre class="programlisting">#include <boost/mpi/environment.hpp> #include <boost/mpi/communicator.hpp> #include <iostream> namespace mpi = boost::mpi; int main(int argc, char* argv[]) { mpi::environment env(argc, argv); mpi::communicator world; std::cout << "I am process " << world.rank() << " of " << world.size() << "." << std::endl; return 0; } </pre> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="mpi.point_to_point"></a>Point-to-Point communication</h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="tutorial.html#mpi.nonblocking">Non-blocking communication</a></dt> <dt><a href="tutorial.html#mpi.user_data_types">User-defined data types</a></dt> </dl></div> As a message passing library, MPI's primary purpose is to routine messages from one process to another, i.e., point-to-point. MPI contains routines that can send messages, receive messages, and query whether messages are available. Each message has a source process, a target process, a tag, and a payload containing arbitrary data. The source and target processes are the ranks of the sender and receiver of the message, respectively. Tags are integers that allow the receiver to distinguish between different messages coming from the same sender. The following program uses two MPI processes to write "Hello, world!" to the screen (<code class="computeroutput">hello_world.cpp</code>): <pre class="programlisting">#include <boost/mpi.hpp> #include <iostream> #include <string> #include <boost/serialization/string.hpp> namespace mpi = boost::mpi; int main() { mpi::environment env; mpi::communicator world; if (world.rank() == 0) { world.send(1, 0, std::string("Hello")); std::string msg; world.recv(1, 1, msg); std::cout << msg << "!" << std::endl; } else { std::string msg; world.recv(0, 0, msg); std::cout << msg << ", "; std::cout.flush(); world.send(0, 1, std::string("world")); } return 0; } </pre> The first processor (rank 0) passes the message "Hello" to the second processor (rank 1) using tag 0. The second processor prints the string it receives, along with a comma, then passes the message "world" back to processor 0 with a different tag. The first processor then writes this message with the "!" and exits. All sends are accomplished with the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp229859664-bb">communicator::send</a></code> method and all receives use a corresponding <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp153560864-bb">communicator::recv</a></code> call. <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="mpi.nonblocking"></a>Non-blocking communication</h4></div></div></div> The default MPI communication operations--<code class="computeroutput">send</code> and <code class="computeroutput">recv</code>--may have to wait until the entire transmission is completed before they can return. Sometimes this blocking behavior has a negative impact on performance, because the sender could be performing useful computation while it is waiting for the transmission to occur. More important, however, are the cases where several communication operations must occur simultaneously, e.g., a process will both send and receive at the same time. Let's revisit our "Hello, world!" program from the previous section. The core of this program transmits two messages: <pre class="programlisting">if (world.rank() == 0) { world.send(1, 0, std::string("Hello")); std::string msg; world.recv(1, 1, msg); std::cout << msg << "!" << std::endl; } else { std::string msg; world.recv(0, 0, msg); std::cout << msg << ", "; std::cout.flush(); world.send(0, 1, std::string("world")); } </pre> The first process passes a message to the second process, then prepares to receive a message. The second process does the send and receive in the opposite order. However, this sequence of events is just that--a sequence--meaning that there is essentially no parallelism. We can use non-blocking communication to ensure that the two messages are transmitted simultaneously (<code class="computeroutput">hello_world_nonblocking.cpp</code>): <pre class="programlisting">#include <boost/mpi.hpp> #include <iostream> #include <string> #include <boost/serialization/string.hpp> namespace mpi = boost::mpi; int main() { mpi::environment env; mpi::communicator world; if (world.rank() == 0) { mpi::request reqs[2]; std::string msg, out_msg = "Hello"; reqs[0] = world.isend(1, 0, out_msg); reqs[1] = world.irecv(1, 1, msg); mpi::wait_all(reqs, reqs + 2); std::cout << msg << "!" << std::endl; } else { mpi::request reqs[2]; std::string msg, out_msg = "world"; reqs[0] = world.isend(0, 1, out_msg); reqs[1] = world.irecv(0, 0, msg); mpi::wait_all(reqs, reqs + 2); std::cout << msg << ", "; } return 0; } </pre> We have replaced calls to the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp229859664-bb">communicator::send</a></code> and <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp153560864-bb">communicator::recv</a></code> members with similar calls to their non-blocking counterparts, <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp228678816-bb">communicator::isend</a></code> and <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp212820160-bb">communicator::irecv</a></code>. The prefix i indicates that the operations return immediately with a <code class="computeroutput"><a class="link" href="../boost/mpi/request.html" title="Class request">mpi::request</a></code> object, which allows one to query the status of a communication request (see the <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp229982656-bb">test</a></code> method) or wait until it has completed (see the <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp229980832-bb">wait</a></code> method). Multiple requests can be completed at the same time with the <code class="computeroutput"><a class="link" href="../boost/mpi/wait_all.html" title="Function wait_all">wait_all</a></code> operation. Important note: The MPI standard requires users to keep the request handle for a non-blocking communication, and to call the "wait" operation (or successfully test for completion) to complete the send or receive. Unlike most C MPI implementations, which allow the user to discard the request for a non-blocking send, Boost.MPI requires the user to call "wait" or "test", since the request object might contain temporary buffers that have to be kept until the send is completed. Moreover, the MPI standard does not guarantee that the receive makes any progress before a call to "wait" or "test", although most implementations of the C MPI do allow receives to progress before the call to "wait" or "test". Boost.MPI, on the other hand, generally requires "test" or "wait" calls to make progress. If you run this program multiple times, you may see some strange results: namely, some runs will produce: <pre class="programlisting">Hello, world! </pre> while others will produce: <pre class="programlisting">world! Hello, </pre> or even some garbled version of the letters in "Hello" and "world". This indicates that there is some parallelism in the program, because after both messages are (simultaneously) transmitted, both processes will concurrent execute their print statements. For both performance and correctness, non-blocking communication operations are critical to many parallel applications using MPI. </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="mpi.user_data_types"></a>User-defined data types</h4></div></div></div> The inclusion of <code class="computeroutput">boost/serialization/string.hpp</code> in the previous examples is very important: it makes values of type <code class="computeroutput">std::string</code> serializable, so that they can be be transmitted using Boost.MPI. In general, built-in C++ types (<code class="computeroutput">int</code>s, <code class="computeroutput">float</code>s, characters, etc.) can be transmitted over MPI directly, while user-defined and library-defined types will need to first be serialized (packed) into a format that is amenable to transmission. Boost.MPI relies on the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a> library to serialize and deserialize data types. For types defined by the standard library (such as <code class="computeroutput">std::string</code> or <code class="computeroutput">std::vector</code>) and some types in Boost (such as <code class="computeroutput">boost::variant</code>), the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a> library already contains all of the required serialization code. In these cases, you need only include the appropriate header from the <code class="computeroutput">boost/serialization</code> directory. For types that do not already have a serialization header, you will first need to implement serialization code before the types can be transmitted using Boost.MPI. Consider a simple class <code class="computeroutput">gps_position</code> that contains members <code class="computeroutput">degrees</code>, <code class="computeroutput">minutes</code>, and <code class="computeroutput">seconds</code>. This class is made serializable by making it a friend of <code class="computeroutput">boost::serialization::access</code> and introducing the templated <code class="computeroutput">serialize()</code> function, as follows: <pre class="programlisting">class gps_position { private: friend class boost::serialization::access; template<class Archive> void serialize(Archive & ar, const unsigned int version) { ar & degrees; ar & minutes; ar & seconds; } int degrees; int minutes; float seconds; public: gps_position(){}; gps_position(int d, int m, float s) : degrees(d), minutes(m), seconds(s) {} }; </pre> Complete information about making types serializable is beyond the scope of this tutorial. For more information, please see the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a> library tutorial from which the above example was extracted. One important side benefit of making types serializable for Boost.MPI is that they become serializable for any other usage, such as storing the objects to disk to manipulated them in XML. Some serializable types, like <code class="computeroutput">gps_position</code> above, have a fixed amount of data stored at fixed field positions. When this is the case, Boost.MPI can optimize their serialization and transmission to avoid extraneous copy operations. To enable this optimization, users should specialize the type trait <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code>, e.g.: <pre class="programlisting">namespace boost { namespace mpi { template <> struct is_mpi_datatype<gps_position> : mpl::true_ { }; } } </pre> For non-template types we have defined a macro to simplify declaring a type as an MPI datatype <pre class="programlisting">BOOST_IS_MPI_DATATYPE(gps_position) </pre> For composite traits, the specialization of <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code> may depend on <code class="computeroutput">is_mpi_datatype</code> itself. For instance, a <code class="computeroutput">boost::array</code> object is fixed only when the type of the parameter it stores is fixed: <pre class="programlisting">namespace boost { namespace mpi { template <typename T, std::size_t N> struct is_mpi_datatype<array<T, N> > : public is_mpi_datatype<T> { }; } } </pre> The redundant copy elimination optimization can only be applied when the shape of the data type is completely fixed. Variable-length types (e.g., strings, linked lists) and types that store pointers cannot use the optimiation, but Boost.MPI will be unable to detect this error at compile time. Attempting to perform this optimization when it is not correct will likely result in segmentation faults and other strange program behavior. Boost.MPI can transmit any user-defined data type from one process to another. Built-in types can be transmitted without any extra effort; library-defined types require the inclusion of a serialization header; and user-defined types will require the addition of serialization code. Fixed data types can be optimized for transmission using the <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code> type trait. </div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="mpi.collectives"></a>Collective operations</h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="tutorial.html#mpi.broadcast">Broadcast</a></dt> <dt><a href="tutorial.html#mpi.gather">Gather</a></dt> <dt><a href="tutorial.html#mpi.reduce">Reduce</a></dt> </dl></div> <a class="link" href="tutorial.html#mpi.point_to_point" title="Point-to-Point communication">Point-to-point operations</a> are the core message passing primitives in Boost.MPI. However, many message-passing applications also require higher-level communication algorithms that combine or summarize the data stored on many different processes. These algorithms support many common tasks such as "broadcast this value to all processes", "compute the sum of the values on all processors" or "find the global minimum." <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="mpi.broadcast"></a>Broadcast</h4></div></div></div> The <code class="computeroutput"><a class="link" href="../boost/mpi/broadcast.html" title="Function broadcast">broadcast</a></code> algorithm is by far the simplest collective operation. It broadcasts a value from a single process to all other processes within a <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>. For instance, the following program broadcasts "Hello, World!" from process 0 to every other process. (<code class="computeroutput">hello_world_broadcast.cpp</code>) <pre class="programlisting">#include <boost/mpi.hpp> #include <iostream> #include <string> #include <boost/serialization/string.hpp> namespace mpi = boost::mpi; int main() { mpi::environment env; mpi::communicator world; std::string value; if (world.rank() == 0) { value = "Hello, World!"; } broadcast(world, value, 0); std::cout << "Process #" << world.rank() << " says " << value << std::endl; return 0; } </pre> Runnin