4.8.2. Matching Probe

The function MPI_PROBE checks for incoming messages without receiving them. Since the list of incoming messages is global among the threads of each MPI process, it can be hard to use this functionality in threaded environments [34,31].

Like MPI_PROBE and MPI_IPROBE, the matching probe operation ( MPI_MPROBE and MPI_IMPROBE procedures) allow incoming messages to be queried without actually receiving them, except that MPI_MPROBE and MPI_IMPROBE provide a mechanism to receive the specific message that was matched regardless of other intervening probe or receive operations. This gives the application an opportunity to decide how to receive the message, based on the information returned by the probe. In particular, the user may allocate memory for the receive buffer, according to the length of the probed message.

MPI_IMPROBE returns flag = true if there is a message that can be received and that matches the pattern specified by the arguments source, tag, and comm. The call matches the same message that would have been received by a call to MPI_RECV with the same argument values for source, tag, comm, and status executed at the same point in the program and returns in status the same value that would have been returned by MPI_RECV. In addition, it returns in message a message handle to the matched message. Otherwise, the call returns flag = false, and leaves status and message undefined.

MPI_IMPROBE is a local procedure. According to the definitions in Section MPI Procedures and in contrast to MPI_IPROBE, it is a nonblocking procedure because it is the initialization of a matched receive operation.

A matched receive ( MPI_MRECV or MPI_IMRECV) executed with the message handle will receive the message that was matched by the matching probe. Unlike MPI_IPROBE, no other probe or receive operation may match the message returned by MPI_IMPROBE. Each message handle returned by MPI_IMPROBE must be received with either MPI_MRECV or MPI_IMRECV.

The source argument of MPI_IMPROBE can be MPI_ANY_SOURCE, and the tag argument can be MPI_ANY_TAG, so that one can probe for messages from an arbitrary source and/or with an arbitrary tag. However, a specific communication context must be provided with the comm argument.

A synchronous mode send operation that is matched with MPI_IMPROBE or MPI_MPROBE will complete successfully only if both a matching receive is started with MPI_MRECV or MPI_IMRECV, and the matching receive operation has started to receive the message sent by the synchronous mode send.

There is a special predefined message handle: MPI_MESSAGE_NO_PROC, which is a message that has MPI_PROC_NULL as its source. The predefined constant MPI_MESSAGE_NULL is the value used for invalid message handles.

A matching probe with source = MPI_PROC_NULL returns flag = true, message = MPI_MESSAGE_NO_PROC, and the status object returns source = MPI_PROC_NULL, tag = MPI_ANY_TAG, and count = 0; see Section Null MPI Processes. It is not necessary to call MPI_MRECV or MPI_IMRECV with MPI_MESSAGE_NO_PROC, but it is not erroneous to do so.

Rationale.

MPI_MESSAGE_NO_PROC was chosen instead of MPI_MESSAGE_PROC_NULLto avoid possible confusion as another null handle constant. ( End of rationale.)

MPI_MPROBE behaves like MPI_IMPROBE except that it is a blocking call that returns only after a matching message has been found.

The implementation of MPI_MPROBE and MPI_IMPROBE needs to guarantee progress in the same way as in the case of MPI_PROBE and MPI_IPROBE. See also Section Progress on progress.

According to the definitions in Section MPI Procedures, MPI_MPROBE is incomplete. It is also a nonlocal procedure.
Advice to users.

This is one of the exceptions in which incomplete procedures are nonlocal. ( End of advice to users.)