The Multicast/Reduction Network: A User's Guide to MRNet

MRNet has been developed to be highly portable; there is no reason why it should not run properly on all common Unix-based platforms. This being said, we have successfully built and tested MRNet using GCC version 3 compilers on the following systems:

We are currently upgrading our build system to allow the use of native compilers where appropriate, for instance, xlc and xlC in AIX environments.

Here we list the third party tools that MRNet uses and needs for proper installation:

MRNet uses GNU autoconf to discover the platform specific configuration parameters. The script that does this auto-configuration is called configure.

UNIX>  ./configure --help

shows all possible options of the command. Below, we display the MRNet-specific ones:

===Begin MRNET Compile Options:
  --with-cc                   Specify C compiler
  --with-cflags               Set C compiler flags
                                  - (ONLY USE WITH --with-cc)
  --with-cxx                  Specify C++ compiler
  --with-cxxflags             Set C++ compiler flags
                                  - (ONLY USE WITH --with-cxx)
  --with-ldflags              Set loader flags
  --with-libfl                Link line for flex library

For example,

UNIX> ./configure --with-cc=cc --with-cxx=c++ --with-libfl=/usr/local/lib/libfl.a

instructs the configure script to use cc for the C compiler, c++ for the C++ compiler and /usr/local/lib/libfl.a as the location of the flex library.

To build the MRNet toolkit by type:

UNIX>  make

After a successful build, the following files will be present:

MRNet is maintained by Dorian Arnold at the University of Wisconsin. Comments and other feedback whether positive or negative are welcome.

Please report bugs to darnold@cs.wisc.edu.

The MRNet webpage is http://www.paradyn.org/mrnet/

MRNet uses communicators to represent groups of network end-points. Like communicators in MPI, MRNet communicators provide a handle that identifies a set of end-points for point-to-point, multicast or broadcast communications. MPI applications typically have a non-hierarchical layout of potentially identical processes. In contrast, MRNet enforces a tree-like layout of all processes, rooted at the tool front-end. Accordingly, MRNet communicators are created and managed by the front-end, and communication is only allowed between a tool's front-end and its back-ends, i.e. back-ends cannot interact with each other directly via MRNet.

A stream is a logical channel that connects the front-end to the end-points of a communicator. All tool-level communication via MRNet must use these streams. Streams carry data packets downstream, from the front-end toward the back-ends, and upstream, from the back-ends toward the front-end. Upward streams are expected to carry data of a specific type allowing data aggregation operations to be associated with a stream. The type is specified using a format string (See Appendix A, MRNET Format Strings) similar to those used in C formatted I/O primitives, e.g. a packet whose data is described by the format string "%d %d %f %s" contains two integers followed by a float then a character string. MRNet expands the standard specification to allow for specifiers that describe arrays of integers and floats.

Data Aggregation is the process of merging multiple input data packets and transforming them into one or more output packets. Though it is not necessary for the aggregation to result in less or even different data, aggregations that reduce or modify data values are most common. MRNet uses data filters to aggregate data packets. Filters specify an operation to perform and the type of the data expected on the bound stream. Filter instances are bound to a stream at stream creation. MRNet uses two types of filters: synchronization filters and transformation filters. Synchronization filters organize data packets from downstream nodes into synchronized waves of data packets, while transformation filters operate on the synchronized data packets yielding one or more output packets.

Filters operate on data flowing upstream in the network. Synchronization filters receive packets one at a time and do not output any packets until the specified synchronization criteria has occurred. Transformation filters input the group of synchronized packets, perform some type of data transformation on the data contained in the packets and output one or more packets. A distinction between synchronization and transformation filters is that synchronization filters are independent of the packet data type, but transformation filters operate on packets of a specific type. Synchronization filters provide a mechanism to deal with the asynchronous rrival of packets from children nodes; the synchronizer collects packets and typically aligns them into waves, passing an entire wave onward at the same time. Therefore, synchronization filters do no data transformation and can operate on packets in a type-independent fashion. MRNet currently supports three synchronization modes:

Transformation filters combine data from multiple packets by performing an aggregation that yields one or more new data packets. Since transformation filters are expected to perform computational operations on data packets, there is a type requirement for the data packets to be passed to this type of filter: the data format string of the stream's packets and the filter must be the same. Transformation operations must be synchronous, but can carry state from one transformation to the next using static storage structures. MRNet provides several transformation filters that should be of general use:

Chapter 7, Adding New Aggregation Filters describes facilities a tool developer may use to add new filters to the provided set.

A complete description of the MRNet API is in Chapter 5, The MRNet C++ API Reference. This section offers a brief overview only. Using libmrnet.a, a tool can leverage a system of internal processes, instances of the mrnet_commnode program, as a communication substrate. After instantiation of the MRNet network (discussed in the section called “MRNet Instantiation”, the front-end and back-end processes are connected by the internal processes. The connection topology and host assignment of these processes is determined by a configuration file, thus the geometry of MRNet's process tree can be customized to suit the physical topology of the underlying hardware resources. While MRNet can generate a variety of standard topologies, users can easily specify their own topologies; see Chapter 6, MRNET Process-tree Topologies for further discussion.

The MRNet API, provided by libmrnet, contains network, end-point, communicator, and stream objects that a tool's front-end and back-end use for communication. The network object is used to instantiate the MRNet network and access end-point objects that represent available tool back-ends. The communicator object is a container for groups of end-points, and streams are used to send data to the end-points in a communicator.

   front_end_main(){
1.   MR_Network * net;
2.   MR_Communicator * comm;
3.   MR_Stream * stream;
4.   float result;
5.   net = new MR_Network(config_file);
6.   comm = net->get_broadcast_communicator( );
7.   stream = new MR_Stream(comm, FMAX_FIL);
8.   stream->send("%d", FLOAT_MAX_INIT);
9.   stream->recv("%f", result);
   }

A simplified version of code from an example tool front-end is shown in Figure 4.1. In the front-end code, after some variable definitions in lines 1-4, in line 5, an instance of the MRNet network is created using the topology specification in config_file. In line 6, the newly created network object is queried for an auto-generated broadcast communicator that contains all available end-points. In line 7, this communicator is used to established a stream for which the MRNet internal processes will use a filter that finds the maximum floating point data value of the data sent upstream. The front-end then might send one or more initialization messages to the backends; in our example code on line 9, we broadcast an integer initializer and await the single floating point value result.

   back_end_main(){
1.   MR_Stream * stream;
2.   int val;
3.   MR_Network::init_backend( );
4.   MR_Stream::recv("%d", &val, &stream);
5.   if(val == FLOAT_MAX_INIT){
6.      stream->send("%f", rand_float);
     }
   }

Figure 4.2 shows the code for the back-end that reciprocates the actions of the front-end. Each tool back-end first connects to the appropriate internal process, via the init_backend call in line 3. While the front-end makes a stream-specific recv call, the back-ends make a stream-anonymous recv that returns the integer sent by the front-end along with a stream object representing the stream that the front-end has established. Finally, each back-end sends a scalar floating point value upstream toward the front-end.

A complete example of MRNet code can be found in Appendix B, A Complete MRNet Example.

While conceptually simple, creating and connecting the internal processes is complicated by interactions with the various job scheduling systems. In the simplest environments, we can launch jobs manually using facilities like rsh or ssh. In more complex environments, it is necessary to submit all requests to a job management system. In this case, we are constrained by the operations provided by the job manager (and these vary from system to system). We currently support two modes of instantiating MRNet-based tools.

In the first mode of process instantiation, MRNet creates the internal and back-end processes, using the specified MRNet topology configuration to determine the hosts on which the components should be located. First, the front-end consults the configuration and uses rsh or ssh to create internal processes for the first level of the communication tree on the appropriate hosts. Upon instantiation, the newly created processes establish a network connection to the process that created it. The first activity on this connection is a message from parent to child containing the portion of the configuration relevant to that child. The child then uses this information to begin instantiation of the sub-tree rooted at that child. When a sub-tree has been established, the root of that sub-tree sends a report to its parent containing the end-points accessible via that sub-tree. Each internal node establishes its children processes and their respective connections sequentially. However, since the various processes are expected to run on different compute nodes, sub-trees in different branches of the network are created in concurrently, maximizing the efficiency of network instantiation.

In the second mode of process instantiation, MRNet relies on a process management system to create some or all of the MRNet processes. This mode accommodates tools that require their back-ends to create, monitor, and control the application processes. For example, IBM's POE uses environment variables to pass information, such as the process' rank within the application's global MPI communicator, to the MPI run-time library in each application process. In cases like this, MRNet cannot provide back-end processes with the environment necessary to start MPI application processes. As a result, MRNet creates its internal processes recursively as in the first instantiation mode, but does not instantiates any back-end processes. MRNet then starts the tool back-ends using the process management system to ensure they have the environment needed to create application processes successfully. When starting the back-ends, MRNet must provide them with the information needed to connect to the MRNet internal process tree, such as the leaf processes' host names and connection port numbers. This information is provided via the environment, using shared filesystems or other information services as available on the target system.