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 *ident, int size);

FORTRAN SYNOPSIS
SUBROUTINE  bsppushreg (ident, size)
<TYPE>, intent(IN) :: ident
INTEGER, intent(IN):: size

DESCRIPTION
A bsplib(3) program consists of p processes, each with its own local memory. The SPMD structure of such a program produces 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 implementation 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 registrations . 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 providing the flexibility associated with a heap-based discipline. In line with superstep semantics, registration takes effect at the next barrier synchronisation. 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, de-registration takes effect at the next barrier synchronisation.

EXAMPLES

1)  Each process dynamically allocates (bsp_pid()+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 executed on two different processors:
    On process 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();
    On Process 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) ``BSPlib: The BSP Programming Library'' 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 http://www.bsp-worldwide.org for more details.

NOTES

i   bsp_push_reg(3) takes effect at the end of the superstep. 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 superstep.

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 commonly named 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'' communication, 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 bsplib-bugs@comlab.ox.ac.uk

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