POOMA: A C++ Toolkit for High-Performance Parallel Scientific Computing
PrevChapter 1. Getting Started with POOMANext

1.4. Writing and Compiling POOMA Programs

In this section, we describe how to write and compile POOMA programs. We illustrate this with a "Hello, POOMA" program that initializes and de-initializes the POOMA library.

The simplest POOMA program is available at examples/Manual/Sequential/initialize-finalize.cpp. It is annotated in Example 1-1. Before its use, the POOMA Toolkit must be initialized by a call to initialize. This usually occurs in the main function. After its use, the POOMA Toolkit should be shut down using a call to finalize. This also usually occurs in the main function. Both of these functions are declared in Pooma/Pooma.h. This header file (or another POOMA header file including it) occurs in every POOMA program.

Example 1-1. A "Hello, POOMA" Program


#include "Pooma/Pooma.h"  (1)
#include <iostream>

int main(int argc, char *argv[])
{
  // Prepare the Pooma library for execution.
  Pooma::initialize(argc,argv);  (2)

  std::cout << "Hello, Pooma." << std::endl;

  // Tell the Pooma library execution has finished.
  Pooma::finalize();  (3)
  return 0;
}
(1)
This POOMA header file must be included directly or indirectly in all POOMA programs.
(2)
Every POOMA program must initialize the POOMA library by invoking the initialize function.
(3)
The POOMA Toolkit is shut down by invoking the finalize function, which must be called after all other POOMA functions.

Compiling this program requires including POOMA header files and library. Let us assume that the environment variable POOMAHOME describes the location of the POOMA source code. For example,


export POOMAHOME=/home/user/pooma
We illustrate how to compile the program using the g++ compiler:

g++ -I${POOMAHOME}/src -I${POOMAHOME}/lib/LINUXgcc \
initialize-finalize.cpp -o initialize-finalize \
-L${POOMAHOME}/lib/${POOMASUITE} -lpooma-gcc
We explain the five command-line options:

-I${POOMAHOME}/src

is the root of a directory tree containing all POOMA template header files. For example, the full path name of Pooma/Pooma.h is ${POOMAHOME}/src/Pooma/Pooma.h.

-I${POOMAHOME}/lib/${POOMASUITE}

indicates the directory that contains configuration-specific header files.

initialize-finalize.cpp

is the source code to compile. It must have a main function with calls to POOMA's initialize and finalize.

-o initialize-finalize

determines the name of the resulting executable program.

-L${POOMAHOME}/lib/${POOMASUITE}

is the directory containing the POOMA library file to use.

-lpooma-gcc

indicates libpooma-gcc.a is the name of the POOMA library in the directory specified by the -L option.

Running the resulting executable prints "Hello, Pooma.":


$ ./initialize-finalize
Hello, Pooma.
$

1.4.1. DANGER: initialize and finalize

In this section, we present detailed explanations of initialize and finalize. Very few POOMA users ever need to use any form different from that presented in the "Hello, POOMA" program.

Prototypes

#include "Pooma/Pooma.h"
// or "Pooma/Arrays.h" or "Pooma/Fields.h" or …

bool Pooma::initialize( int &argc, char ** &argv, bool initRTS = true, bool getCLArgsArch = true, bool initArch = true );

bool Pooma::initialize( Pooma::Options &opts, bool initRTS = true, bool initArch = true );

bool Pooma::finalize(void);

bool Pooma::finalize( bool quitRTS, bool quitArch );

Explanation

Before its use, the POOMA Toolkit must be initialized by a call to initialize. This usually occurs in the main function. The first form removes and processes any POOMA-specific arguments from the command-line arguments argv and argc. The third, fourth, and fifth arguments all have a default value of true. If initRTS is true, the run-time system is initialized. E.g., the contexts are prepared for use. If getCLArgsArch is true, architecture-specific command-line arguments are removed from argv and argc. Architecture-specific initialization occurs if getCLArgsArch is true. An architecture is specified by a hardware interface, e.g., processor type, but frequently is also associated with an operating system or compiler. For example, Metrowerks for the Macintosh has an architecture-specific initialization. The function always returns true.

initialize's alternative form assumes the POOMA-specific and architecture-specific command-line arguments have already been removed from argv and argc and stored in opts. Its other two parameters have the same meaning, and the two functions' semantics are otherwise the same.

After its use, the POOMA Toolkit should be shut down using a call to finalize. This usually occurs in the main function. The former, and more frequently used, form first prints any statistics and turns off all default POOMA streams. Then it shuts down the run-time system if it was previously initialized and then shuts down architecture-specific objects if they were previously initialized. The latter form gives provides explicit control whether the run-time system (quitRTS) and architecture-specific objects (quitArch) are shut down. Both functions always returns true.

Including almost any POOMA header file, rather than just Pooma/Pooma.h suffices since most other POOMA header files include it.

PrevHomeNext
Compiling the POOMA LibraryUpSupporting Distributed Computation