Provided by: pvm-dev_3.4.5-12.5ubuntu1_amd64 
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)