


bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



NAME
     bsp_get, bsp_hpget -  copy  data  from  a  remote  processes
     memory


C SYNOPSIS
     #include "bsp.h"

     void bsp_get(int _p_i_d,const void *_s_r_c, int _o_f_f_s_e_t,void *_d_s_t,int _n_b_y_t_e_s);

     void bsp_hpget(int _p_i_d,const void *_s_r_c, int _o_f_f_s_e_t,void *_d_s_t,int _n_b_y_t_e_s);

FORTRAN SYNOPSIS
     SUBROUTINE  bspget(_p_i_d,_s_r_c,_o_f_f_s_e_t,_d_s_t,_n_b_y_t_e_s)
       INTEGER, intent(IN)  :: _p_i_d,_o_f_f_s_e_t,_n_b_y_t_e_s
       <TYPE>,  intent(IN)  :: _s_r_c
       <TYPE>,  intent(OUT) :: _d_s_t

     SUBROUTINE  bsphpget(_p_i_d,_s_r_c,_o_f_f_s_e_t,_d_s_t,_n_b_y_t_e_s)
       INTEGER, intent(IN)  :: _p_i_d,_o_f_f_s_e_t,_n_b_y_t_e_s
       <TYPE>,  intent(IN)  :: _s_r_c
       <TYPE>,  intent(OUT) :: _d_s_t

DESCRIPTION
     The bsp_get(3) and bsp_hpget(3) operations  reach  into  the
     local   memory   of  another  process  and  copy  previously
     registered remote data held there into a data  structure  in
     the local memory of the process that initiated them.

     The semantics _b_u_f_f_e_r_e_d _o_n _s_o_u_r_c_e, _b_u_f_f_e_r_e_d _o_n _d_e_s_t_i_n_a_t_i_o_n is
     used  for  bsp_get(3)  communications.  This semantics means
     that the value taken from the source on the  remote  process
     by  the  get, is the value available once the remote process
     finishes executing all its superstep computations.  Further-
     more,  writing  the  value  from the remote process into the
     destination memory area on the initiating process only takes
     effect  at  the  end of the superstep after all remote reads
     from any other  bsp_get(3)  operations  are  performed,  _b_u_t
     _b_e_f_o_r_e  any  data  is  written by any bsp_put(3). Therefore,
     computation and buffered communication operations  within  a
     superstep can be _t_h_o_u_g_h_t to occur in the following order:


     1    local computation is performed; also, when a bsp_put(3)
          is excecuted, the associated source data is read;


     2    the source data associated with all  bsp_get(3)  opera-
          tions are read;


     3    data associated with any bsp_put(3) or  bsp_get(3)  are



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






bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



          written into the destination data structures.

          A high-performance version of get,  bsp_hpget(3),  pro-
          vides  the _u_n_b_u_f_f_e_r_e_d _o_n _s_o_u_r_c_e, _u_n_b_u_f_f_e_r_e_d _o_n _d_e_s_t_i_n_a_-
          _t_i_o_n semantics in which the two-way  communication  can
          take effect at any time during the superstep.


EXAMPLES
     1)   The  procedure  _g_e_t__a_r_r_a_y  is  the  dual  of  _p_u_t__a_r_r_a_y
          defined  in  the  manual  page for bsp_put(3). The pro-
          cedure is semantically  equivalent  to  the  concurrent
          assignment:

          forall i in {0,..,n-1} xs[i] := xs[xs[i]]

          void get_array(int *xs, int n) {
            int i,pid,local_idx,n_over_p=n/bsp_nprocs();
            if (n % bsp_nprocs())
              bsp_abort("{get_array} %d not divisible by %d",
                        n,bsp_nprocs());
            bsp_push_reg(xs,n_over_p*sizeof(int));
            bsp_sync();

            for(i=0;i<n_over_p;i++) {
              pid       = xs[i]/n_over_p;
              local_idx = xs[i]%n_over_p;
              bsp_get(pid,xs,local_idx*sizeof(int),&xs[i],sizeof(int));
            }
            bsp_sync();
            bsp_pop_reg(xs);
          }

          Similarly, the function can be defined in Fortran as:

                  SUBROUTINE getarray(xs,n)
                    INCLUDE 'fbsp.h'
                    INTEGER xs(*),n
                    INTEGER i,pid,localidx,noverp

                    noverp=n/bspnprocs()
                    IF (MOD(n,bspnprocs()) .NE. 0) THEN
                      CALL bspabort('N not divisible by p')
                    END IF
                    CALL bsppushreg(xs,noverp*BSPINT)
                    CALL bspsync()
                    DO i=1,noverp
                      pid      = xs(i)/noverp
                      localidx = MOD(xs(i),noverp)
                      CALL bspget(pid,xs,localidx*BSPINT,xs(i),BSPINT)
                    END DO
                    CALL bspsync()



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






bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



                    CALL bsppopreg(xs)
                  END

          In this example buffering  is  necessary  as  processes
          need to read data before it is overwritten. Thus, for a
          given array  element  _x_s[_i],  all  reads  generated  by
          bsp_get(3)  are performed ahead of the writes generated
          by any buffered operation, including those due  to  the
          bsp_get(3) of the process on which _x_s[_i] resides.


     2)   The function _b_s_p__s_u_m defined below is a collective com-
          munication  (i.e., all processes have to call the func-
          tion), such that when process _i calls the function with
          an  array _x_s containing _n_e_l_e_m__i, then the result on _a_l_l
          the processes will be the sum of all  the  arrays  from
          all the processes.

          int bsp_sum(int *xs, int nelem) {
            int *local_sums,i,j,result=0;
            for(j=0;j<nelem;j++) result += xs[j];
            bsp_push_reg(&result,sizeof(int));
            bsp_sync();

            local_sums = calloc(bsp_nprocs(),sizeof(int));
            if (local_sums==NULL)
              bsp_abort("{bsp_sum} no memory for %d int",bsp_nprocs());
            for(i=0;i<bsp_nprocs();i++)
              bsp_hpget(i,&result,0,&local_sums[i],sizeof(int));
            bsp_sync();

            result=0;
            for(i=0;i<bsp_nprocs();i++) result += local_sums[i];
            bsp_pop_reg(&result);
            free(local_sums);
            return result;
          }

          Similarly, the function can be defined in Fortran as:

                  INTEGER FUNCTION bspsum(xs,nelem)
                    INCLUDE 'fbsp.h'
                    INTEGER xs(*),nelem,MAXPROCS
                    PARAMETER (MAXPROCS=40)
                    INTEGER i,j,result,localsums(MAXPROCS)

                    result=0
                    DO j=1,nelem
                      result = result + xs(j)
                    END DO

                    CALL bsppushreg(result,BSPINT)



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






bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



                    CALL bspsync()
                    DO i=0,bspnprocs()-1
                      CALL bsphpget(i,result,0,localsums(i+1),BSPINT)
                    END DO
                    CALL bspsync()

                    result=0
                    DO i=1,bspnprocs()
                      result=result+localsums(i)
                    END DO
                    CALL bsppopreg(result)
                    bspsum=result
                  END

          The function contains three supersteps. In  the  first,
          the  local  array  _x_s  of  each  process  is summed and
          assigned to the variable _r_e_s_u_l_t. This variable is  then
          registered  for  communication in the subsequent super-
          step. Next, each local _r_e_s_u_l_t  is  broadcast  into  the
          _b_s_p__p_i_d()_t_h  element  of  _l_o_c_a_l__s_u_m_s} on every process.
          Unlike the previous examples, an unbuffered  communica-
          tion  is  used  in  preference to a buffered bsp_get(3)
          because the variable _r_e_s_u_l_t is not used  in  any  local
          computation during the same superstep as the communica-
          tion.  In the final superstep of  the  algorithm,  each
          process  returns  the sum of the _p values obtained from
          each process.


     3)   Consider a function _c_y_c_l_i_c__s_h_i_f_t executed on each  pro-
          cess,  that  takes  an  integer  _x as its argument, and
          returns the value of _x on its  left  neighbouring  pro-
          cess.

          int cyclic_shift(int x) {
            bsp_push_reg(&x,sizeof(int));
            bsp_sync();
            bsp_get( (bsp_pid()==0)?(bsp_nprocs()-1):bsp_pid()-1,
                     &x,0,
                     &x,
                     sizeof(int));
            bsp_sync();
            bsp_pop_reg(&x);
            return result;
          }


     4)   An alternative definition of _c_y_c_l_i_c _s_h_i_f_t that  uses  a
          high performance get.
          int cyclic_shift(int x) {
            int result;
            bsp_push_reg(&x,sizeof(int));



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






bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



            bsp_sync();
            bsp_hpget( (bsp_pid()==0)?(bsp_nprocs()-1):bsp_pid()-1,
                       &x,0,
                       &result,
                       sizeof(int));
            bsp_sync();
            bsp_pop_reg(&result);
            return result;
          }


     5)   Consider  an  alternative  definition  of  a   function
          _b_s_p__a_l_l_s_u_m_s  that  calculates  the  running  sums  of _p
          values stored on _p processors using a logorithmic tech-
          nique.  i.e.,  if  _x__i is stored on process _i, then the
          result on each processor is _x__0 + .. _x__i.

          #include "bsp.h"
          #include <stdio.h>

          int bsp_allsums(int x) {
            int i, left, right;

            bsp_push_reg(&right,sizeof(int));
            bsp_sync();

            right=x;
            for(i=1;i<bsp_nprocs();i*=2) {
              if (bsp_pid() >= i)
                bsp_get(bsp_pid()-i,&right,0,&left,sizeof(int));
              bsp_sync();
              if (bsp_pid()>=i) right=left+right;
            }
            bsp_pop_reg(&right);
            return right;
          }

          void main() {
            int y;
            bsp_begin(bsp_nprocs());
            y = bsp_pid()+1;
            printf("y=%d sums=%d\n",y,bsp_allsums(y));
            bsp_end();
          }

          A compilation, and an example run on four processors is
          shown below:

          pippin> bspcc allsums.c
          pippin> ./a.out
          y=4 sums=10
          y=2 sums=3



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






bsp_get(3)              BSPlib FUNCTIONS               bsp_get(3)



          y=1 sums=1
          y=3 sums=6



SEE ALSO
     drma(3),   bsp_push_reg(3),   bsp_pop_reg(3),    bsp_put(3),
     bsp_hpput(3)

     ``_B_S_P_l_i_b: _T_h_e _B_S_P _P_r_o_g_r_a_m_m_i_n_g _L_i_b_r_a_r_y'' Jonathan M. D. Hill,
     Bill  McColl,  Dan  C.  Stefanescu,  Mark W. Goudreau, Kevin
     Lang, Satish B. Rao, , Torsten Suel, Thanasis Tsantilas, and
     Rob  Bisseling.  Parallel  Computing,  to  appear  1998. See
     _h_t_t_p://_w_w_w._b_s_p-_w_o_r_l_d_w_i_d_e._o_r_g for more details.



NOTES
     i    The source  memory  area  used  in  a  get  has  to  be
          registered.  It is an error to fetch from a data struc-
          ture that has not been registered.


     ii   The  destination  of  a  get  does  _n_o_t  _h_a_v_e   _t_o   _b_e
          _r_e_g_i_s_t_e_r_e_d.


     iii  If the source memory area _s_r_c is registered  with  size
          _x,  then it is a bounds error to perform the communica-
          tion _b_s_p__g_e_t(_p_i_d,_s_r_c,_o,_d_s_t,_n) if _o+_n>_x.


     iv   A communication of zero bytes does nothing.


     v    A process can  read  from  its  own  memory  if  _p_i_d  =
          _b_s_p__p_i_d().  However, due to the _b_u_f_f_e_r_e_d _a_t _d_e_s_t_i_n_a_t_i_o_n
          semantics of bsp_get(3), the  memory  copy  only  takes
          effect  _a_t  _t_h_e  _e_n_d _o_f _t_h_e _s_u_p_e_r_s_t_e_p ; i.e, the source
          data is read and then written at the end of the  super-
          step.


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
     The Oxford BSP Toolset implementation of BSPlib was  written
     by 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                    6



