Ubuntu Manpage: pvm_gather - A specified member of the group receives messages from each member of the group and gathers

name
synopsis
parameters
description
examples
errors
see also

Provided by: pvm-dev_3.4.6-1build2_amd64

NAME

       pvm_gather  - A specified member of the group receives messages from each member of the group and gathers
       these messages into a single array.

SYNOPSIS

       C    int info = pvm_gather( void *result,  void *data,
                         int count, int datatype, int msgtag,
                         char *group, int rootginst)

       Fortran    call pvmfgather(result, data, count, datatype,
                                  msgtag, group, rootginst, info)

PARAMETERS

       result  On the root this is a pointer to the starting address of an array datatype of local values  which
               are to be accumulated from the members of the group.  If n if the number of members in the group,
               then this array of datatype should be of length at least n*count.  This  argument  is  meaningful
               only on the root.

       data    For  each  group  member this is a pointer to the starting address of an array of length count of
               datatype which will be sent to the specified root member of the group.

       count   Integer specifying the number of elements of datatype to be sent by each member of the  group  to
               the root.

       datatype
               Integer specifying the type of the entries in the result and data arrays.  (See below for defined
               types.)

       msgtag  Integer message tag supplied by the user.  msgtag should be >= 0.  It allows the  user's  program
               to distinguish between different kinds of messages.

       group   Character string group name of an existing group.

       rootginst
               Integer  instance number of group member who performs the gather of the messages from the members
               of the group.

       info    Integer status code returned by the routine.  Values less than zero indicate an error.

DESCRIPTION

pvm_gather() performs a send of messages from each member of the group to the specified root member of
the group. All group members must call pvm_gather(), each sends its array data of length count of
datatype to the root which accumulates these messages into its result array. It is as if the root
receives count elements of datatype from the ith member of the group and places these values in its
result array starting with offset i*count from the beginning of the result array. The root task is
identified by its instance number in the group.

C and Fortran defined datatypes are:
C datatypes FORTRAN datatypes
-----------------------------------
PVM_BYTE BYTE1
PVM_SHORT INTEGER2
PVM_INT INTEGER4
PVM_FLOAT REAL4
PVM_CPLX COMPLEX8
PVM_DOUBLE REAL8
PVM_DCPLX COMPLEX16
PVM_LONG

In using the scatter and gather routines, keep in mind that C stores multidimensional arrays in row
order, typically starting with an initial index of 0; whereas, Fortran stores arrays in column order,
typically starting with an offset of 1.

Note: pvm_gather() does not block. If a task calls pvm_gather and then leaves the group before the root
has called pvm_gather an error may occur.

The current algorithm is very simple and robust. A future implementation may make more efficient use of
the architecture to allow greater parallelism.

EXAMPLES

       C:
          info =  pvm_gather(&getmatrix, &myrow, 10, PVM_INT,
                             msgtag, "workers", rootginst);

       Fortran:
          CALL PVMFGATHER(GETMATRIX, MYCOLUMN, COUNT, INTEGER4,
         &                MTAG, 'workers', ROOT, INFO)

ERRORS

       These error conditions can be returned by pvm_gather

       PvmNoInst
              Calling task is not in the group

       PvmBadParam
              The datatype specified is not appropriate

       PvmSysErr
              Pvm system error