REDUCE(3PVM)							  PVM Version 3.4						      REDUCE(3PVM)

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 spec-
       ified 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  pur-
       poses).

       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)