REDUCE(3PVM)

📦 version 3.4.6, in debian bookworm, ubuntu jammy

💖 REDUCE 💖 (the 3PVM one, bestie)

okay so. PVM Version 3.4 era, and we are talking about the group reduction moment. Sit down, hydrate, let's go. 🫶

✨ NAME ✨

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

Like. it takes everybody's little data arrays and squishes them into one. That's the whole vibe. 🎀

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

literally two languages, one dream. 💅

🦋 PARAMETERS 🦋

  • func — the function that defines the operation being done on the global data. The pre-defined girlies are PvmMax, PvmMin, PvmSum, and PvmProduct. But bestie, you can absolutely define your own function. main character energy fr.

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. Here's the tea: on return, the data array on the root gets 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 — like, they may be different than the values originally passed to pvm_reduce. 😭 do not trust them.
  • count — integer, the number of elements of datatype in the data array. The value of count should agree between all members of the group. no solo runs, everybody matches. 👑
  • datatype — integer specifying the type of the entries in the data array. (defined types listed below, keep scrolling ⬇️)
  • msgtag — integer message tag supplied by you. msgtag should be >= 0. It lets your program tell different kinds of messages apart. iykyk.
  • group — character string group name of an existing group.
  • rootginst — integer instance number of the group member who gets the result. the chosen one. ✨
  • 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. so like, however it gets there, it gets there. 🧚

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

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. (so sorry bytes, not your era for sum/product 🙈)

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, and it's a real one: 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 yeah, she's asynchronous and she said what she said. 😭

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

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

look at instance 1 eating. 🔥 everyone else? not defined. as always. 💀

⭐ EXAMPLES ⭐

C:

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

Fortran:

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

copy paste responsibly, bestie. 💅

💀 ERRORS 💀

These error conditions can be returned by pvm_reduce

  • PvmNoInst — Calling task is not in the group. (you're not on the list 😭)
  • PvmBadParam — The datatype specified is not appropriate for the specified reduction function. (wrong combo, no cap)
  • PvmSysErr — Pvm system error

🫶 SEE ALSO 🫶

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

and that's the page!! this absolute icon of a doc is dated 6 February, 1995, and it's part of PVM Version 3.4. vintage but still slaying. 🎀✨💖

📦 where this page comes from