libmboard (Message Board Library)

Version 0.2.1

Overview

The Message Board Library provides memory management and message data synchronisation facilities for multi-agent simulations generated using the FLAME framework (http://www.flame.ac.uk).

As agents only interact with its environment (and each other) via messages, the Message Board library serves as a means of achieving parallelisation. Agents can be farmed out across multiple processors and simulated concurrently, while a coherent simulation is maintained through a unified view of the distributed Message Boards.

Synchronisation of the message boards are non-blocking as they are performed on a separate communication thread, allowing much of the communication time to be overlapped with computation.

Obtaining the source

You can download the latest release from CCPForge (http://ccpforge.cse.rl.ac.uk/frs/?group_id=8). We currently only provide private releases, so you will need to be logged in as a member of the FLAME framework project.

Developers and maintainers

If you are a developer and wish to use the development version (unstable), you can check out a copy from SVN (http://ccpforge.cse.rl.ac.uk/svn/xagents/trunk/libmboard). Within the checked out directory, you can either:

1. directly use the maintainer source by running ./autogen.sh to generate the Makefiles and configure script, or
2. generate your own release file by running ./create_distribution.sh. A *.tar.gz file will be generate (and tested).

Building and installing the Message Board library

1. Within the source directory, run "./configure". This will configure the source code for your system.
   • If you do not have root access, or do not wish to install the library into the default location (/usr/local), you can specify an alternative location by running "./configure --prefix=/your/target/dir" instead.
   • You can also provide further information to the configure script as arguments. Run "./configure --help" for a list of possible options.
2. Upon successful configuration, run "make" to compile the project.
3. (optional) You can run "make test" to compile and run the unit tests. You will need to have CUnit (http://cunit.sourceforge.net/) installed.
4. To install your newly built library, run "make install". This will install the libraries, header files, and scripts to either the default location or the directory you may have specified earlier.

Using the library

To use the Message Board library with your code, you will need to include the mboard.h header file, and call the appropriate Message Board API Routines. All Message Board routines return integer-based Return Codes. It is recommended that you always check the return code, and include sufficient error handling if the routine ends errorneously.

When linking your executable, you will need to link in the appropriate Message Board library. There are four versions available:

• link with -lmboard_s for the serial version.
• link with -lmboard_sd for the serial DEBUG version.
• link with -lmboard_p for the parallel version.
• link with -lmboard_pd for the parallel DEBUG version

Always use the DEBUG version during the development and testing stage of your project. They may incur performance overheads, but the DEBUG versions include crucial checks and assertions to ensure that the library is used correctly. Once your code has been validated and verified, you can switch to the standard version for your production runs.

If your library was installed to a non-default location (by configuring with "./configure --prefix=/libmboard/install/directory"), you will need to inform your compiler/linker where to locate the Message Board libraries and header files.

• append '-I/libmboard/install/directory/include' to your compilation flags (CFLAGS).
• append '-L/libmboard/install/directory/lib' to your linker flags (LDFLAGS).

The parallel versions of the library uses MPI and pthreads. Therefore, you may need additional compilation options or specific compilers when using then with you code. This depends on how your system was set up.

Starting from version 0.1.5, the mboard-conf utility is provided to assist you in generating the necessary flags for compiling your code with the Message Board library. It will be installed along with your library, and can be found in /libmboard/install/directory/bin.

Example:

• gcc 'mboard-config --cflags' -c test.c
• gcc 'mboard-config --ldflags' -o program test.o 'mboard-config --libs'

Run '/libmboard/install/directory/mboard-config --help' for more details.

Tuning

To tune the behaviour of libmboard, see Tuning libmboard using environment variables.

Example

The ./example/circle_mb directory within the source contains an example of how libmboard can be used within a project.