REDUCE(3PVM)							 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.

DISCUSSION
  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 elementwise 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	dataypes 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
  dataypes 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 func-
  tion 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 neces-
  sary.	 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 parallel-
  ism.

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)