--- name: "pvm_reduce" section: "3" platform: "linux" package: "pvm-dev" version: "3.4.2-8" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/pvm_reduce" --- # pvm\_reduce(3) Performs a reduction operation over members of the specified group. ## 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)**