You are here: Documentation Quickstart for C

MulticoreBSP for C: a quick-start guide

For the purpose of this guide, we assume the following:

  • the GNU Compiler Collection (GCC) is installed, and `gcc' refers to GCC's C compiler,
  • you work in a UNIX-like shell environment,
  • you have downloaded the MulticoreBSP for C library to your current directory,
  • you have downloaded the BSPedupack from Prof. Dr. Rob Bisseling's website to your current directory.

The above links to versions 1.1 and 1.02 of MulticoreBSP for C and BSPedupack, respectively. These might not be the latest versions at the time you read this! Check the respective websites for the latest software updates (MulticoreBSP, BSPedupack).

Compiling the library

First extract all files with

  • tar xvfz MulticoreBSP-for-C.tar.gz

and the library will appear in the new `./MulticoreBSP-for-C' directory. We proceed with compilation:

  • cd MulticoreBSP-for-C;
  • make

This will create two new subdirectories: `include' and `lib'. Applications using MulticoreBSP for C need to include the header-file `mcbsp.h' found in the `include' directory, and link to the MulticoreBSP library at `lib/libmcbsp1.2.0.a'. No additional configuration is necessary.

Optional: testing the library

MulticoreBSP for C comes with a basic testing suite. To check if your version of the library compiled correctly, you may want to run these tests with

  • make tests

If all is OK, output should be as follows (excerpt):

...
./test_internal
SUCCESS
./test_util > ...
SUCCESS
./test_bsp
SUCCESS
./test_abort 2> ...
SUCCESS
./test_spmd
SUCCESS


Each executable verifies functions in a separate internal file from the libraries, or check specific functionalities which could not be integrated in other tests. If a failure occurs, it usually specifies the origin on a function-level; please report it if this happens.

The remainder of the quick-start deals with Compiling and running existing BSPlib C code first, and with writing new MulticoreBSP code second.

Compiling existing BSP programs

Suppose we have a BSP program written in C using the original BSPlib standard, and we want to use MulticoreBSP to run the same code on a modern multicore processor. To ensure full compatibility with BSPlib code, MulticoreBSP for C supports a compatibility mode we shall demonstrate now. First, we build MulticoreBSP for C in compatibility mode:

  • make compat

This creates a new file in the `lib' directory, namely `compat-libmcbsp1.2.0.a'. The include file for MulticoreBSP for C in compatibility mode remains unchanged. We demonstrate the compatibility mode using the BSPedupack software:

  • cd ..
  • tar xvf BSPedupack1.02.tar
  • cd BSPedupack1.02

We open bspedupack.h to adapt the BSP include header; i.e.,

  • change line 15 from `bspedupack.h' from #include "bsp.h" to #include "mcbsp.h"

MulticoreBSP for C does not require a special BSP-enabled compiler, but is compatible with standard C compilers. If the compiler defines a compatibility flag, the API of MulticoreBSP for C reverts back to the original BSPlib specifications. We adapt the BSPedupack makefile to this end:

  • change line 1 from `Makefile' from CC= bspcc to CC= gcc
  • change line 2 from `Makefile' from CFLAGS = ... to CFLAGS= -O3 -DMCBSP_COMPATIBILITY_MODE
MulticoreBSP for C makes use of the POSIX Threads (PThreads) and POSIX realtime (rt) standards. Programs compiled using MulticoreBSP for C should include the two POSIX libraries. This results in the last adaptation of the BSPedupack makefile:
  • change line 3 from `Makefile' from LFLAGS= -lm to LFLAGS= compat-libmcbsp1.2.0.a -pthread -lm -lrt

Warning for OS X and Windows users: Some popular OSes do not support the POSIX standards we use here; these include Mac OS X (no POSIX realtime) and Microsoft Windows (no POSIX threads and no POSIX realtime). On Mac OS X or Microsoft Windows, remove the `-lrt' from the LFLAGS above. On Microsoft Windows, make use of the PThreads-win32 project (see this forum post for details).
When in doubt which LFLAGS to use, the `deplibs' script in the MulticoreBSP for C directory auto-detects the proper dependencies; simply type ../MulticoreBSP-for-C/deplibs.sh to see its output.

Finally, we make the include and library file visible from our current location:

  • ln -s ../MulticoreBSP-for-C/include/mcbsp.h
  • ln -s ../MulticoreBSP-for-C/lib/compat-libmcbsp1.2.0.a

Note that these two files are also downloadable separately from the complete MulticoreBSP for C source package. In any case, we are now all set to build BSPedupack on top of MulticoreBSP:

  • make

Everything should have compiled without warnings. If you see warnings, ensure that they are not the result of not having the compatibility mode properly enabled (due to e.g. omitting or misspelling of the corresponding define flag).

Running BSP programs

If static linking is used (as above), running BSP applications requires no additional effort. The five BSPedupack applications can immediately be run as you would any application:

  1. ./bench, a BSP benchmarking utility
  2. ./ip, a parallel inner-product calculation
  3. ./lu, a parallel dense LU factorisation  (Note: the actual number of threads used is M times N)
  4. ./fft, a parallel Fast Fourier Transform for complex-valued vectors  (Note: both the vector length as well as the number of threads requested must be powers of 2!)
  5. ./matvec, a parallel sparse matrix–vector multiplication benchmark  (Note: BSPedupack includes a test matrix for 2 threads. Use `test.mtx-P2' as matrix, `test.mtx-v2' as the v-vector distribution, and `test.mtx-u2' as the u-vector distribution. Use the Mondriaan software to try other matrices.)

Writing, compiling, and running your own BSP application

Not relying on existing source, we give a very short `Hello world!' example on how to write parallel programs in MulticoreBSP for C. We change to the library directory and work from there.

  • cd ../MulticoreBSP-for-C
A MulticoreBSP for C application starts as any other C program. Let us first write the basic skeleton code:

#include <stdlib.h>

int main( int argc, char ** argv ) {
    return EXIT_SUCCESS;
}


and save this as `example.c'. To use our library to spawn three threads which each print `Hello world!', we include the MulticoreBSP for C header file and write the Single Program Multiple Data (SPMD) code which gets executed by each thread:

#include <stdlib.h>
#include <stdio.h>
#include "include/mcbsp.h"

void spmd() {
    bsp_begin( 3 );
    printf( "Hello world!\n" );
    bsp_end();
}

int main( int argc, char ** argv ) {
    return EXIT_SUCCESS;
}


All that remains is to let MulticoreBSP know that the entry point of our parallel SPMD program is the spmd program, and then direct the main thread to that code section to start the parallel execution.

#include <stdlib.h>
#include <stdio.h>
#include "include/mcbsp.h"

void spmd() {
    bsp_begin( 3 );
    printf( "Hello world!\n" );
    bsp_end();
}

int main( int argc, char ** argv ) {
    bsp_init( &spmd, argc, argv );
    spmd();
    return EXIT_SUCCESS;
}


We can now compile the example and indeed see it work:

  • gcc -o example example.c lib/libmcbsp1.2.0.a -pthread -lrt
  • ./example

The output should read

Hello world!
Hello world!
Hello world!


This shows the basics of using the MulticoreBSP library, and emplys only 3 out of the 22 BSP primitives available. Adding the use of bsp_nprocs and bsp_pid enables us to start a variable amount of threads, as well as differentiate between theads within the SPMD program:

#include <stdlib.h>
#include <stdio.h>
#include "include/mcbsp.h"

unsigned int P;

void spmd() {
    bsp_begin( P );
    printf( "Hello world from thread %d out of %d!\n", bsp_pid(), bsp_nprocs() );
    bsp_end();
}

int main( int argc, char ** argv ) {
    printf( "How many threads do you want started? There are %d cores available.\n", bsp_nprocs() );
    fflush( stdout );
    scanf( "%d", &P );
    if( P == 0 || P > bsp_nprocs() ) {
        fprintf( stderr, "Cannot start %d threads.\n", P );
        return EXIT_FAILURE;
    }
    bsp_init( &spmd, argc, argv );
    spmd();
    return EXIT_SUCCESS;
}


We can again compile this extended example and run it:

  • gcc -o example example.c lib/libmcbsp1.2.0.a -pthread -lrt
  • ./example

Output may, for example, look like the following:

How many threads do you want started? There are 4 cores available.
4
Hello world from thread 3 out of 4!
Hello world from thread 2 out of 4!
Hello world from thread 0 out of 4!
Hello world from thread 1 out of 4!


Note the arbitrary order of threads writing to screen. For meaningful parallel programming, communication between threads is necessary. Sixteen of the remaining seventeen MulticoreBSP primitives provide you with various means on how to do this; please refer to this single documentation page for a full description. The introductory text on the BSP model may help starting programmers as well.

With sufficient demand this section might be expanded to briefly demonstrate communication. In the mean time perhaps the forum can help provide answers to any remaining unclarities.