Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
REDUCE(3PVM)			PVM Version 3.4			  REDUCE(3PVM)

NAME
       pvm_reduce  - Performs a	reduction operation over members of the	speci-
       fied 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 re-
       duction	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  nec-
       essary.	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_re-
       duce.   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  implementa-
       tion  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 is-
       sued 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 re-
	      duction function.

       PvmSysErr
	      Pvm system error

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

			       6 February, 1995			  REDUCE(3PVM)

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | ILLUSTRATION | EXAMPLES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pvm_reduce&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help