Zoltan User's Guide | Next | Previous

## C++ Interface

The C++ interface to the Zoltan library is contained in the header files listed below. Each header file defines one class. Each class represents a Zoltan data structure and the functions that operate on that data structure. The class methods in the header files call functions in the Zoltan C library. So to use the C++ interface from your application, include the appropriate header file and link with the Zoltan C library.

header file | class
--- | ---
include/zoltan_cpp.h | Zoltan, representing a load balancing instance
Utilities/Communication/zoltan_comm_cpp.h | Zoltan_Comm, representing an unstructured communication instance
Utilities/DDirectory/zoltan_dd_cpp.h | Zoltan_DD, representing a distributed directory instance
Utilities/Timer/zoltan_timer_cpp.h | Zoltan_Timer, representing a timer instance

More detailed information about the interface may be found in the Zoltan Developer's Guide.

Simple examples of the use of the interface may be found in the examples/CPP directory. A more complete example is the test driver zCPPdrive. The source code for this test driver is in the driver directory.

A note on declaring application registered query functions from a C++ application may be found in the section titled Application-Registered Query Functions.

Two peculiarities of the wrapping of Zoltan with C++ classes are mentioned here:

1. You must call the C language function Zoltan_Initialize before using the C++ interface to the Zoltan library. This function should only be called once. Due to design choices, the C++ interface maintains no global state that is independent of any instantiated objects, so it does not know if the function has been called or not. Therefore, the C++ wrappers do not call Zoltan_Initialize for you.
2. It is preferable to allocate Zoltan objects dynamically so you can explicitly delete them before your application exits. (Zoltan objects allocated instead on the stack will be deleted automatically at the completion of the scope in which they were created.) The reason is that the Zoltan destructor calls Zoltan_Destroy(), which makes an MPI call to free the communicator in use by the Zoltan object. However the MPI destructor may have been called before the Zoltan destructor. In this case you would receive an error while your application is exiting.

This second point is illustrated in the good and bad example below.

`int main(int argc, char *argv[])` `{` `MPI::Init(argc, argv);` `int rank = MPI::COMM_WORLD.Get_rank();` `int size = MPI::COMM_WORLD.Get_size();` `//Initialize the Zoltan library with a C language call` `float version;` `Zoltan_Initialize(argc, argv, &version);` `//Dynamically create Zoltan object.` `Zoltan *zz = new Zoltan(MPI::COMM_WORLD);` `zz->Set_Param("LB_METHOD", "RCB");` `//Several lines of code would follow, working with zz` `//Explicitly delete the Zoltan object` `delete zz;` `MPI::Finalize();` `}`
Good example, Zoltan object is dynamically allocated and explicity deleted before exit.

`int main(int argc, char *argv[])` `{` `Zoltan zz;` `MPI::Init(argc, argv);` `int rank = MPI::COMM_WORLD.Get_rank();` `int size = MPI::COMM_WORLD.Get_size();` `//Initialize the Zoltan library with a C language call` `float version;` `Zoltan_Initialize(argc, argv, &version);` `zz.Set_Param("LB_METHOD", "RCB");` `//Several lines of code would follow, working with zz` `MPI::Finalize();` `}`
Bad example, the MPI destructor may execute before the Zoltan destructor at process exit.

[Table of Contents | Next: Fortran Interface | Previous: Zoltan Usage | Privacy and Security]