SPMD Framework

Collaboration diagram for SPMD Framework:

Functions
void	bsp_init (void(*spmd_part)(void), int argc, char *argv[])
void	bsp_begin (int maxprocs)
void	bsp_end (void)
void	bsp_abort (const char *format,...)
int	bsp_nprocs (void)
int	bsp_pid (void)
double	bsp_time (void)
void	bsp_sync (void)

Detailed Description

BSPlib adopts the Single Program Multiple Data (SPMD) programming model.

There are basically two flavours of packaging your parallel program. In case your entire program is SPMD, there is a simple way:

#include <bsp.h>
 
int main(int argc, char ** argv)
{
    bsp_begin( bsp_nprocs() );
 
    // doing the parallel code here
 
    bsp_end();
    return 0;
}

If some initialisation or postprocessing by exactly one process is required, a slightly more elaborate start-up is required:

#include <bsp.h>
 
void spmd(void)
{
    bsp_begin( bsp_nprocs() );
 
    // doing the parallel code here
 
    bsp_end();
}
 
int main(int argc, char ** argv)
{
    bsp_init( &spmd, argc, argv);
 
    // doing some sequential initialisation here....
 
    spmd();
 
    // doing some sequential postprocessing here...
 
    return 0;
}

In the latter fashion, process 0 in the SPMD section is the continuation of the original process initiating the program.

Function Documentation

bsp_init()

void bsp_init	(	void(*)(void)	spmd_part,
		int	argc,
		char *	argv[]
	)

Explicitly initializes the BSPlib runtime. This function must be called if some of the program is not supposed to run in parallel, i.e. the first statement in your program is not bsp_begin() or the last statement before return or exit is not bsp_end(). That might happen, for example, if some initialization or postprocessing work has to be performed sequentially at the start or end of the program, respectivly. In this case the parallel part of the program must be in a separate function, whose pointer has to be provided through the spmd_part parameter.

Parameters

[in]	spmd_part	The pointer to the function with the parallel part of the program. The first statement of that function must be bsp_begin(). The last the statement must be bsp_end().
[in]	argc	Number of command line parameters argc as provided by main
[in]	argv	Array of pointers argv to the command line parameters as provided by main

Exceptions

bsp_abort	When parameter spmd_part is NULL
bsp_abort	When bsp_init() called more than once.

See also

bsp_begin

bsp_end

bsp_begin()

void bsp_begin

(

int

maxprocs

)

Start the parallel section of the program with at most maxprocs BSP processes. If some sequential initialization of preprocessing is required, a call to bsp_init() first is mandatory.

Parameters

[in]

maxprocs

Number of requested processes. It is not guaranteed that this amount will be available. The actual number is returned by bsp_nprocs() after the call to bsp_begin().

Exceptions

bsp_abort	When bsp_begin() is called for a second time without an intermediate call to bsp_init first.
bsp_abort	When maxprocs is less than 1.
bsp_abort	When it runs out of memory.

See also

bsp_init

bsp_end

bsp_nprocs

bsp_end()

void bsp_end

(

void

)

End the parallel section of the program. If some sequential postprocessing is required a call to bsp_init() is mandatory.

Exceptions

bsp_abort	When bsp_begin() hasn't been called yet
bsp_abort	When bsp_end() is called for a second time
bsp_abort	When another process called bsp_sync() instead
bsp_abort	When communication subsystem fails.

See also

bsp_init

bsp_begin

bsp_nprocs

bsp_abort()

void bsp_abort	(	const char *	format,
			...
	)

Abnormally terminate execution of all BSP processes with the given message. The format and subsequent parameters are exactly the same as printf.

Parameters

[in]

format

Format string which is exactly as printf

Exceptions

bsp_abort

Always

bsp_nprocs()

int bsp_nprocs

(

void

)

Return the number of available parallel processes. When called before bsp_begin(), it returns an upper bound of how many be acquired by a bsp_begin(). When called after bsp_begin(), it returns how many processes are actually used.

Returns

The number of available parallel processes.

Exceptions

bsp_abort

When it is called outside an SPMD section and it failed to query machine parameters

bsp_pid()

int bsp_pid

(

void

)

Return the ID of the process. The processes are uniquely numbered from 0 to P-1 where P is the number of processes in the parallel section.

Returns

The ID of the process.

Exceptions

bsp_abort

When not between bsp_begin() and bsp_end()

Invariant

bsp_pid() < bsp_nprocs()

bsp_pid() >= 0

bsp_time()

double bsp_time

(

void

)

Return the elapsed wall clock time in seconds since bsp_begin().

Returns

The elapsed wall clock time in seconds since bsp_begin()

Exceptions

bsp_abort

When not between bsp_begin() and bsp_end()

Remarks

Clocks will run roughly at the same pace on each process, but it is not a global clock. It can and will happen that for brief moments speeds differ. Over longer periods of time clock drift can be substantial.

bsp_sync()

void bsp_sync

(

void

)

Separates two supersteps with a barrier synchronization. There is no notion of subset synchronization, so all processes must participate. Doing otherwise will result in undefined behaviour and a runtime error when one of the processes exits. Communication that was initiated in the previous superstep is guaranteed to have finished after a call to this function.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end()
bsp_abort	When another process called bsp_end()
bsp_abort	When not all processes deregistered the same registration slot with bsp_pop_reg()
bsp_abort	When not all processes registered the same number of memory regions with bsp_push_reg()
bsp_abort	When not all processes set the same message tag size with bsp_set_tagsize()
bsp_abort	When it runs out of memory.
bsp_abort	When the communication subsystem fails.