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:
-
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.
-
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]