Provided by: pvm-dev_3.4.5-12.5ubuntu1_amd64 bug

NAME

       pvm_reduce - Performs a reduction operation over members of the specified group.

SYNOPSIS

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

       Fortran    call pvmfreduce(func, data, count, datatype,
                                  msgtag, group, rootginst, info)

PARAMETERS

       func    Function  which defines the operation performed on the global data. Predefined are
               PvmMax, PvmMin, PvmSum, and PvmProduct.  Users can define their own function.

                 SYNOPSIS for func
                 C   void func(int *datatype, void *x, void *y,
                               int *num, int *info)
                 Fortran    call func(datatype, x, y, num, info)

       data    Pointer to the starting address of an array of local values.
               On return, the data array on the root will be overwritten
               with the result of the reduce operation over the group.
               For the other (non-root) members of the group the values
               of the data array upon return from the reduce operation
               are not defined; the values may be different than
               those originally passed to pvm_reduce.

       count   Integer specifying the number of elements of
               datatype
               in the data array.
               The value of count should agree between all members of the group.

       datatype
               Integer specifying the type of the entries in the data array.
               (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 gets the result.

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

DESCRIPTION

       pvm_reduce() performs global operations  such  as  max,  min,  sum,  or  a  user  provided
       operation  on  the  data  provided  by  the  members  of  a group.  All group members call
       pvm_reduce with the same size local data array which may contain one or more entries.  The
       root task is identified by its instance number in the group.

       The  inner workings of the pvm_reduce call are implementation dependent; however, when the
       pvm_reduce call completes, the root's data array will be equal to the specified  operation
       applied element-wise to the data arrays of all the group members.

       A  broadcast  by the root can be used if the other members of the group need the resultant
       value(s).

       PVM supplies the following predefined functions that can be specified in func.
                PvmMin
                PvmMax
                PvmSum
                PvmProduct

       PvmMax and PvmMin are implemented for all the datatypes listed below.  For complex  values
       the minimum [maximum] is that complex pair with the minimum [maximum] modulus.  PvmSum and
       PvmProduct are implemented for all the  datatypes  listed  below  with  the  exception  of
       PVM_BYTE and BYTE1.

       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

       A  user  defined  function may be used in func.  The argument func is a function with four
       arguments.  It is the base function used for the reduction operation.  Both x  and  y  are
       arrays  of  type  specified by datatype with num entries.  The arguments datatype and info
       are as specified above.  The arguments x and num correspond to data and count above.   The
       argument y contains received values.

       Caveat: pvm_reduce() does not block, a call to pvm_barrier may be necessary.  For example,
       an error may occur if a task calls pvm_reduce and then leaves the group  before  the  root
       has  completed  its call to pvm_reduce.  Similarly, an error may occur if a task joins the
       group after the root has issued its call to  pvm_reduce.   Synchronization  of  the  tasks
       (such  as  a  call  to  pvm_barrier) was not included within the pvm_reduce implementation
       since this overhead is unnecessary in many user codes (which may already  synchronize  the
       tasks for other purposes).

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

ILLUSTRATION

       The following example illustrates a call to pvm_reduce.   Suppose  you  have  three  group
       members (instance numbers 0, 1, 2) with an array called Idata with 5 values as specified:

            instance       the 5 values in the integer array
               0                1,   2,   3,   4,   5
               1               10,  20,  30,  40,  50
               2              100, 200, 300, 400, 500

       And,  suppose that a call to reduce (such as the ones following) are issued where the root
       is the group member with instance value of 1:

          C:
             root = 1;
             info = pvm_reduce(PvmSum, &Idata, 5, PVM_INT, msgtag,
                               "worker", root);
          Fortran:
             root = 1
             call pvmfreduce(PvmSum, Idata, 5, INTEGER4, msgtag,
                             "worker", root, info)

       Then, upon completion of the reduce call, the following will result:

            instance       the 5 values in the integer array
               0              .... not defined.......
               1              111, 222, 333, 444, 555
               2              .... not defined ......

EXAMPLES

       C:
          info =  pvm_reduce(PvmMax, &myvals, 10, PVM_FLOAT,
                             msgtag, "worker", rootginst);

       Fortran:
          CALL PVMFREDUCE(PvmMax, MYVALS, COUNT, REAL4,
         &                MTAG, 'worker', ROOT, INFO)

ERRORS

       These error conditions can be returned by pvm_reduce

       PvmNoInst
              Calling task is not in the group

       PvmBadParam
              The datatype specified is not appropriate for the specified reduction function.

       PvmSysErr
              Pvm system error

SEE ALSO

       pvm_bcast(3PVM), pvm_barrier(3PVM), pvm_psend(3PVM)

                                         6 February, 1995                            REDUCE(3PVM)