1REDUCE(3PVM) PVM Version 3.4 REDUCE(3PVM)
2
6 pvm_reduce - Performs a reduction operation over members of the speci‐
7 fied group.
8
11 C int info = pvm_reduce( void (*func)(),
12 void *data, int count, int datatype,
13 int msgtag, char *group, int rootginst)
14 Fortran call pvmfreduce(func, data, count, datatype,
16 msgtag, group, rootginst, info)
17
20 func Function which defines the operation performed on the global
21 data. Predefined are PvmMax, PvmMin, PvmSum, and PvmProduct.
22 Users can define their own function.
23 SYNOPSIS for func
25 C void func(int *datatype, void *x, void *y,
26 int *num, int *info)
27 Fortran call func(datatype, x, y, num, info)
28 data Pointer to the starting address of an array of local values.
30 On return, the data array on the root will be overwritten
31 with the result of the reduce operation over the group.
32 For the other (non-root) members of the group the values
33 of the data array upon return from the reduce operation
34 are not defined; the values may be different than
35 those originally passed to pvm_reduce.
36 count Integer specifying the number of elements of
38 datatype
39 in the data array.
40 The value of count should agree between all members of the group.
41 datatype
43 Integer specifying the type of the entries in the data array.
44 (See below for defined types.)
45 msgtag Integer message tag supplied by the user.
47 msgtag should be >= 0. It allows the user's program to
48 distinguish between different kinds of messages.
49 group Character string group name of an existing group.
51 rootginst
53 Integer instance number of group member who gets the result.
54 info Integer status code returned by the routine.
56 Values less than zero indicate an error.
57
61 pvm_reduce() performs global operations such as max, min, sum, or a
62 user provided operation on the data provided by the members of a group.
63 All group members call pvm_reduce with the same size local data array
64 which may contain one or more entries. The root task is identified by
65 its instance number in the group.
66 The inner workings of the pvm_reduce call are implementation dependent;
68 however, when the pvm_reduce call completes, the root's data array will
69 be equal to the specified operation applied element-wise to the data
70 arrays of all the group members.
71 A broadcast by the root can be used if the other members of the group
73 need the resultant value(s).
74 PVM supplies the following predefined functions that can be specified
76 in func.
77 PvmMin
78 PvmMax
79 PvmSum
80 PvmProduct
81 PvmMax and PvmMin are implemented for all the datatypes listed below.
83 For complex values the minimum [maximum] is that complex pair with the
84 minimum [maximum] modulus. PvmSum and PvmProduct are implemented for
85 all the datatypes listed below with the exception of PVM_BYTE and
86 BYTE1.
87 C and Fortran defined datatypes are:
89 C datatypes FORTRAN datatypes
90 -----------------------------------
91 PVM_BYTE BYTE1
92 PVM_SHORT INTEGER2
93 PVM_INT INTEGER4
94 PVM_FLOAT REAL4
95 PVM_CPLX COMPLEX8
96 PVM_DOUBLE REAL8
97 PVM_DCPLX COMPLEX16
98 PVM_LONG
99 A user defined function may be used in func. The argument func is a
101 function with four arguments. It is the base function used for the
102 reduction operation. Both x and y are arrays of type specified by
103 datatype with num entries. The arguments datatype and info are as
104 specified above. The arguments x and num correspond to data and count
105 above. The argument y contains received values.
106 Caveat: pvm_reduce() does not block, a call to pvm_barrier may be nec‐
108 essary. For example, an error may occur if a task calls pvm_reduce and
109 then leaves the group before the root has completed its call to
110 pvm_reduce. Similarly, an error may occur if a task joins the group
111 after the root has issued its call to pvm_reduce. Synchronization of
112 the tasks (such as a call to pvm_barrier) was not included within the
113 pvm_reduce implementation since this overhead is unnecessary in many
114 user codes (which may already synchronize the tasks for other pur‐
115 poses).
116 The current algorithm is very simple and robust. A future implementa‐
118 tion may make more efficient use of the architecture to allow greater
119 parallelism.
120
123 The following example illustrates a call to pvm_reduce. Suppose you
124 have three group members (instance numbers 0, 1, 2) with an array
125 called Idata with 5 values as specified:
126 instance the 5 values in the integer array
128 0 1, 2, 3, 4, 5
129 1 10, 20, 30, 40, 50
130 2 100, 200, 300, 400, 500
131 And, suppose that a call to reduce (such as the ones following) are
134 issued where the root is the group member with instance value of 1:
135 C:
137 root = 1;
138 info = pvm_reduce(PvmSum, &Idata, 5, PVM_INT, msgtag,
139 "worker", root);
140 Fortran:
141 root = 1
142 call pvmfreduce(PvmSum, Idata, 5, INTEGER4, msgtag,
143 "worker", root, info)
144 Then, upon completion of the reduce call, the following will result:
147 instance the 5 values in the integer array
149 0 .... not defined.......
150 1 111, 222, 333, 444, 555
151 2 .... not defined ......
152
156 C:
157 info = pvm_reduce(PvmMax, &myvals, 10, PVM_FLOAT,
158 msgtag, "worker", rootginst);
159 Fortran:
161 CALL PVMFREDUCE(PvmMax, MYVALS, COUNT, REAL4,
162 & MTAG, 'worker', ROOT, INFO)
163
166 These error conditions can be returned by pvm_reduce
167 PvmNoInst
169 Calling task is not in the group
170 PvmBadParam
172 The datatype specified is not appropriate for the specified
173 reduction function.
174 PvmSysErr
176 Pvm system error
177
179 pvm_bcast(3PVM), pvm_barrier(3PVM), pvm_psend(3PVM)
180 6 February, 1995 REDUCE(3PVM)