


bsp_push_reg(3)         BSPlib FUNCTIONS          bsp_push_reg(3)



NAME
     bsp_push_reg - register a data-structure  as  available  for
     direct remote memory access.


C SYNOPSIS
     #include "bsp.h"

     void bsp_push_reg (const void *_i_d_e_n_t, int _s_i_z_e);

FORTRAN SYNOPSIS
     SUBROUTINE  bsppushreg (_i_d_e_n_t, _s_i_z_e)
     <TYPE>, intent(IN) :: _i_d_e_n_t
     INTEGER, intent(IN):: _s_i_z_e


DESCRIPTION
     A bsplib(3) program consists of _p processes, each  with  its
     own  local memory. The SPMD structure of such a program pro-
     duces _p local instances of the various data structures  used
     in  the  program.  Although these _p instances share the same
     name, they will not, in  general,  have  the  same  physical
     address.  Due  to stack or heap allocation, or due to imple-
     mentation on a heterogeneous architecture,  one  might  find
     that the _p instances of variable _x have been allocated at up
     to _p different addresses.

     To allow bsplib(3) programs to execute correctly we  require
     a mechanism for relating these various addresses by creating
     associations called _r_e_g_i_s_t_r_a_t_i_o_n_s. A registration is created
     when  each  process calls bsp_push_reg(3) and, respectively,
     provides the address and the  extent  of  a  local  area  of
     memory.  Both types of information are relevant as processes
     can  create  new  registrations  by   providing   the   same
     addresses,  but different extents. The semantics adopted for
     registration enables procedures called within supersteps  to
     be  written in a modular way by allowing newer registrations
     to temporarily replace  older  ones.   However,  the  scheme
     adopted does not impose the strict nesting of push-pop pairs
     that is normally associated with a stack. This provides  the
     benefits  of  encapsulation provided by a stack, whilst pro-
     viding the flexibility associated with a heap-based  discip-
     line.  In  line with superstep semantics, _r_e_g_i_s_t_r_a_t_i_o_n _t_a_k_e_s
     _e_f_f_e_c_t _a_t _t_h_e _n_e_x_t _b_a_r_r_i_e_r _s_y_n_c_h_r_o_n_i_s_a_t_i_o_n.

     A registration association is destroyed  when  each  process
     calls  bsp_pop_reg(3)  and provides the address of its local
     area participating in that  registration.  A  runtime  error
     will  be  raised  if  these addresses (i.e., one address per
     process) do not refer to the same registration  association.
     In  line  with  superstep  semantics,  _d_e-_r_e_g_i_s_t_r_a_t_i_o_n _t_a_k_e_s
     _e_f_f_e_c_t _a_t _t_h_e _n_e_x_t _b_a_r_r_i_e_r _s_y_n_c_h_r_o_n_i_s_a_t_i_o_n.



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






bsp_push_reg(3)         BSPlib FUNCTIONS          bsp_push_reg(3)



EXAMPLES
     1)   Each  process   dynamically   allocates   (_b_s_p__p_i_d()+_1)
          integers  using  calloc(3)  and  registers  the data as
          available for remote memory access.

          int *data;
          data = calloc(bsp_pid()+1,sizeof(int));
          bsp_push_reg(data,(bsp_pid()+1)*sizeof(int));
          bsp_sync();


     2)   Consider the following two pieces of  code  being  exe-
          cuted on two different processors:

          _O_n _p_r_o_c_e_s_s _0
          int x,y;
          x = 1;
          y = 2;
          bsp_push_reg(&x,sizeof(int));
          bsp_sync();
          bsp_put(1,&y,&x,0,sizeof(int));
          bsp_sync();

          _O_n _P_r_o_c_e_s_s _1
          int x;
          x = 3;
          y = 4;
          bsp_push_reg(&x,sizeof(int));
          bsp_sync();
          bsp_sync();

          Both process 0 and process 1 register _x in their  first
          slot.  When  process  0 executes a bsp_put(3) using the
          variable _x as the  destination  region  name,  this  is
          mapped  to  the region whose address is associated with
          the first slot in Process 1. Therefore, after the  last
          synchronisation identified by bsp_sync(3), on process 0
          _x=_1 and _y=_2, and on process 1 _x=_2 and _y=_4.


SEE ALSO
     drma(3),    bsp_pop_reg(3),    bsp_put(3),     bsp_hpput(3),
     bsp_get(3), bsp_hpget(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.






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






bsp_push_reg(3)         BSPlib FUNCTIONS          bsp_push_reg(3)



NOTES
     i    bsp_push_reg(3) takes effect at the end of  the  super-
          step.  DRMA(3)  operations may use the registered areas
          from the start of the next superstep.


     ii   DRMA(3) operations are allowed to use memory areas that
          have  been  de-registered  in  the  same  superstep, as
          bsp_pop_reg(3) only takes effect at the end of a super-
          step.


     iii  Communication into unregistered memory areas  raises  a
          runtime error.


     iv   Registration is a property of an area of memory and not
          a reference to the memory.  There can therefore be many
          references (i.e.,  pointers)  to  a  registered  memory
          area.


     v    If only a subset  of  the  processes  are  required  to
          register  data because a program may have no concept of
          a _c_o_m_m_o_n_l_y _n_a_m_e_d memory area on all processes, then all
          processes  must  call bsp_push_reg(3) although some may
          register the memory area  NULL.  This  memory  area  is
          regarded as unregistered.


     vi   While registration is designed for ``full duplex'' com-
          munication,  a process can do half duplex communication
          by, appropriately, registering an area of size 0.


     vii  It is an error to provide negative values for the  size
          of the registration area.


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                    3



