MPI Subroutine Reference

MPE_IGATHERV, MPE_Igatherv

Purpose

Performs a nonblocking gatherv operation.

C synopsis

#include <mpi.h>
int MPE_Igatherv(void* sendbuf,int sendcount,MPI_Datatype sendtype,
    void* recvbuf,int recvcounts,int *displs,MPI_Datatype recvtype,
    int root,MPI_Comm comm,MPI_Request *request);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPE_IGATHERV(CHOICE SENDBUF,INTEGER SENDCOUNT,INTEGER SENDTYPE,
    CHOICE RECVBUF,INTEGER RECVCOUNTS(*),INTEGER DISPLS(*),
    INTEGER RECVTYPE,INTEGER ROOT,INTEGER COMM,INTEGER REQUEST,
    INTEGER IERROR)

Parameters

sendbuf

is the starting address of the send buffer (choice) (IN)

sendcount

is the number of elements to be sent (integer) (IN)

sendtype

is the datatype of the send buffer elements (handle) (IN)

recvbuf

is the address of the receive buffer (choice, significant only at root) (OUT)

recvcounts

integer array (of length group size) that contains the number of elements received from each task (significant only at root) (IN)

displs

integer array (of length group size). Entry i specifies the displacement relative to recvbuf at which to place the incoming data from task i (significant only at root) (IN)

recvtype

is the datatype of the receive buffer elements (handle, significant only at root) (IN)

root

is the rank of the receiving task (integer) (IN)

comm

is the communicator (handle) (IN)

request

is the communication request (handle) (OUT)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

This subroutine is a nonblocking version of MPI_GATHERV. It performs the same function as MPI_GATHERV except that it returns a request handle that must be explicitly completed by using one of the MPI wait or test operations.

Notes

The MPE prefix used with this subroutine indicates that it is an IBM extension to the MPI standard and is not part of the standard itself. MPE routines are provided to enhance the function and the performance of user applications, but applications that use them will not be directly portable to other MPI implementations.

Nonblocking collective communication routines allow for increased efficiency and flexibility in some applications. Because these routines do not synchronize the participating tasks like blocking collective routines generally do, tasks running at different speeds do not waste time waiting for each other.

When it is expected that tasks will be reasonably synchronized, the blocking collective communication routines provided by standard MPI will commonly give better performance than the nonblocking versions.

The nonblocking collective routines can be used in conjunction with the MPI blocking collective routines and can be completed by any of the MPI wait or test functions. Use of MPI_CANCEL and MPI_REQUEST_FREE is not supported.

The threads library has a limit of seven outstanding nonblocking collective calls. A nonblocking call is considered outstanding between the time the call is made and the time the wait is completed. This restriction does not apply to the signal library or to any call defined by the MPI standard.

Applications using nonblocking collective calls often perform best when they run in interrupt mode.

When you use this subroutine in a threads application, make sure all collective operations on a particular communicator are started in the same order at each task. See IBM Parallel Environment for AIX: MPI Programming Guide for more information on programming with MPI in a threads environment.

Errors

Invalid communicator

Invalid communicator type

must be intracommunicator

Invalid count(s)

Invalid datatype(s)

Type not committed

Invalid root

root < 0 or root >= groupsize

A send and receive have unequal message lengths

MPI_IN_PLACE not valid

MPI not initialized

MPI already finalized

Develop mode error if:

Inconsistent root

Related information

MPI_GATHERV