Nonblocking communication

Nonblocking communications use methods of the Request class to identify communication operations and match the operation that initiates the communication with the operation that terminates it.

Request Comm.isend(Object buf, int offset, int count,
                   Datatype datatype, int dest, int tag)

buf	send buffer array
offset	initial offset in send buffer
count	number of items to send
datatype	datatype of each item in send buffer
dest	rank of destination
tag	message tag
returns:	communication request

Start a standard mode, nonblocking send. Java binding of the MPI operation MPI_ISEND. Further comments as for send.

Request Comm.ibsend(Object buf, int offset, int count,
                    Datatype datatype, int dest, int tag)

buf	send buffer array
offset	initial offset in send buffer
count	number of items to send
datatype	datatype of each item in send buffer
dest	rank of destination
tag	message tag
returns:	communication request

Start a buffered mode, nonblocking send. Java binding of the MPI operation MPI_IBSEND. Further comments as for send.

Request Comm.issend(Object buf, int offset, int count,
                    Datatype datatype, int dest, int tag)

buf	send buffer array
offset	initial offset in send buffer
count	number of items to send
datatype	datatype of each item in send buffer
dest	rank of destination
tag	message tag
returns:	communication request

Start a synchronous mode, nonblocking send. Java binding of the MPI operation MPI_ISSEND. Further comments as for send.

Request Comm.irsend(Object buf, int offset, int count,
                    Datatype datatype, int dest, int tag)

buf	send buffer array
offset	initial offset in send buffer
count	number of items to send
datatype	datatype of each item in send buffer
dest	rank of destination
tag	message tag
returns:	communication request

Start a ready mode, nonblocking send. Java binding of the MPI operation MPI_IRSEND. Further comments as for send.

Request Comm.irecv(Object buf, int offset, int count,
                   Datatype datatype, int source, int tag)

buf	receive buffer array
offset	initial offset in receive buffer
count	number of items in receive buffer
datatype	datatype of each item in receive buffer
source	rank of source
tag	message tag
returns:	communication request

Start a nonblocking receive. Java binding of the MPI operation MPI_IRECV. Further comments as for recv.

The following functions are used to complete nonblocking communication operations (and also communications started using the persistent communication requests--subclass Prequest--introduced later). We use the following terminology. A request is ``active'' if it is associated with an ongoing communication. Otherwise it is inactive. An inactive instance of the base class Request is called a ``void request''. Note, however, that an inactive instance of the Prequest subclass is not said to be ``void'', because it retains detailed information about a communication pattern even when no corresponding communication is ongoing.

• Rationale. A ``void request'' corresponds to what is called a ``null handle'' in the C and Fortran MPI bindings. It seems impractical to have completion operations like wait set request object references to null references in the Java sense (because Java methods cannot directly modify references passed to them as arguments). To avoid a confusing semantic distinction between null MPI handles and null Java references we introduce the terminology of a ``void request object''. The Request default constructor can be used to explicitly create a void request, replacing assignment of the value MPI_REQUEST_NULL. The inquiry Request.isVoid can be used to determine if a particular request is void, replacing a test for equality to MPI_REQUEST_NULL.(End of rationale.)

Status Request.wait()

returns:

status object

Blocks until the operation identified by the request is complete. Java binding of the MPI operation MPI_WAIT. After the call returns, the request object becomes inactive.

Status Request.test()

returns:

status object or null reference

Returns a status object if the operation identified by the request is complete, or a null reference otherwise. Java binding of the MPI operation MPI_TEST. After the call, if the operation is complete (ie, if the return value of test is non-null), the request object becomes an inactive request.

Request.Request()

Default constructor for Request. Constructs a void request.

boolean Request.isVoid()

returns:

true if the request object is void, false otherwise

Note that isVoid is always false on instances of the subclass Prequest.

void Request.finalize()

• Advice to implementors. In a JNI-based wrapper implementation, the finalize method for Request should call MPI_Request_free only if isVoid() is false. If the request is void, for example because a wait operation on the object recently succeeded, the MPI_Request_free call is redundant.(End of advice to implementors.)

static Status Request.waitAny(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	status object

Blocks until one of the operations associated with the active requests in the array has completed. Java binding of the MPI operation MPI_WAITANY. The index in arrayOfRequests for the request that completed can be obtained from the status object through the Status.getIndex inquiry. The corresponding element of arrayOfRequests becomes inactive.

The arrayOfRequests may contain inactive requests. If the list containts no active requests, the method immediately returns a status for which the getIndex inquiry will return MPI.UNDEFINED.

static Status Request.testAny(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	status object or null reference

Tests for completion of either one or none of the operations associated with active requests. Java binding of the MPI operation MPI_TESTANY. If some request completed, the index in arrayOfRequests of that request can be obtained from the status object through the Status.getIndex() inquiry. The corresponding element of arrayOfRequests becomes inactive. If no request completed, testAny returns a null reference.

The arrayOfRequests may contain inactive requests. If the list containts no active requests, the method immediately returns a status for which the getIndex inquiry will return MPI.UNDEFINED.

int Status.getIndex()

returns:

index of the the operation that completed.

This method can be applied to any status object returned by Request.waitAny, Request.testAny, Request.waitSome, or Request.testSome.

static Status [] Request.waitAll(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	array of status objects

Blocks until all of the operations associated with the active requests in the array have completed. Java binding of the MPI operation MPI_WAITALL. The result array will be the same size as arrayOfRequests. On exit, requests become inactive. If the input value of arrayOfRequests contains any inactive requests, corresponding elements of the result array will contain null status references.

static Status [] Request.testAll(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	array of status objects, or a null reference

Tests for completion of all of the operations associated with active requests. Java binding of the MPI operation MPI_TESTALL. If all operations have completed, the exit values of the argument array and the result array are as for waitAll. If any operation has not completed, the result value is null and no element of the argument array is modified.

static Status [] Request.waitSome(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	array of status objects

Blocks until at least one of the operations associated with the active requests in the array has completed. Java binding of the MPI operation MPI_WAITSOME. The size of the result array will be the number of operations that completed. The index in arrayOfRequests for each request that completed can be obtained from the returned status objects using the Status.getIndex inquiry. The corresponding element in arrayOfRequests becomes inactive.

If arrayOfRequests list contains no active requests, testAll immediately returns a null reference.

static Status [] Request.testSome(Request [] arrayOfRequests)

arrayOfRequests	array of requests
returns:	array of status objects

Behaves like waitSome, except that it returns immediately. Java binding of the MPI operation MPI_TESTSOME. If no operation has completed, testSome returns an array of length zero and elements of arrayOfRequests are unchanged. Otherwise, arguments and return value are as for waitSome.