Collaboration diagram for Direct Remote Memory Access:

Functions
void	bsp_push_reg (const void *ident, int size)

void	bsp_pop_reg (const void *ident)

void	bsp_put (int pid, const void src, void dst, int offset, int nbytes)

void	bsp_hpput (int pid, const void src, void dst, int offset, int nbytes)

void	bsp_get (int pid, const void src, int offset, void dst, int nbytes)

void	bsp_hpget (int pid, const void src, int offset, void dst, int nbytes)

Detailed Description

As a means to communicate between processes BSPlib defines a set of functions to write in or read from the memory of another process.

The basic flow of statements is as follows:

Register memory with bsp_push_reg() and bsp_sync()
Do the communication with bsp_put(), bsp_hpput(), bsp_get(), or bsp_hpget()
Wait for the communication to finish with a bsp_sync()
Free resources by deregistering the memory with bsp_pop_reg()

For example: a program that computes the maximum return value of a function that is called by all processes.

#include <bsp.h>
#include <stdlib.h>
#include <stdio.h>
 
// A function that return a number depending on which process this is
int f( void )
{
    return 5 * bsp_pid();
}
 
 
int main( int argc, char ** argv)
{
    int a, maxA;
    int *b;
    bsp_pid_t s, root, p;
    bsp_nprocs_t P;
 
    // start the SPMD program
    bsp_begin( bsp_nprocs(  ) );
 
    // store some short-hands
    root = 0;
    P = bsp_nprocs(  );
    s = bsp_pid(  );
 
    // prepare an array to hold data
    b = ( int * ) malloc( sizeof( int ) * P );
 
    // register this array globally, so that anyone can reach it
    bsp_push_reg( b, sizeof( int ) * P );
    bsp_sync(  );
 
    // compute a value that depends somehow on this process
    a = f(  );
 
    // Gather from all processes the value of 'a' on process 0
    bsp_put( root, &a, b, sizeof( int ) * s, sizeof( int ) );
    bsp_sync(  );
 
    // Let process 0 determine the maximum
    if ( root == s )
    {
        maxA = -1;
        for ( p = 0; p < P; ++p )
            if ( maxA < b[p] ) maxA = b[p];
        printf( "The maximum is %d\n", maxA );
    }
 
    // free resources
    bsp_pop_reg( b );
    free( b );
 
    // terminate the program
    bsp_end(  );
    return 0;
}

Function Documentation

◆ bsp_push_reg()

void bsp_push_reg	(	const void *	ident,
		int	size
	)

Register a memory region to be used with bsp_put(), bsp_hpput(), bsp_get(), and bsp_hpget(). When a memory region is to be registered, all processes must call this function in the same superstep with the pointer ident to the memory region and its size. After the next bsp_sync() this will create a new registration slot for this memory region, which each process can identify by the pointer ident it supplied.

Remarks: Memory regions may be registered multiple times with the same pointer ident. When referenced the most recent registration slot takes precedence.; If a process wishes to register a memory region with zero size, which may be the case if it doesn't have to answer to remote puts and gets, it must still provide a (locally) unique pointer ident.; If a process is not involved in the communication at all, it may register NULL with a zero memory size.

Parameters

[in]	ident	Pointer to the memory region and identifier to the memory slot.
[in]	size	Size of the memory region in bytes.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end()
bsp_abort	When the size is negative
bsp_abort	When `NULL` is registered with a non-zero size

See also: bsp_pop_reg

◆ bsp_pop_reg()

void bsp_pop_reg ( const void * ident )

Deregister a memory region. When a memory region is to be deregistered, all processes must call this function in the same superstep with the pointer ident identifying the targeted registration slot, which is the same pointer that was used to register the memory region before. If two or more registration slots match the pointer, the most recent registration slot will be removed.

Parameters

[in] ident Pointer identifying the memory region.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end()
bsp_abort	When no memory registration slot can be identified by ident

See also: bsp_push_reg

◆ bsp_put()

void bsp_put	(	int	pid,
		const void *	src,
		void *	dst,
		int	offset,
		int	nbytes
	)

Copy local data into remote memory region where it will appear after the next bsp_sync(). The source data is copied to a buffer before the function returns, and the data is actually written in the destination memory at the next bsp_sync().

Parameters

[in]	pid	The process ID of the remote process
[in]	src	A pointer to the local source data
[out]	dst	A pointer identifying the registration slot of the remote memory region.
[in]	offset	A byte offset into the destination remote memory
[in]	nbytes	Number of bytes to copied.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When dst is `NULL`.
bsp_abort	When either offset or size is negative.
bsp_abort	When the registration slot of the remote memory region cannot be identified by dst.
bsp_abort	When the write would be beyond the extent of the registered memory region.

See also: bsp_hpput; bsp_push_reg

◆ bsp_hpput()

void bsp_hpput	(	int	pid,
		const void *	src,
		void *	dst,
		int	offset,
		int	nbytes
	)

Copy local data into remote memory region where it is guaranteed to be written after the next bsp_sync. The data may be copied at any time between the function call and the next bsp_sync(). It is therefore important not to touch the source and destination memory areas, as the result of that will be undefined.

Parameters

[in]	pid	The process ID of the remote process
[in]	src	A pointer to the local source data
[out]	dst	A pointer identifying the registration slot of the remote memory region.
[in]	offset	A byte offset into the destination remote memory
[in]	nbytes	Number of bytes to copied.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When dst is `NULL`.
bsp_abort	When either offset or size is negative.
bsp_abort	When the registration slot of the remote memory region cannot be identified by dst.
bsp_abort	When the operation would write beyond the extent of the registered memory region.

See also: bsp_put; bsp_push_reg

◆ bsp_get()

void bsp_get	(	int	pid,
		const void *	src,
		int	offset,
		void *	dst,
		int	nbytes
	)

Copy data from remote memory region into a local memory area where it will appear after the next bsp_sync(). The remote data is read and written to the local memory area at the next bsp_sync().

Parameters

[in]	pid	The process ID of the remote process
[in]	src	A pointer identifying the registration slot of the remote memory region.
[in]	offset	A byte offset into the source remote memory
[out]	dst	A pointer to the local memory area.
[in]	nbytes	Number of bytes to copied.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When src is `NULL`.
bsp_abort	When either offset or size is negative.
bsp_abort	When the registration slot of the remote memory region cannot be identified by src .
bsp_abort	When the write would beyond the extent of the registered memory region.

See also: bsp_hpget; bsp_push_reg

◆ bsp_hpget()

void bsp_hpget	(	int	pid,
		const void *	src,
		int	offset,
		void *	dst,
		int	nbytes
	)

Copy data from remote memory region into a local memory area where it is guaranteed to be written after the next bsp_sync(). The data is not buffered, which means that at any time in that particular super-step the remote data can be read, and that the retrieved data can be written to the local memory area at any time between the call to bsp_hpget() and the end of the call to the next bsp_sync().

Parameters

[in]	pid	The process ID of the remote process
[in]	src	A pointer identifying the registration slot of the remote memory region.
[in]	offset	A byte offset into the source remote memory
[out]	dst	A pointer to the local memory area.
[in]	nbytes	Number of bytes to copied.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When src is NULL.
bsp_abort	When either offset or size is negative.
bsp_abort	When the registration slot of the remote memory region cannot be identified by src .
bsp_abort	When the write would beyond the extent of the registered memory region.

See also: bsp_get; bsp_push_reg

Functions

Detailed Description

Function Documentation

◆ bsp_push_reg()

◆ bsp_pop_reg()

◆ bsp_put()

◆ bsp_hpput()

◆ bsp_get()

◆ bsp_hpget()