Collection of BSPlib primitives that control BSP processes. More...

Functions
static void	bsp_begin (const bsp_pid_t P)
	The first statement in an SPMD program. More...

static void	bsp_end (void)
	Terminates an SPMD program. More...

static void	bsp_init (void(spmd)(void), int argc, char *argv)
	Prepares for parallel SPMD execution of a given program. More...

static void	bsp_abort (const char *const error_message,...)
	Aborts an SPMD program. More...

static void	bsp_vabort (const char *const error_message, va_list args)
	Alternative bsp_abort call. More...

static bsp_pid_t	bsp_nprocs (void)
	Returns the number of available processors or processes, depending on whether we are inside or outside an BSP SPMD section. More...

static bsp_pid_t	bsp_pid (void)
	Returns a unique BSP process identifier. More...

static double	bsp_time (void)
	Indicates the elapsed time in this SPMD run. More...

static void	bsp_sync (void)
	Signals the end of a superstep and starts global synchronisation. More...

Detailed Description

Collection of BSPlib primitives that control BSP processes.

Each BSP process executes the same program– and to do useful computation, this program should be run on different data; hence the BSP paradigm falls under the Single Program, Multiple Data (SPMD) family. Additionally, BSP imposes a strict structure on a BSP program's algorithmic structure; a program consists out of a series of supersteps, and each superstep consists of (1) a computation phase, and (2) a communication phase. From an algorithmic viewpoint, communication is not allowed during a computation phase, while computation is not be allowed during a communication phase. In practice, however, an implementation may perform asynchronous communication and may not even require global barriers.

To start SPMD sections, BSPlib defines the following primitives:

bsp_init Initialises the BSP runtime and registers the SPMD section.
bsp_begin Starts an SPMD program.

To end SPMD sections, the following primitives are available:

bsp_end Cleanly exits an SPMD run.
bsp_abort Aborts an SPMD run, as soon as possible.

To provide BSP processes introspection about the SPMD run they take part in:

bsp_pid Returns a process ID that is unique in the current SPMD run.
bsp_nprocs Returns the number of processes in the current SPMD run.

To signal the end of the current computation phase and start the following communication phase:

bsp_sync

In BSPlib, an SPMD program is given by a function wherein the first executable statement is bsp_begin, and the last executable statement is bsp_end. If the SPMD function is not `int main()', the SPMD section must first be registered using bsp_init. The functions bsp_end, bsp_abort, and bsp_pid will raise errors when called outside an SPMD section.

Function Documentation

static void bsp_abort	(	const char *const	error_message,
			...
	)

inlinestatic

Aborts an SPMD program.

Will print an error message once and notifies other threads in the SPMD program to abort. Other threads stop at the next bsp_sync or bsp_end at latest. The error message is in the regular C printf format, with a variable number of arguments.

Parameters

error_message The error message to display.

References mcbsp_vabort.

static void bsp_begin ( const bsp_pid_t P )

inlinestatic

The first statement in an SPMD program.

Spawns P threads.

If the bsp_begin() is the first statement in a program (i.e., it is the first executable statement in main), then a call to bsp_init prior to bsp_begin is not necessary.

Normally main() intialises the parallel computation and provides an entry-point for the SPMD part of the computation using bsp_init. This entry-point is a function wherein the first executable statement is this bsp_begin primitive.

Note: with MCBSP_COMPATIBILITY_MODE defined, P is of type int.

Parameters

P	The number of threads requested for the SPMD program.

References mcbsp_begin.

static void bsp_end ( void )

inlinestatic

Terminates an SPMD program.

This should be the last statement in a block of code opened by bsp_begin. It will end the thread which calls this primitive, unless the current thread is the originator of the parallel run. Only that original thread will resume with any remaining sequential code.

References mcbsp_end.

static void bsp_init	(	void(*)(void)	spmd,
		int	argc,
		char **	argv
	)

inlinestatic

Prepares for parallel SPMD execution of a given program.

Provides an entry-point for new threads when spawned by a bsp_begin. To properly start a new thread on distributed-memory machines, as was the goal of BSPlib, the program arguments are also supplied.

The function spmd points is assumed to have bsp_begin as its first statement, and bsp_end as its final statement.

Parameters

spmd	Entry point for new threads in the SPMD program.
argc	Number of supplied arguments in argv.
argv	List of the application arguments.

References mcbsp_init.

static bsp_pid_t bsp_nprocs ( void )

inlinestatic

Returns the number of available processors or processes, depending on whether we are inside or outside an BSP SPMD section.

Outside an SPMD section, this primitive returns the number of BSP processors; i.e., the number of single units of execution, where each such unit is capable of running a BSP process. Note that the notion of a BSP process is one that lives in the BSP algorithmic model, and the notion of a BSP processor is one from the BSP computer model. On modern architectures, this primitive returns the number of supported hardware threads on the current architecture.

Inside an SPMD section, this primitive returns the number of SPMD processes that are active within the current BSP run.

Note: if MCBSP_COMPATIBILITY_MODE is defined, the return type of this function is `int'. Otherwise, it is of type `unsigned int'.

Returns: The number of available processes (inside SPMD). or the number of available BSP processors.

References mcbsp_nprocs.

static bsp_pid_t bsp_pid ( void )

inlinestatic

Returns a unique BSP process identifier.

This function may only be called from within a BSP SPMD section.

A BSP process identifier during an SPMD run is a unique integer from the set $\{0,1,\ldots,P-1\}$ , where P is the value returned by bsp_nprocs. This unique identifier is constant during the entire SPMD program, that is, from bsp_begin until bsp_end.

Note: if MCBSP_COMPATIBILITY_MODE is defined, the return type of this function is `int'. Otherwise, it is of type `unsigned int'.

Returns: The unique BSP process ID.

References mcbsp_pid.

static void bsp_sync ( void )

inlinestatic

Signals the end of a superstep and starts global synchronisation.

A BSP SPMD program is logically separated in supersteps; during a superstep threads may perform local computations and buffer communication requests with other BSP threads. These buffered communication requests are executed during synchronisation. When synchronisation ends, all communication is guaranteed to be finished and threads start executing the next superstep.

The available communication-queueing requests during a superstep are: bsp_put, bsp_get, bsp_send. Those primitives strictly adhere to the separation of supersteps and communication. Other communication primitives, bsp_hpput, bsp_hpget and bsp_direct_get are less strict in this separation; refer to their documentation for details.

References mcbsp_sync.

static double bsp_time ( void )

inlinestatic

Indicates the elapsed time in this SPMD run.

This function may only be called from within a BSP SPMD section.

Returns the time elapsed since the start of the current BSP process. Time is returned in seconds. The timers across the various BSP processes from a single SPMD program are not necessarily synchronised. (I.e., this is not a global timer!).

Returns: Elapsed time since the local bsp_begin, in seconds.

References mcbsp_time.

static void bsp_vabort	(	const char *const	error_message,
		va_list	args
	)

inlinestatic

Alternative bsp_abort call.

Works with a va_list reference to pass a variable number of arguments. Implemented primarily for if a user wants to wrap bsp_abort in his or her own function with variable arguments.

Parameters

error_message	The error message to display.
args	A list of arguments needed to display the above error_message.

References mcbsp_vabort.

Functions

Detailed Description

Function Documentation