


bsp_fold(3)               BSPlib level1               bsp_fold(3)



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 (*_o_p)(void*,void*,void*,int*),
                   void *_s_r_c, void *_d_s_t, int _n_b_y_t_e_s)

FORTRAN SYNOPSIS
     SUBROUTINE bspfold(_o_p,_s_r_c,_d_s_t,_n_b_y_t_e_s)
       INTERFACE
         SUBROUTINE op(_r_e_s,_l_e_f_t,_r_i_g_h_t,_n)
           INTEGER, intent(IN) :: _n
           <TYPE>,  intent(IN) :: _l_e_f_t,_r_i_g_h_t
           <TYPE>,  intent(OUT):: _r_e_s
       END INTERFACE
       INTEGER, intent(IN)  :: _n_b_y_t_e_s
       <TYPE>,  intent(IN)  :: _s_r_c
       <TYPE>,  intent(OUT) :: _d_s_t



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

     The data-structures _s_r_c and _d_s_t have to be of size _n_b_y_t_e_s on
     each  process.  The procedure _o_p is defined by the user, and
     combines the arguments _l_e_f_t and _r_i_g_h_t,  placing  the  result
     into  _r_i_g_h_t. The size of _l_e_f_t, _r_i_g_h_t, and _r_e_s_u_l_t all have to
     be _n_b_y_t_e_s. When defining the procedure _o_p, the user does not
     have  to  cope  with  the  possibility that _r_e_s_u_l_t, _l_e_f_t, or
     _r_i_g_h_t are aliased.


EXAMPLES
     1)   Consider the definition of a function _b_s_p__s_u_m 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;



Oxford BSP Toolset  Last change: 1.4 25/9/98                    1






bsp_fold(3)               BSPlib level1               bsp_fold(3)



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

          The assignment *_r_e_s  =  _0  in  the  definition  is  not
          semantically necessary as it doesn't change the desired
          effect of the summation. This is guarenteed as  neither
          _r_i_g_h_t or _l_e_f_twill be aliased to _r_e_s_u_l_t.



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



SEE ALSO
     bsplib_level1(3), bsp_scan(3)


BUGS
     Problems  and  bug  reports  should  be  mailed  to  _b_s_p_l_i_b-
     _b_u_g_s@_c_o_m_l_a_b._o_x._a_c._u_k


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

























Oxford BSP Toolset  Last change: 1.4 25/9/98                    2



