MulticoreBSP for C  Version 2.0.4
Functions
Single Program, Multiple Data Framework

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:

To end SPMD sections, the following primitives are available:

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

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

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_messageThe 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
PThe 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
spmdEntry point for new threads in the SPMD program.
argcNumber of supplied arguments in argv.
argvList 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_messageThe error message to display.
argsA list of arguments needed to display the above error_message.

References mcbsp_vabort.