REDUCE(3PVM)

💖 REDUCE(3PVM) 💖

okay bestie, sit down, hydrate, and let me tell you about pvm_reduce from PVM Version 3.4 — it's the group-chat glow-up your parallel program has been waiting for 🫶

---

✨ NAME ✨

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

like. it takes everybody's little data arrays and smooshes them into ONE. iconic behavior honestly 💅

---

✨ 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 — the function that defines the operation performed on the global data. Predefined for you are PvmMax, PvmMin, PvmSum, and PvmProduct. and yes, you can define your own function, go off 👑

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. so like, non-root besties, your array is in its ✨mystery era✨, don't trust it 😭
• 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. fr fr, everybody has to be on the same page.
• 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. the main character of this operation, lowkey 🎀
• info — Integer status code returned by the routine. Values less than zero indicate an error. if info is negative, something is giving 💀 not good.

---

✨ 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. no cap, element-wise, every single entry gets the treatment ✨

A broadcast by the root can be used if the other members of the group need the resultant value(s). so if the non-root girlies are nosy (valid), root can pvm_bcast it out 📣

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. yes bestie, byte girlies do NOT get sum or product, that's just the rules 🙈

C and Fortran defined datatypes are:

• PVM_BYTE / BYTE1
• PVM_SHORT / INTEGER2
• PVM_INT / INTEGER4
• PVM_FLOAT / REAL4
• PVM_CPLX / COMPLEX8
• PVM_DOUBLE / REAL8
• PVM_DCPLX / COMPLEX16
• PVM_LONG

(that's C datatypes on the left, FORTRAN datatypes on the right, and PVM_LONG is out here living its solo life with no Fortran twin 🦋)

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).

so like, it does NOT block. if you dip out of the group too early it's giving error 💀 add a pvm_barrier if you need everybody to actually be there.

The current algorithm is very simple and robust. A future implementation may make more efficient use of the architecture to allow greater parallelism. it's simple, it's robust, it's doing its best and honestly? we respect it 🌸

---

✨ 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 ......

the way instance 1 ate that sum and left zero crumbs 😭👑 111, 222, 333, 444, 555 — no cap, that's math AND main character energy.

---

✨ 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. bestie you are literally not in this group chat, exit stage left 🚪
• PvmBadParam — The datatype specified is not appropriate for the specified reduction function. wrong datatype for that op, the vibe check failed 💀
• PvmSysErr — Pvm system error. not our fault, the system is having a moment 😭

---

✨ SEE ALSO ✨

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

---

and that's the whole page bestie 💖 this was written up on 6 February, 1995, living in the PVM Version 3.4 era, filed under REDUCE(3PVM) — iconic then, iconic now. now go call pvm_reduce and slay ✨🎀🦋