NAME

     bsp_fold - fold (aka reduce) an associate operator between a
     single data item held in each process

C SYNOPSIS

     #include "bsp_level1.h"

     void bsp_fold(void (*op)(void*,void*,void*,int*),
                   void *src, void *dst, int nbytes)

FORTRAN SYNOPSIS

     SUBROUTINE bspfold(op,src,dst,nbytes)
       INTERFACE
         SUBROUTINE op(res,left,right,n)
           INTEGER, intent(IN) :: n
           <TYPE>,  intent(IN) :: left,right
           <TYPE>,  intent(OUT):: res
       END INTERFACE
       INTEGER, intent(IN)  :: nbytes
       <TYPE>,  intent(IN)  :: src
       <TYPE>,  intent(OUT) :: dst

DESCRIPTION

     A collective reduction operation  that  combines  the  local
     copies  of the data src on each processor, using an associa-
     tive, binary operator op. The result  of  the  reduction  is
     copied into dst on all the processors.

     The data-structures src and dst have to be of size nbytes on
     each  process.  The procedure op is defined by the user, and
     combines the arguments left and right,  placing  the  result
     into  right. The size of left, right, and result all have to
     be nbytes. When defining the procedure op, the user does not
     have  to  cope  with  the  possibility that result, left, or
     right are aliased.

EXAMPLES

     1)   Consider the definition of a function bsp_sum that sums
          a single integer stored on each process.

          void addition(int *res, int *left, int *right; int *nbytes) {
            *res = 0;
            *res = *left + *right;
          }

          int bsp_sum(x) {
            int result;
            bsp_fold(addition,&x,&result,sizeof(int));
            return result;
          }

          The assignment *res  =  0  in  the  definition  is  not
          semantically necessary as it doesn't change the desired
          effect of the summation. This is guarenteed as  neither
          right or leftwill be aliased to result.

NOTES

     In the C implementation of bsp_fold, the nbytes argument  to
     the  operator  op is defined to be a pointer to a integer so
     that either a C or Fortran 77 subroutine can be used as op.

SEE ALSO

     bsplib_level1(3), bsp_scan(3)

BUGS

     Problems  and  bug  reports  should  be  mailed  to  bsplib-
     bugs@comlab.ox.ac.uk

AUTHORS

     Jonathan.Hill@comlab.ox.ac.uk
     http://www.comlab.ox.ac.uk/oucl/people/jonathan.hill.html