Package edu.rit.pj

Class Comm

java.lang.Object

edu.rit.pj.Comm

public class Comm
extends Object

Class Comm provides a communicator for a PJ cluster parallel program. Class Comm provides a method to initialize the PJ message passing middleware and run the parallel program on multiple processors of a cluster parallel computer. Class Comm also provides methods for passing messages between the processes of the parallel program.

BASIC CONCEPTS

A cluster parallel computer typically consists of a frontend processor and a number of backend processors connected via a dedicated high-speed network. A user logs into the frontend processor and runs a PJ program there. The PJ message passing middleware causes copies of the PJ program to run in a number of separate processes, each process on a different backend processor. The backend processes run the PJ program, using the PJ middleware to send messages amongst themselves. The PJ middleware redirects the backend processes' standard output and standard error streams to the frontend process. The frontend process does not actually execute the PJ program, but merely displays all the backend processes' standard output and standard error streams on the frontend process's own standard output and standard error.

For the PJ message passing middleware to work, certain server processes must be running. See package edu.rit.pj.cluster for further informati on.

To initialize the PJ message passing middleware, the program must first call the static Comm.init() method, passing in the command line arguments.

A communicator is associated with a group of backend processes. The communicator's size is the number of processes in the group. Each process in the communicator has a different rank in the range 0 .. size-1. A process may obtain the size and rank by calling the communicator's size() and rank() methods.

There is one predefined communicator, the world communicator, consisting of all the backend processes in the parallel program. A process may obtain a reference to the world communicator by calling the static Comm.world() method. Typically, the first few lines in a PJ cluster parallel program look like this:

 public class AParallelProgram
 {
 public static void main
 (String[] args)
 throws Exception
 {
 Comm.init (args);
 Comm world = Comm.world();
 int size = world.size();
 int rank = world.rank();
 . . .

The number of processes in the parallel program -- that is, the size of the world communicator -- is specified by the "pj.np" property, which must be an integer greater than or equal to 1. You can specify the number of processes on the Java command line like this:

 java -Dpj.np=4 . . .

If the "pj.np" property is not specified, the default is 1.

The PJ program will run on the specified number of backend processors as described above. To determine which backend processors to use, the PJ program interacts with a Job Scheduler server process running on the frontend processor. When the PJ program starts and calls the Comm.init() method, the middleware first prints the job number on the standard error. The middleware then waits until the required number of backend processors are ready to run a job. As each backend processor becomes ready, the middleware prints on the standard error the name of each backend processor assigned to the job. Once all are ready, the PJ program starts running on those backend processors, and all further output comes from the PJ program. Since each PJ program interacts with the Job Scheduler, the Job Scheduler can ensure that each backend processor is running a backend process for only one job at a time.

Depending on the system load, your PJ program may have to wait in the Job Scheduler's queue for a while until enough backend processors become ready. If you get tired of waiting, you can kill your PJ program (e.g., by typing CTRL-C), which will remove your PJ program from the Job Scheduler's queue.

The Job Scheduler has a web interface that lets you examine the cluster status. Just point your web browser at this URL: http://<hostname>:8080/

where <hostname> is replaced by the host name of the frontend processor. The default port for the cluster status web interface is port 8080. The Job Scheduler can be configured to use a different port. For further information, see package edu.rit.pj.cluster.

If the PJ program is executed on a host where no Job Scheduler is running, the PJ program will run in one process on that host (i.e., the machine you're logged into), rather than on the backend processors. The message passing methods in class Comm will still work, though. This option can be useful for debugging a PJ program's logic on a non-parallel machine before running the PJ program on a cluster.

MESSAGE PASSING

PJ provides two categories of communication, point-to-point communication and collective communication. The following methods of class Comm are used for point-to-point communication:

• send()
• receive()
• sendReceive()
• floodSend()
• floodReceive()

The following methods are used for collective communication:

• broadcast()
• scatter()
• gather()
• allGather()
• reduce()
• allReduce()
• allToAll()
• scan()
• exclusiveScan()
• barrier()

These methods are described further in the sections below.

In addition, you can create a new communicator consisting of all, or a subset of, the processes in an existing communicator. Message passing in the new communicator is completely independent of message passing in the original communicator. The following method creates a new communicator:

• createComm()

POINT-TO-POINT COMMUNICATION

One process in a PJ cluster parallel program, the source process, may use a communicator to send a message to another process in the program, the destination process. This is called a point-to-point communication because just the two processes are involved (as opposed to a collective communication, which involves all the processes). Five point-to-point communication methods are available in this release: send, receive, send-receive, flood-send, and flood-receive.

Send and Receive

To do a point-to-point communication, the source process calls the send() method on a certain communicator, such as the world communicator. The source process specifies the destination process's rank, the tag for the message, and a buffer containing the data items to be sent (type Buf). Likewise, the destination process calls the receive() method on the same communicator as the source process. The destination process specifies the source process's rank, the message tag which must be the same as in the source process, and the buffer for the data items to be received.

A send() method call and a receive() method call are said to match if (a) the rank passed to the send() method equals the rank of the process calling receive(), (b) the rank passed to the receive() method equals the rank of the process calling send(), (c) the item data type in the source buffer is the same as the item data type in the destination buffer, and (d) the send message tag equals the receive message tag. A receive() method call will block until a matching send() method call occurs. If more than one send() method call matches a receive() method call, one of the matching send() method calls is picked in an unspecified manner. A send() method call may block until a matching receive() method call occurs due to flow control in the underlying network communication.

The message tag can be used to distinguish different kinds of messages. A receive() method call will only match a send() method call with the same tag. If there is no need to distinguish different kinds of messages, omit the tag (it will default to 0).

Once a send() method call and a receive() method call have been matched together, the actual message data transfer takes place. Each item in the source buffer, starting at index 0 and continuing for the entire length of the source buffer, is written to the message. At the other end, each item in the destination buffer, starting at index 0, is read from the message.

The receive() method returns a CommStatus object. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the destination buffer, nothing is stored into the extra data items at the end of the destination buffer. If the actual number of data items in the message is greater than the length of the destination buffer, the extra data items at the end of the message are discarded.

The send() method does not return until all the message elements have been written from the source buffer. Likewise, the receive() method does not return until all the message elements have been read into the destination buffer. However, you cannot assume that because the send() method has returned, the matching receive() method has also returned. Because of buffering in the underlying network communication, not all the destination items might have been received even though all the source items have been sent.

The destination process, instead of specifying a particular source process, can declare that it will receive a message from any source process by specifying null for the source process rank in the receive() method call. This is called a wildcard source. In this case the receive() method call's returned status object will indicate the actual source process that sent the message.

The destination process, instead of specifying a particular message tag, can declare that it will receive a message with any tag by specifying null for the tag in the receive() method call. This is called a wildcard tag. Alternatively, the destination process can specify a range of message tags, and it will receive a message with any tag in the given range. In these cases the receive() method call's returned status object will indicate the actual message tag that was sent.

A process can send a message to itself. In this case one thread must call send() (specifying the process's own rank as the destination) and a different thread must call receive() (specifying the process's own rank as the source), otherwise a deadlock will ensue.

Send-Receive

By calling the sendReceive() method, a process can send a buffer of outgoing message items to a destination process while simultaneously receiving a buffer of incoming message items from a source process. The destination process may be the same as the source process, or different from the source process. The outgoing message items must come from a different place than where the incoming message items will be stored, otherwise the incoming message items may overwrite the outgoing message items before they can be sent. When the sendReceive() method returns, the outgoing message items have been fully sent, but they may not yet have been fully received; and the incoming message items have been fully received.

With the sendReceive() method, a process cannot receive a message from a wildcard source, and a process cannot receive a message with a wildcard tag or a range of tags. The process calling sendReceive() must know the rank of the source process and the message tag (if not 0). The sendReceive() method does return a status object giving the outcome of the receive half of the send-receive operation, just as the receive() method does.

A process can send-receive messages with itself. In this case one thread must call sendReceive() (specifying the process's own rank as the source and destination) and a different thread must also call sendReceive() (specifying the process's own rank as the source and destination), otherwise a deadlock will ensue.

Non-Blocking Communication

The send(), receive(), and sendReceive() methods each have a non-blocking version. A non-blocking communication method initiates the communication operation and immediately returns, storing the state of the communication operation in a CommRequest object. The communicator then performs the communication operation in a separate thread. This allows the calling thread to do other work while the communication operation is in progress. To wait for the send and receive operations to finish, call the CommRequest object's waitForFinish() method.

Flood-Send and Flood-Receive

Any process can send a message to all processes in the communicator. This is called "flooding" the message. First, all processes must start a flood-receive operation, either by calling the non-blocking floodReceive() method, or by having a separate thread call the blocking floodReceive() method. Then, one process (any process) must call the floodSend() method. The data items in the flood-send operation's outgoing buffer are copied into the flood-receive operation's incoming buffer in all processes.

Message flooding is similar to the "broadcast" collective communication operation (see below). The differences are these: Broadcasting combines sending and receiving in a single operation; flooding uses separate send and receive operations. For broadcasting, every process must know which process is sending the outgoing data items; for flooding, the receiving processes do not need to know which process is sending (any process can send).

COLLECTIVE COMMUNICATION

A PJ cluster parallel program may use a communicator to send a message among all the processes in the program at the same time. This is called a collective communication because all the processes in the communicator are involved (as opposed to a point-to-point communication). Ten collective communication methods are available in this release: broadcast, scatter, gather, all-gather, reduce, all-reduce, all-to-all, scan, exclusive-scan, and barrier. Further collective communication methods will be added to class Comm in a later release.

Broadcast

One process in the communicator, the root process, has a source buffer (type Buf) filled with data. The other processes in the communicator each have a destination buffer with the same length and the same item data type as the source buffer. Each process calls the communicator's broadcast() method. Afterwards, all the destination buffers contain the same data as the source buffer.

Before and After Broadcast.

Before: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 1 | | | | | | | | 2 | | | | | | | | 3 | | | | | | | | 4 | | | | | | | | 5 | | | | | | | | 6 | | | | | | | | 7 | | | | | | | | 8 | | | | | | | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 1 | | 1 | | 1 | | 2 | | 2 | | 2 | | 2 | | 3 | | 3 | | 3 | | 3 | | 4 | | 4 | | 4 | | 4 | | 5 | | 5 | | 5 | | 5 | | 6 | | 6 | | 6 | | 6 | | 7 | | 7 | | 7 | | 7 | | 8 | | 8 | | 8 | | 8 | +----+ +----+ +----+ +----+

Note: Any process can be the root of the broadcast. The above is only one example with process 0 as the root.

Scatter

One process in the communicator, the root process, has K source buffers (type Buf) filled with data, where K is the size of the communicator. For example, the source buffers could be different portions of an array. Each process in the communicator (including the root process) has a destination buffer with the same length and the same item data type as the corresponding source buffer. Each process calls the communicator's scatter() method. Afterwards, each process's destination buffer contains the same data as the corresponding source buffer in the root process.

Scatter.

Before: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ | 3 | | 4 | +----+ | 5 | | 6 | +----+ | 7 | | 8 | +----+ +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ | 3 | | 4 | +----+ | 5 | | 6 | +----+ | 7 | | 8 | +----+ +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+

In the root process, the destination buffer can be the same as the source buffer:

Scatter

Before: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ +----+ | 3 | | | | 4 | | | +----+ +----+ +----+ | 5 | | | | 6 | | | +----+ +----+ +----+ | 7 | | | | 8 | | | +----+ +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ +----+ | 3 | | 3 | | 4 | | 4 | +----+ +----+ +----+ | 5 | | 5 | | 6 | | 6 | +----+ +----+ +----+ | 7 | | 7 | | 8 | | 8 | +----+ +----+

Note: Any process can be the root of the scatter. The above is only one example with process 0 as the root.

Gather

Gather is the opposite of scatter. One process in the communicator, the root process, has K destination buffers (type Buf), where K is the size of the communicator. For example, the destination buffers could be different portions of an array. Each process in the communicator (including the root process) has a source buffer with the same length and the same item data type as the corresponding destination buffer, filled with data. Each process calls the communicator's gather() method. Afterwards, each destination buffer in the root process contains the same data as the corresponding source buffer.

Gather

Before: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+ +----+ | | | | +----+ | | | | +----+ | | | | +----+ | | | | +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+ +----+ | 1 | | 2 | +----+ | 3 | | 4 | +----+ | 5 | | 6 | +----+ | 7 | | 8 | +----+

In the root process, the destination buffer can be the same as the source buffer:

Gather

Before: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ +----+ | | | 3 | | | | 4 | +----+ +----+ +----+ | | | 5 | | | | 6 | +----+ +----+ +----+ | | | 7 | | | | 8 | +----+ +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ | 1 | | 2 | +----+ +----+ | 3 | | 3 | | 4 | | 4 | +----+ +----+ +----+ | 5 | | 5 | | 6 | | 6 | +----+ +----+ +----+ | 7 | | 7 | | 8 | | 8 | +----+ +----+

Note: Any process can be the root of the gather. The above is only one example with process 0 as the root.

All-Gather

All-gather is the same as gather, except that every process has an array of destination buffers, and every process receives the results of the gather. Each process in the communicator has a source buffer (type Buf) filled with data. Each process in the communicator has K destination buffers, where K is the size of the communicator. For example, the destination buffers could be different portions of an array. Each destination buffer has the same length and the same item data type as the corresponding source buffer. Each process calls the communicator's allGather() method. Afterwards, each destination buffer in every process contains the same data as the corresponding source buffer.

All-Gather

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | 1 | | 1 | | 1 | | 1 | | 2 | | 2 | | 2 | | 2 | +----+ +----+ +----+ +----+ | 3 | | 3 | | 3 | | 3 | | 4 | | 4 | | 4 | | 4 | +----+ +----+ +----+ +----+ | 5 | | 5 | | 5 | | 5 | | 6 | | 6 | | 6 | | 6 | +----+ +----+ +----+ +----+ | 7 | | 7 | | 7 | | 7 | | 8 | | 8 | | 8 | | 8 | +----+ +----+ +----+ +----+

The destination buffer can be the same as the source buffer in each process:

All-Gather

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | | | | | | | 2 | | | | | | | +----+ +----+ +----+ +----+ | | | 3 | | | | | | | | 4 | | | | | +----+ +----+ +----+ +----+ | | | | | 5 | | | | | | | | 6 | | | +----+ +----+ +----+ +----+ | | | | | | | 7 | | | | | | | | 8 | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 1 | | 1 | | 1 | | 2 | | 2 | | 2 | | 2 | +----+ +----+ +----+ +----+ | 3 | | 3 | | 3 | | 3 | | 4 | | 4 | | 4 | | 4 | +----+ +----+ +----+ +----+ | 5 | | 5 | | 5 | | 5 | | 6 | | 6 | | 6 | | 6 | +----+ +----+ +----+ +----+ | 7 | | 7 | | 7 | | 7 | | 8 | | 8 | | 8 | | 8 | +----+ +----+ +----+ +----+

Reduce

Reduce is like gather, except the buffers' contents are combined together instead of just copied. Each process in the communicator has a buffer (type Buf) filled with data. Each process calls the communicator's reduce() method, specifying some binary operation (type Op) for combining the data. Afterwards, each element of the buffer in the root process contains the result of combining all the corresponding elements in all the buffers using the specified binary operation. For example, if the operation is addition, each buffer element in the root process ends up being the sum of the corresponding buffer elements in all the processes. In the non-root processes, the buffers' contents may be changed from their original contents.

Reduce

Before: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 (root) 1 2 3 +----+ +----+ +----+ +----+ | 16 | | ?? | | ?? | | ?? | | 20 | | ?? | | ?? | | ?? | +----+ +----+ +----+ +----+

Note: Any process can be the root of the reduction. The above is only one example with process 0 as the root.

All-Reduce

All-reduce is the same as reduce, except that every process receives the results of the reduction. Each process in the communicator has a buffer (type Buf) filled with data. Each process calls the communicator's allReduce() method, specifying some binary operation (type Op) for combining the data. Afterwards, each element of the buffer in each process contains the result of combining all the corresponding elements in all the buffers using the specified binary operation. For example, if the operation is addition, each buffer element ends up being the sum of the corresponding buffer elements.

All-Reduce

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 16 | | 16 | | 16 | | 16 | | 20 | | 20 | | 20 | | 20 | +----+ +----+ +----+ +----+

All-to-All

Every process in the communicator has K source buffers (type Buf) filled with data, where K is the size of the communicator. Every process in the communicator also has K destination buffers (type Buf). The source buffers and the destination buffers must refer to different storage. For example, the source buffers could be portions of an array, and the destination buffers could be portions of a different array. Each process calls the communicator's allToAll() method. Afterwards, for each process rank k, 0 <= k <= K-1, and each buffer index i, 0 <= i <= K-1, destination buffer i in process k contains the same data as source buffer k in process i.

All-to-All

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 9 | | 17 | | 25 | | 2 | | 10 | | 18 | | 26 | +----+ +----+ +----+ +----+ | 3 | | 11 | | 19 | | 27 | | 4 | | 12 | | 20 | | 28 | +----+ +----+ +----+ +----+ | 5 | | 13 | | 21 | | 29 | | 6 | | 14 | | 22 | | 30 | +----+ +----+ +----+ +----+ | 7 | | 15 | | 23 | | 31 | | 8 | | 16 | | 24 | | 32 | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+ | | | | | | | | | | | | | | | | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 9 | | 17 | | 25 | | 2 | | 10 | | 18 | | 26 | +----+ +----+ +----+ +----+ | 3 | | 11 | | 19 | | 27 | | 4 | | 12 | | 20 | | 28 | +----+ +----+ +----+ +----+ | 5 | | 13 | | 21 | | 29 | | 6 | | 14 | | 22 | | 30 | +----+ +----+ +----+ +----+ | 7 | | 15 | | 23 | | 31 | | 8 | | 16 | | 24 | | 32 | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+ | 9 | | 11 | | 13 | | 15 | | 10 | | 12 | | 14 | | 16 | +----+ +----+ +----+ +----+ | 17 | | 19 | | 21 | | 23 | | 18 | | 20 | | 22 | | 24 | +----+ +----+ +----+ +----+ | 25 | | 27 | | 29 | | 31 | | 26 | | 28 | | 30 | | 32 | +----+ +----+ +----+ +----+

Scan

Each process in the communicator has a buffer (type Buf) filled with data. Each process calls the communicator's scan() method, specifying some binary operation (type Op) for combining the data. Afterwards, each element of the buffer in a particular process contains the result of combining all the corresponding elements in its own and all lower-ranked processes' buffers using the specified binary operation. For example, if the operation is addition, each buffer element ends up being the sum of its own and all lower-ranked processes' buffer elements.

Scan

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 4 | | 9 | | 16 | | 2 | | 6 | | 12 | | 20 | +----+ +----+ +----+ +----+

The scan operation is also known as "prefix scan" or "inclusive prefix scan" -- "inclusive" because the process's own element is included in the result.

Exclusive-Scan

The exclusive-scan operation is a variation of the scan operation. Each process in the communicator has a buffer (type Buf) filled with data. Each process calls the communicator's exclusiveScan() method, specifying some binary operation (type Op) for combining the data, and specifying an initial data value. Afterwards, each element of the buffer in a particular process contains the result of combining all the corresponding elements in all lower-ranked processes' buffers using the specified binary operation, except in process 0 each element of the buffer contains the initial data value. For example, if the operation is addition and the initial data value is 0, each buffer element ends up being the sum of all lower-ranked processes' buffer elements.

Exclusive-Scan

Before: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 1 | | 3 | | 5 | | 7 | | 2 | | 4 | | 6 | | 8 | +----+ +----+ +----+ +----+

...

After: Process Process Process Process 0 1 2 3 +----+ +----+ +----+ +----+ | 0 | | 1 | | 4 | | 9 | | 0 | | 2 | | 6 | | 12 | +----+ +----+ +----+ +----+

This version of the scan operation is also known as "exclusive prefix scan" -- "exclusive" because the process's own element is excluded from the result.

Barrier

The barrier operation causes all the processes to synchronize with each other. Each process calls the communicator's barrier() method. The calling thread blocks until all processes in the communicator have called the barrier() method. Then the calling thread unblocks and returns from the barrier() method call.

Version:

21-Jan-2009

Author:

Alan Kaminsky

Method Summary

Modifier and Type	Method	Description
void	allGather(int tag, Buf src, Buf[] dstarray)	All-gather messages from each process to all processes in this communicator using the given message tag.
void	allGather(Buf src, Buf[] dstarray)	All-gather messages from each process to all processes in this communicator.
void	allReduce(int tag, Buf buffer, Op op)	Perform an all-reduce on all processes in this communicator using the given message tag.
void	allReduce(Buf buffer, Op op)	Perform an all-reduce on all processes in this communicator.
void	allToAll(int tag, Buf[] srcarray, Buf[] dstarray)	Do an all-to-all among all processes in this communicator using the given message tag.
void	allToAll(Buf[] srcarray, Buf[] dstarray)	Do an all-to-all among all processes in this communicator.
void	barrier()	Cause all processes in this communicator to wait at a barrier.
void	barrier(int tag)	Cause all processes in this communicator to wait at a barrier, using the given message tag.
void	broadcast(int root, int tag, Buf buffer)	Broadcast a message to all processes in this communicator using the given message tag.
void	broadcast(int root, Buf buffer)	Broadcast a message to all processes in this communicator.
Comm	createComm(boolean participate)	Create a new communicator.
Comm	createComm(boolean participate, int tag)	Create a new communicator.
void	dump(PrintStream out, String prefix)	Dump the state of this communicator on the given print stream.
void	exclusiveScan(int tag, Buf buf, Op op, Object item)	Perform an exclusive scan on all processes in this communicator using the given message tag.
void	exclusiveScan(Buf buf, Op op, Object item)	Perform an exclusive scan on all processes in this communicator.
CommStatus	floodReceive(Buf buffer)	Flood-receive a message from any process in this communicator.
CommRequest	floodReceive(Buf buffer, CommRequest request)	Flood-receive a message from any process in this communicator (non-blocking).
CommStatus	floodReceive(Integer tag, Buf buffer)	Flood-receive a message from any process in this communicator with the given message tag.
CommRequest	floodReceive(Integer tag, Buf buffer, CommRequest request)	Flood-receive a message from any process in this communicator with the given message tag (non-blocking).
void	floodSend(int tag, Buf buffer)	Flood-send a message to all processes in this communicator with the given message tag.
CommRequest	floodSend(int tag, Buf buffer, CommRequest request)	Flood-send a message to all processes in this communicator with the given message tag (non-blocking).
void	floodSend(Buf buffer)	Flood-send a message to all processes in this communicator.
CommRequest	floodSend(Buf buffer, CommRequest request)	Flood-send a message to all processes in this communicator (non-blocking).
void	gather(int root, int tag, Buf src, Buf[] dstarray)	Gather messages from all processes in this communicator using the given message tag.
void	gather(int root, Buf src, Buf[] dstarray)	Gather messages from all processes in this communicator.
String	host()	Obtain the host name of this communicator's backend processor.
static void	init(String[] args)	Initialize the PJ message passing middleware.
int	rank()	Obtain the current process's rank in this communicator.
CommStatus	receive(Integer fromRank, int tag, Buf buffer)	Receive a message from the process at the given rank in this communicator with the given message tag.
CommRequest	receive(Integer fromRank, int tag, Buf buffer, CommRequest request)	Receive a message from the process at the given rank in this communicator with the given message tag (non-blocking).
CommStatus	receive(Integer fromRank, Buf buffer)	Receive a message from the process at the given rank in this communicator.
CommRequest	receive(Integer fromRank, Buf buffer, CommRequest request)	Receive a message from the process at the given rank in this communicator (non-blocking).
CommStatus	receive(Integer fromRank, Range tagRange, Buf buffer)	Receive a message from the process at the given rank in this communicator with the given message tag range.
CommRequest	receive(Integer fromRank, Range tagRange, Buf buffer, CommRequest request)	Receive a message from the process at the given rank in this communicator with the given message tag range (non-blocking).
void	reduce(int root, int tag, Buf buffer, Op op)	Perform a reduction on all processes in this communicator using the given message tag.
void	reduce(int root, Buf buffer, Op op)	Perform a reduction on all processes in this communicator.
void	scan(int tag, Buf buf, Op op)	Perform a scan on all processes in this communicator using the given message tag.
void	scan(Buf buf, Op op)	Perform a scan on all processes in this communicator.
void	scatter(int root, int tag, Buf[] srcarray, Buf dst)	Scatter messages to all processes in this communicator using the given message tag.
void	scatter(int root, Buf[] srcarray, Buf dst)	Scatter messages to all processes in this communicator.
void	send(int toRank, int tag, Buf buffer)	Send a message to the process at the given rank in this communicator with the given message tag.
CommRequest	send(int toRank, int tag, Buf buffer, CommRequest request)	Send a message to the process at the given rank in this communicator with the given message tag (non-blocking).
void	send(int toRank, Buf buffer)	Send a message to the process at the given rank in this communicator.
CommRequest	send(int toRank, Buf buffer, CommRequest request)	Send a message to the process at the given rank in this communicator (non-blocking).
CommStatus	sendReceive(int toRank, int sendTag, Buf sendBuf, int fromRank, int recvTag, Buf recvBuf)	Send a message to the process at the given rank in this communicator with the given message tag, and receive a message from the process at the given rank in this communicator with the given message tag.
CommRequest	sendReceive(int toRank, int sendTag, Buf sendBuf, int fromRank, int recvTag, Buf recvBuf, CommRequest request)	Send a message to the process at the given rank in this communicator with the given message tag, and receive a message from the process at the given rank in this communicator with the given message tag (non-blocking).
CommStatus	sendReceive(int toRank, Buf sendBuf, int fromRank, Buf recvBuf)	Send a message to the process at the given rank in this communicator, and receive a message from the process at the given rank in this communicator.
CommRequest	sendReceive(int toRank, Buf sendBuf, int fromRank, Buf recvBuf, CommRequest request)	Send a message to the process at the given rank in this communicator, and receive a message from the process at the given rank in this communicator (non-blocking).
int	size()	Obtain the number of processes in this communicator.
String	toString()	Returns a string version of this communicator.
static Comm	world()	Obtain a reference to the world communicator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

init

public static void init(String[] args)
                 throws IOException

Initialize the PJ message passing middleware. Certain Java system properties specify the middleware's behavior; these properties are typically given on the Java command line with the "-D" flag. For further information, see class PJProperties.

Parameters:

args - Command line arguments.

Throws:

NullPointerException - (unchecked exception) Thrown if args is null.

IllegalArgumentException - (unchecked exception) Thrown if the value of one of the Java system properties is illegal.

IOException - Thrown if an I/O error occurred.

world

public static Comm world()

Obtain a reference to the world communicator.

Returns:

World communicator.

Throws:

IllegalStateException - (unchecked exception) Thrown if Comm.init() has not been called. Thrown if world() is called in the job frontend process; the world communicator does not exist in the job frontend process.

size

public int size()

Obtain the number of processes in this communicator.

Returns:

Size.

rank

public int rank()

Obtain the current process's rank in this communicator.

Returns:

Rank.

host

public String host()

Obtain the host name of this communicator's backend processor. If this communicator is not running on a cluster backend processor, the host name is "<unknown>".

Returns:

Host name.

createComm

public Comm createComm(boolean participate)
                throws IOException

Create a new communicator. Every process in this communicator must call the createComm() method. Each process passes true or false for the participate argument to state whether the process will participate in the new communicator. At least one process must participate in the new communicator. Messages to set up the new communicator are sent to all processes in this communicator, using a message tag of 0.

In processes participating in the new communicator, the new communicator is returned. The participating processes appear in the same order by rank in the new communicator as in this communicator. The process can call the new communicator's rank() method to determine the process's rank in the new communicator.

In processes not participating in the new communicator, null is returned.

Parameters:

participate - True if this process will participate in the new communicator; false otherwise.

Returns:

New communicator if this process will participate in the new communicator; null otherwise.

Throws:

IOException - Thrown if an I/O error occurred.

createComm

public Comm createComm(boolean participate,
 int tag)
                throws IOException

Create a new communicator. Every process in this communicator must call the createComm() method. Each process passes true or false for the participate argument to state whether the process will participate in the new communicator. At least one process must participate in the new communicator. Messages to set up the new communicator are sent to all processes in this communicator, using the given message tag.

In processes participating in the new communicator, the new communicator is returned. The participating processes appear in the same order by rank in the new communicator as in this communicator. The process can call the new communicator's rank() method to determine the process's rank in the new communicator.

In processes not participating in the new communicator, null is returned.

Parameters:

participate - True if this process will participate in the new communicator; false otherwise.

tag - Message tag.

Returns:

New communicator if this process will participate in the new communicator; null otherwise.

Throws:

IOException - Thrown if an I/O error occurred.

send

public void send(int toRank,
 Buf buffer)
          throws IOException

Send a message to the process at the given rank in this communicator. The message uses a tag of 0. The message items come from the given buffer. To receive the message, the destination process must call the receive() method. When the send() method returns, the message has been fully sent, but it may not yet have been fully received.

A process can send a message to itself; in this case a different thread must call the receive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

buffer - Buffer of data items to be sent.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

send

public void send(int toRank,
 int tag,
 Buf buffer)
          throws IOException

Send a message to the process at the given rank in this communicator with the given message tag. The message items come from the given buffer. To receive the message, the destination process must call the receive() method. When the send() method returns, the message has been fully sent, but it may not yet have been fully received.

A process can send a message to itself; in this case a different thread must call the receive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

tag - Message tag.

buffer - Buffer of data items to be sent.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

send

public CommRequest send(int toRank,
 Buf buffer,
 CommRequest request)
                 throws IOException

Send a message to the process at the given rank in this communicator (non-blocking). A message tag of 0 is used. The message items come from the given buffer. To receive the message, the destination process must call the receive() method.

The send() method initiates the send operation and immediately returns a CommRequest object. The send operation is performed by a separate thread. To wait for the send operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the message has been fully sent, but it may not yet have been fully received.

A process can send a message to itself; in this case a different thread must call the receive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

buffer - Buffer of data items to be sent.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

send

public CommRequest send(int toRank,
 int tag,
 Buf buffer,
 CommRequest request)
                 throws IOException

Send a message to the process at the given rank in this communicator with the given message tag (non-blocking). The message items come from the given buffer. To receive the message, the destination process must call the receive() method.

The send() method initiates the send operation and immediately returns a CommRequest object. The send operation is performed by a separate thread. To wait for the send operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the message has been fully sent, but it may not yet have been fully received.

A process can send a message to itself; in this case a different thread must call the receive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

tag - Message tag.

buffer - Buffer of data items to be sent.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommStatus receive(Integer fromRank,
 Buf buffer)
                   throws IOException

Receive a message from the process at the given rank in this communicator. If rank is null, a message will be received from any process in this communicator. The message must have a tag of 0. The received message items are stored in the given buffer. To send the message, the source process must call the send() method. When the receive() method returns, the message has been fully received.

A CommStatus object is returned. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the buffer, nothing is stored into the extra data items at the end of the buffer. If the actual number of data items in the message is greater than the length of the buffer, the extra data items at the end of the message are discarded.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

buffer - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommStatus receive(Integer fromRank,
 int tag,
 Buf buffer)
                   throws IOException

Receive a message from the process at the given rank in this communicator with the given message tag. If rank is null, a message will be received from any process in this communicator. The received message items are stored in the given buffer. To send the message, the source process must call the send() method. When the receive() method returns, the message has been fully received.

A CommStatus object is returned. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the buffer, nothing is stored into the extra data items at the end of the buffer. If the actual number of data items in the message is greater than the length of the buffer, the extra data items at the end of the message are discarded.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

tag - Message tag.

buffer - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommStatus receive(Integer fromRank,
 Range tagRange,
 Buf buffer)
                   throws IOException

Receive a message from the process at the given rank in this communicator with the given message tag range. If rank is null, a message will be received from any process in this communicator. If tagRange is null, a message will be received with any tag. If tagRange is not null, a message will be received with any tag in the given range. The received message items are stored in the given buffer. To send the message, the source process must call the send() method. When the receive() method returns, the message has been fully received.

A CommStatus object is returned. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the buffer, nothing is stored into the extra data items at the end of the buffer. If the actual number of data items in the message is greater than the length of the buffer, the extra data items at the end of the message are discarded.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

tagRange - Message tag range, or null to receive any tag.

buffer - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommRequest receive(Integer fromRank,
 Buf buffer,
 CommRequest request)
                    throws IOException

Receive a message from the process at the given rank in this communicator (non-blocking). If rank is null, a message will be received from any process in this communicator. The message must have a tag of 0. The received message items are stored in the given buffer. To send the message, the source process must call the send() method.

The receive() method initiates the receive operation and immediately returns a CommRequest object. The receive operation is performed by a separate thread. To wait for the receive operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the incoming message items have been fully received.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

buffer - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommRequest receive(Integer fromRank,
 int tag,
 Buf buffer,
 CommRequest request)
                    throws IOException

Receive a message from the process at the given rank in this communicator with the given message tag (non-blocking). If rank is null, a message will be received from any process in this communicator. If tag is null, a message will be received with any tag. The received message items are stored in the given buffer. To send the message, the source process must call the send() method.

The receive() method initiates the receive operation and immediately returns a CommRequest object. The receive operation is performed by a separate thread. To wait for the receive operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the incoming message items have been fully received.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

tag - Message tag.

buffer - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

receive

public CommRequest receive(Integer fromRank,
 Range tagRange,
 Buf buffer,
 CommRequest request)
                    throws IOException

Receive a message from the process at the given rank in this communicator with the given message tag range (non-blocking). If rank is null, a message will be received from any process in this communicator. If tagRange is null, a message will be received with any tag. If tagRange is not null, a message will be received with any tag in the given range. The received message items are stored in the given buffer. To send the message, the source process must call the send() method.

The receive() method initiates the receive operation and immediately returns a CommRequest object. The receive operation is performed by a separate thread. To wait for the receive operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the incoming message items have been fully received.

A process can receive a message from itself; in this case a different thread must call the send() method on this communicator.

Parameters:

fromRank - Source process's rank in this communicator, or null to receive from any process.

tagRange - Message tag range, or null to receive any tag.

buffer - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if fromRank is not null and is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

sendReceive

public CommStatus sendReceive(int toRank,
 Buf sendBuf,
 int fromRank,
 Buf recvBuf)
                       throws IOException

Send a message to the process at the given rank in this communicator, and receive a message from the process at the given rank in this communicator. A message tag of 0 is used. The outgoing message items come from the buffer sendbuf. The incoming message items go into the buffer recvbuf. The outgoing message items must come from a different place than where the incoming message items will be stored. The destination process (process toRank) must call a method to receive this process's outgoing message items. The source process (process fromRank) must call a method to send this process's incoming message items. When the sendReceive() method returns, the outgoing message items have been fully sent, but they may not yet have been fully received; and the incoming message items have been fully received.

A CommStatus object is returned giving the results of the receive half of the operation. The status object gives the rank of the process that sent the incoming message, the message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the receive buffer, nothing is stored into the extra data items at the end of the receive buffer. If the actual number of data items in the message is greater than the length of the receive buffer, the extra data items at the end of the message are discarded.

A process can send-receive messages with itself; in this case a different thread must call the sendReceive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

sendBuf - Buffer of data items to be sent.

fromRank - Source process's rank in this communicator.

recvBuf - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank or fromRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if sendBuf or recvBuf is null.

IOException - Thrown if an I/O error occurred.

sendReceive

public CommStatus sendReceive(int toRank,
 int sendTag,
 Buf sendBuf,
 int fromRank,
 int recvTag,
 Buf recvBuf)
                       throws IOException

Send a message to the process at the given rank in this communicator with the given message tag, and receive a message from the process at the given rank in this communicator with the given message tag. The outgoing message items come from the buffer sendbuf. The incoming message items go into the buffer recvbuf. The outgoing message items must come from a different place than where the incoming message items will be stored. The destination process (process toRank) must call a method to receive this process's outgoing message items. The source process (process fromRank) must call a method to send this process's incoming message items. When the sendReceive() method returns, the outgoing message items have been fully sent, but they may not yet have been fully received; and the incoming message items have been fully received.

A CommStatus object is returned giving the results of the receive half of the operation. The status object gives the rank of the process that sent the incoming message, the message tag that was received, and the actual number of data items in the message. If the actual number of data items in the message is less than the length of the receive buffer, nothing is stored into the extra data items at the end of the receive buffer. If the actual number of data items in the message is greater than the length of the receive buffer, the extra data items at the end of the message are discarded.

A process can send-receive messages with itself; in this case a different thread must call the sendReceive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

sendTag - Message tag for outgoing message.

sendBuf - Buffer of data items to be sent.

fromRank - Source process's rank in this communicator.

recvTag - Message tag for incoming message.

recvBuf - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank or fromRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if sendBuf or recvBuf is null.

IOException - Thrown if an I/O error occurred.

sendReceive

public CommRequest sendReceive(int toRank,
 Buf sendBuf,
 int fromRank,
 Buf recvBuf,
 CommRequest request)
                        throws IOException

Send a message to the process at the given rank in this communicator, and receive a message from the process at the given rank in this communicator (non-blocking). A message tag of 0 is used. The outgoing message items come from the buffer sendbuf. The incoming message items go into the buffer recvbuf. The outgoing message items must come from a different place than where the incoming message items will be stored. The destination process (process toRank) must call a method to receive this process's outgoing message items. The source process (process fromRank) must call a method to send this process's incoming message items.

The sendReceive() method initiates the send and receive operations and immediately returns a CommRequest object. The send and receive operations are performed by a separate thread. To wait for the send and receive operations to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the outgoing message items have been fully sent, but they may not yet have been fully received; and the incoming message items have been fully received.

A process can send-receive messages with itself; in this case a different thread must call the sendReceive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

sendBuf - Buffer of data items to be sent.

fromRank - Source process's rank in this communicator.

recvBuf - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank or fromRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if sendBuf or recvBuf is null.

IOException - Thrown if an I/O error occurred.

sendReceive

public CommRequest sendReceive(int toRank,
 int sendTag,
 Buf sendBuf,
 int fromRank,
 int recvTag,
 Buf recvBuf,
 CommRequest request)
                        throws IOException

Send a message to the process at the given rank in this communicator with the given message tag, and receive a message from the process at the given rank in this communicator with the given message tag (non-blocking). The outgoing message items come from the buffer sendbuf. The incoming message items go into the buffer recvbuf. The outgoing message items must come from a different place than where the incoming message items will be stored. The destination process (process toRank) must call a method to receive this process's outgoing message items. The source process (process fromRank) must call a method to send this process's incoming message items.

The sendReceive() method initiates the send and receive operations and immediately returns a CommRequest object. The send and receive operations are performed by a separate thread. To wait for the send and receive operations to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the outgoing message items have been fully sent, but they may not yet have been fully received; and the incoming message items have been fully received.

A process can send-receive messages with itself; in this case a different thread must call the sendReceive() method on this communicator.

Parameters:

toRank - Destination process's rank in this communicator.

sendTag - Message tag for outgoing message.

sendBuf - Buffer of data items to be sent.

fromRank - Source process's rank in this communicator.

recvTag - Message tag for incoming message.

recvBuf - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if toRank or fromRank is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if sendBuf or recvBuf is null.

IOException - Thrown if an I/O error occurred.

floodSend

public void floodSend(Buf buffer)
               throws IOException

Flood-send a message to all processes in this communicator. The message uses a tag of 0. The message items come from the given buffer. To receive the message, every process (including the sending process) must call the floodReceive() method. When the floodSend() method returns, the message has been fully sent, but it may not yet have been fully received in all processes.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

buffer - Buffer of data items to be sent.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodSend

public void floodSend(int tag,
 Buf buffer)
               throws IOException

Flood-send a message to all processes in this communicator with the given message tag. The message items come from the given buffer. To receive the message, every process (including the sending process) must call the floodReceive() method. When the floodSend() method returns, the message has been fully sent, but it may not yet have been fully received in all processes.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

tag - Message tag.

buffer - Buffer of data items to be sent.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodSend

public CommRequest floodSend(Buf buffer,
 CommRequest request)
                      throws IOException

Flood-send a message to all processes in this communicator (non-blocking). A message tag of 0 is used. The message items come from the given buffer. To receive the message, every process (including the sending process) must call the floodReceive() method.

The floodSend() method initiates the flood-send operation and immediately returns a CommRequest object. The flood-send operation is performed by a separate thread. To wait for the flood-send operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the message has been fully sent, but it may not yet have been fully received in all processes.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

buffer - Buffer of data items to be sent.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodSend

public CommRequest floodSend(int tag,
 Buf buffer,
 CommRequest request)
                      throws IOException

Flood-send a message to all processes in this communicator with the given message tag (non-blocking). The message items come from the given buffer. To receive the message, every process (including the sending process) must call the floodReceive() method.

The floodSend() method initiates the flood-send operation and immediately returns a CommRequest object. The flood-send operation is performed by a separate thread. To wait for the flood-send operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the message has been fully sent, but it may not yet have been fully received in all processes.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

tag - Message tag.

buffer - Buffer of data items to be sent.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodReceive

public CommStatus floodReceive(Buf buffer)
                        throws IOException

Flood-receive a message from any process in this communicator. The message must have a tag of 0. The received message items are stored in the given buffer. To send the message, the source process must call the floodSend() method. When the floodReceive() method returns, the message has been fully received.

A CommStatus object is returned. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

buffer - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodReceive

public CommStatus floodReceive(Integer tag,
 Buf buffer)
                        throws IOException

Flood-receive a message from any process in this communicator with the given message tag. If tag is null, a message will be received with any tag. The received message items are stored in the given buffer. To send the message, the source process must call the floodSend() method. When the floodReceive() method returns, the message has been fully received.

A CommStatus object is returned. The status object gives the actual rank of the process that sent the message, the actual message tag that was received, and the actual number of data items in the message.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

tag - Message tag, or null to receive any tag.

buffer - Buffer of data items to be received.

Returns:

Status object giving the outcome of the message reception.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodReceive

public CommRequest floodReceive(Buf buffer,
 CommRequest request)
                         throws IOException

Flood-receive a message from any process in this communicator (non-blocking). A message tag of 0 is used. If tag is null, a message will be received with any tag. The received message items are stored in the given buffer. To send the message, the source process must call the floodSend() method.

The floodReceive() method initiates the flood-receive operation and immediately returns a CommRequest object. The flood-receive operation is performed by a separate thread. To wait for the flood-receive operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the incoming message items have been fully received.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

buffer - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

floodReceive

public CommRequest floodReceive(Integer tag,
 Buf buffer,
 CommRequest request)
                         throws IOException

Flood-receive a message from any process in this communicator with the given message tag (non-blocking). If tag is null, a message will be received with any tag. The received message items are stored in the given buffer. To send the message, the source process must call the floodSend() method.

The floodReceive() method initiates the flood-receive operation and immediately returns a CommRequest object. The flood-receive operation is performed by a separate thread. To wait for the flood-receive operation to finish, call the returned CommRequest object's waitForFinish() method. When that method returns, the incoming message items have been fully received.

Note: The length of the incoming buffer in the floodReceive() method call must be the same as the length of the outgoing buffer in the floodSend() method call.

Parameters:

tag - Message tag, or null to receive any tag.

buffer - Buffer of data items to be received.

request - CommRequest object to use to wait for the operation to finish; in this case request is returned. If request is null, a new CommRequest object is created and returned.

Returns:

CommRequest object to use to wait for the operation to finish.

Throws:

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

broadcast

public void broadcast(int root,
 Buf buffer)
               throws IOException

Broadcast a message to all processes in this communicator. The broadcast uses a message tag of 0. All processes must call broadcast() with the same value for root and with a buffer of the same length and the same item data type.

The root process (the process whose rank in this communicator is root) sends the message items. The message items come from the given buffer. When the broadcast() method returns, the message has been fully sent, but it may not yet have been fully received by all processes.

Each non-root process receives the message items. The message items are stored in the given buffer. When the broadcast() method returns, the message has been fully received.

Parameters:

root - Root process's rank in this communicator.

buffer - Buffer of data items to be sent (root process) or received (non-root processes).

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

broadcast

public void broadcast(int root,
 int tag,
 Buf buffer)
               throws IOException

Broadcast a message to all processes in this communicator using the given message tag. All processes must call broadcast() with the same values for root and tag and with a buffer of the same length and the same item data type.

The root process (the process whose rank in this communicator is root) sends the message items. The message items come from the given buffer. When the broadcast() method returns, the message has been fully sent, but it may not yet have been fully received by all processes.

Each non-root process receives the message items. The message items are stored in the given buffer. When the broadcast() method returns, the message has been fully received.

Parameters:

root - Root process's rank in this communicator.

tag - Message tag.

buffer - Buffer of data items to be sent (root process) or received (non-root processes).

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buffer is null.

IOException - Thrown if an I/O error occurred.

scatter

public void scatter(int root,
 Buf[] srcarray,
 Buf dst)
             throws IOException

Scatter messages to all processes in this communicator. The scatter uses a message tag of 0. All processes must call scatter() with the same value for root.

The root process (the process whose rank in this communicator is root) sends the message items. The message items sent to process i come from the source buffer at index i in the given array of source buffers. When the scatter() method returns, the messages have been fully sent, but they may not yet have been fully received by all processes.

Each process, including the root process, receives the message items. The message items are stored in the given destination buffer. This must have the same length and the same item data type as the corresponding source buffer. When the scatter() method returns, the message has been fully received.

In the non-root processes, the source buffer array is ignored and may be null.

Parameters:

root - Root process's rank in this communicator.

srcarray - Array of source buffers to be sent by the root process. Ignored in the non-root processes.

dst - Destination buffer to be received.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1. Thrown if srcarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if srcarray or any element thereof is null. Thrown if dst is null.

IOException - Thrown if an I/O error occurred.

scatter

public void scatter(int root,
 int tag,
 Buf[] srcarray,
 Buf dst)
             throws IOException

Scatter messages to all processes in this communicator using the given message tag. All processes must call scatter() with the same values for root and tag.

The root process (the process whose rank in this communicator is root) sends the message items. The message items sent to process i come from the source buffer at index i in the given array of source buffers. When the scatter() method returns, the messages have been fully sent, but they may not yet have been fully received by all processes.

Each process, including the root process, receives the message items. The message items are stored in the given destination buffer. This must have the same length and the same item data type as the corresponding source buffer. When the scatter() method returns, the message has been fully received.

In the non-root processes, the source buffer array is ignored and may be null.

Parameters:

root - Root process's rank in this communicator.

tag - Message tag.

srcarray - Array of source buffers to be sent by the root process. Ignored in the non-root processes.

dst - Destination buffer to be received.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1. Thrown if srcarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if srcarray or any element thereof is null. Thrown if dst is null.

IOException - Thrown if an I/O error occurred.

gather

public void gather(int root,
 Buf src,
 Buf[] dstarray)
            throws IOException

Gather messages from all processes in this communicator. The gather uses a message tag of 0. All processes must call gather() with the same value for root.

The root process (the process whose rank in this communicator is root) receives the message items. The message items received from process i are stored in the destination buffer at index i in the given array of destination buffers. When the gather() method returns, all the messages have been fully received.

Each process, including the root process, sends the message items. The message items come from the given source buffer. This must have the same length and the same item data type as the corresponding destination buffer. When the gather() method returns, the message has been fully sent, but it may not yet have been fully received by the root process.

In the non-root processes, the destination buffer array is ignored and may be null.

Parameters:

root - Root process's rank in this communicator.

src - Source buffer to be sent.

dstarray - Array of destination buffers to be received by the root process. Ignored in the non-root processes.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1. Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if dstarray or any element thereof is null. Thrown if src is null.

IOException - Thrown if an I/O error occurred.

gather

public void gather(int root,
 int tag,
 Buf src,
 Buf[] dstarray)
            throws IOException

Gather messages from all processes in this communicator using the given message tag. All processes must call gather() with the same values for root and tag.

The root process (the process whose rank in this communicator is root) receives the message items. The message items received from process i are stored in the destination buffer at index i in the given array of destination buffers. When the gather() method returns, all the messages have been fully received.

Each process, including the root process, sends the message items. The message items come from the given source buffer. This must have the same length and the same item data type as the corresponding destination buffer. When the gather() method returns, the message has been fully sent, but it may not yet have been fully received by the root process.

In the non-root processes, the destination buffer array is ignored and may be null.

Parameters:

root - Root process's rank in this communicator.

tag - Message tag.

src - Source buffer to be sent.

dstarray - Array of destination buffers to be received by the root process. Ignored in the non-root processes.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1. Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if dstarray or any element thereof is null. Thrown if src is null.

IOException - Thrown if an I/O error occurred.

allGather

public void allGather(Buf src,
 Buf[] dstarray)
               throws IOException

All-gather messages from each process to all processes in this communicator. A message tag of 0 is used. All processes must call allGather().

Each process sends the message items in the given source buffer. When the allGather() method returns, the source buffer has been fully sent.

Each process receives message items from the other processes. The message items received from process i are stored in the destination buffer at index i in the given array of destination buffers. This destination buffer must have the same length and the same item data type as the source buffer in process i. When the allGather() method returns, all the destination buffers have been fully received.

All-gather is the same as gather, except that every process has an array of destination buffers, and every process receives the results of the gather.

Parameters:

src - Source buffer to be sent.

dstarray - Array of destination buffers to be received.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if dstarray or any element thereof is null. Thrown if src is null.

IOException - Thrown if an I/O error occurred.

allGather

public void allGather(int tag,
 Buf src,
 Buf[] dstarray)
               throws IOException

All-gather messages from each process to all processes in this communicator using the given message tag. All processes must call allGather() with the same value for tag.

Each process sends the message items in the given source buffer. When the allGather() method returns, the source buffer has been fully sent.

Each process receives message items from the other processes. The message items received from process i are stored in the destination buffer at index i in the given array of destination buffers. This destination buffer must have the same length and the same item data type as the source buffer in process i. When the allGather() method returns, all the destination buffers have been fully received.

All-gather is the same as gather, except that every process has an array of destination buffers, and every process receives the results of the gather.

Parameters:

tag - Message tag.

src - Source buffer to be sent.

dstarray - Array of destination buffers to be received.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if dstarray or any element thereof is null. Thrown if src is null.

IOException - Thrown if an I/O error occurred.

reduce

public void reduce(int root,
 Buf buffer,
 Op op)
            throws IOException

Perform a reduction on all processes in this communicator. The reduction uses a message tag of 0. All processes must call reduce() with the same value for root, with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling reduce(), each process has a buffer filled with data items. After reduce() returns, each data item in the root process's buffer has been set to the reduction of the corresponding data items in all the processes' buffers. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process rank 0, 1, 2, and so on. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

In the root process, the reduce operation always changes the buffer's contents as described above. In the non-root processes, the reduce operation may or may not change the buffer's contents; the final contents of the buffer in the non-root processes is not specified.

When the reduce() method returns in the root process, the reduction has been fully performed as described above. When the reduce() method returns in a non-root process, the non-root process has sent all its data items into the reduction, but the reduction may not be fully complete in the root process yet.

Parameters:

root - Root process's rank in this communicator.

buffer - Buffer of data items to be reduced.

op - Binary operation.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

reduce

public void reduce(int root,
 int tag,
 Buf buffer,
 Op op)
            throws IOException

Perform a reduction on all processes in this communicator using the given message tag. All processes must call reduce() with the same value for root, with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling reduce(), each process has a buffer filled with data items. After reduce() returns, each data item in the root process's buffer has been set to the reduction of the corresponding data items in all the processes' buffers. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process rank 0, 1, 2, and so on. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

In the root process, the reduce operation always changes the buffer's contents as described above. In the non-root processes, the reduce operation may or may not change the buffer's contents; the final contents of the buffer in the non-root processes is not specified.

When the reduce() method returns in the root process, the reduction has been fully performed as described above. When the reduce() method returns in a non-root process, the non-root process has sent all its data items into the reduction, but the reduction may not be fully complete in the root process yet.

Parameters:

root - Root process's rank in this communicator.

tag - Message tag.

buffer - Buffer of data items to be reduced.

op - Binary operation.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if root is not in the range 0 .. size()-1.

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

allReduce

public void allReduce(Buf buffer,
 Op op)
               throws IOException

Perform an all-reduce on all processes in this communicator. The all-reduce uses a message tag of 0. All processes must call allReduce() with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling allReduce(), each process has a buffer filled with data items. After allReduce() returns, each data item in the calling process's buffer has been set to the reduction of the corresponding data items in all the processes' buffers. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process rank 0, 1, 2, and so on. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

The allReduce() method is similar to the reduce() method, except the results are stored in all the processes' buffers, not just the one root process's buffer.

Parameters:

buffer - Buffer of data items to be reduced.

op - Binary operation.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

allReduce

public void allReduce(int tag,
 Buf buffer,
 Op op)
               throws IOException

Perform an all-reduce on all processes in this communicator using the given message tag. All processes must call allReduce() with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling allReduce(), each process has a buffer filled with data items. After allReduce() returns, each data item in the calling process's buffer has been set to the reduction of the corresponding data items in all the processes' buffers. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process rank 0, 1, 2, and so on. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

The allReduce() method is similar to the reduce() method, except the results are stored in all the processes' buffers, not just the one root process's buffer.

Parameters:

tag - Message tag.

buffer - Buffer of data items to be reduced.

op - Binary operation.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

allToAll

public void allToAll(Buf[] srcarray,
 Buf[] dstarray)
              throws IOException

Do an all-to-all among all processes in this communicator. A message tag of 0 is used.

srcarray must be an array of K buffers, where K is the size of this communicator. dstarray must be an array of K buffers referring to different storage from the source buffers. For each process rank k, 0 <= k <= K, and each buffer index i, 0 <= i <= K, the contents of srcarray[k] in process i are sent to dstarray[i] in process k.

Parameters:

srcarray - Array of source buffers to be sent by this process.

dstarray - Array of destination buffers to be received by this process.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if srcarray's length does not equal the size of this communicator. Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if srcarray or any element thereof is null. Thrown if dstarray or any element thereof is null.

IOException - Thrown if an I/O error occurred.

allToAll

public void allToAll(int tag,
 Buf[] srcarray,
 Buf[] dstarray)
              throws IOException

Do an all-to-all among all processes in this communicator using the given message tag. All processes must call allToAll() with the same value for tag.

srcarray must be an array of K buffers, where K is the size of this communicator. dstarray must be an array of K buffers referring to different storage from the source buffers. For each process rank k, 0 <= k <= K, and each buffer index i, 0 <= i <= K, the contents of srcarray[k] in process i are sent to dstarray[i] in process k.

Parameters:

tag - Message tag.

srcarray - Array of source buffers to be sent by this process.

dstarray - Array of destination buffers to be received by this process.

Throws:

IndexOutOfBoundsException - (unchecked exception) Thrown if srcarray's length does not equal the size of this communicator. Thrown if dstarray's length does not equal the size of this communicator.

NullPointerException - (unchecked exception) Thrown if srcarray or any element thereof is null. Thrown if dstarray or any element thereof is null.

IOException - Thrown if an I/O error occurred.

scan

public void scan(Buf buf,
 Op op)
          throws IOException

Perform a scan on all processes in this communicator. A message tag of 0 is used. All processes must call scan() with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling scan(), each process has a buffer filled with data items. After scan() returns, each data item in the buffer of process rank i has been set to the reduction of the corresponding data items in the buffers of process ranks 0 through i. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process ranks 0 through i. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

Parameters:

buf - Buffer of data items to be scanned.

op - Binary operation.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

scan

public void scan(int tag,
 Buf buf,
 Op op)
          throws IOException

Perform a scan on all processes in this communicator using the given message tag. All processes must call scan() with the same value for tag, with a buffer of the same length and the same item data type, and with the same binary operation (class Op).

Before calling scan(), each process has a buffer filled with data items. After scan() returns, each data item in the buffer of process rank i has been set to the reduction of the corresponding data items in the buffers of process ranks 0 through i. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process ranks 0 through i. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

Parameters:

tag - Message tag.

buf - Buffer of data items to be scanned.

op - Binary operation.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

exclusiveScan

public void exclusiveScan(Buf buf,
 Op op,
 Object item)
                   throws IOException

Perform an exclusive scan on all processes in this communicator. A message tag of 0 is used. All processes must call exclusiveScan() with a buffer of the same length and the same item data type, with the same binary operation (class Op), and with the same initial data value.

Before calling exclusiveScan(), each process has a buffer filled with data items. After exclusiveScan() returns, each data item in the buffer of process rank i > 0 has been set to the reduction of the corresponding data items in the buffers of process ranks 0 through i-1. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process ranks 0 through i-1. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

In process 0, each data item in the buffer has been set to the initial data value using the buffer's fill() method.

If the buffer's item data type is a primitive type, the item must be an instance of the corresponding primitive wrapper class -- class Integer for type int, class Double for type double, and so on. If the item is null, the item data type's default initial value is assigned to each element in the buffer.

If the buffer's item data type is a nonprimitive type, the item must be an instance of the item class or a subclass thereof. The item may be null. Note that since item is assigned to every buffer element, every buffer element ends up referring to the same item.

Parameters:

buf - Buffer of data items to be scanned.

op - Binary operation.

item - Initial data value.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

exclusiveScan

public void exclusiveScan(int tag,
 Buf buf,
 Op op,
 Object item)
                   throws IOException

Perform an exclusive scan on all processes in this communicator using the given message tag. All processes must call exclusiveScan() with the same value for tag, with a buffer of the same length and the same item data type, with the same binary operation (class Op), and with the same initial data value.

Before calling exclusiveScan(), each process has a buffer filled with data items. After exclusiveScan() returns, each data item in the buffer of process rank i > 0 has been set to the reduction of the corresponding data items in the buffers of process ranks 0 through i-1. The reduction is calculated by this formula:

item₀ op item₁ op item₂ op . . .

where op is the binary operation passed in as an argument and item₀, item₁, item₂, and so on are the data items in the buffers of process ranks 0 through i-1. However, the order in which the data items actually are combined is not specified. Therefore, the binary operation must be such that the answer will be the same regardless of the order in which the data items are combined; that is, the binary operation must be commutative and associative.

In process 0, each data item in the buffer has been set to the initial data value using the buffer's fill() method.

If the buffer's item data type is a primitive type, the item must be an instance of the corresponding primitive wrapper class -- class Integer for type int, class Double for type double, and so on. If the item is null, the item data type's default initial value is assigned to each element in the buffer.

If the buffer's item data type is a nonprimitive type, the item must be an instance of the item class or a subclass thereof. The item may be null. Note that since item is assigned to every buffer element, every buffer element ends up referring to the same item.

Parameters:

tag - Message tag.

buf - Buffer of data items to be scanned.

op - Binary operation.

item - Initial data value.

Throws:

NullPointerException - (unchecked exception) Thrown if buf is null or op is null.

ClassCastException - (unchecked exception) Thrown if buf and op do not use the same item data type.

IOException - Thrown if an I/O error occurred.

barrier

public void barrier()
             throws IOException

Cause all processes in this communicator to wait at a barrier. The barrier uses a message tag of 0. All processes must call barrier(). The calling thread blocks until every process has called barrier(), then the calling thread unblocks and returns from the barrier() call.

Throws:

IOException - Thrown if an I/O error occurred.

barrier

public void barrier(int tag)
             throws IOException

Cause all processes in this communicator to wait at a barrier, using the given message tag. All processes must call barrier() with the same tag. The calling thread blocks until every process has called barrier(), then the calling thread unblocks and returns from the barrier() call.

Parameters:

tag - Message tag.

Throws:

IOException - Thrown if an I/O error occurred.

toString

public String toString()

Returns a string version of this communicator. The string includes the communicator's size, the current process's rank, and the host and port of each backend process.

Overrides:

toString in class Object

Returns:

String version.

dump

public void dump(PrintStream out,
 String prefix)

Dump the state of this communicator on the given print stream. For debugging.

Parameters:

out - Print stream.

prefix - String to print at the beginning of each line.