C++ Interface
As with the Fortran interface just described, any change to the user
API of Zoltan should be reflected in the C++ interface. This section
explains the conventions used in the C++ interface, which you will want
to follow when you modify or expand it.
Classes
The C language Zoltan library already observes the principles of
object oriented program design. Each sub function of Zoltan (load
balancing, timing, etc.) has a data structure
associated with it. This data structure maintains all the state required
for one instance of that sub function. Each request of the library for
some operation requires that data structure.
The classes in the Zoltan C++ library follow the structure just described.
Each class is defined in a header
file and encapsulates a Zoltan data structure and the functions that
operate on that structure. A C++ application wishing to use a
feature of Zoltan, would include the feature's header file in it's source, and
link with the Zoltan C library.
The C language load balancing data stucture
(Zoltan_Struct)
and the C functions that operate on it are accessed
through the C++ Zoltan class, defined in zoltan_cpp.h.
The communication package is encapsulated the Zoltan_Comm class
defined in zoltan_comm_cpp.h.
Again, to use the communication utility of Zoltan from a C++ program,
include zoltan_comm_cpp.h and use the C++ methods defined there.
The C++ Zoltan timer class is called Zoltan_Timer_Object and
is defined in zoltan_timer_cpp.h.
The distributed directory utility of Zoltan is encapsulated in the
class Zoltan_DD defined in zoltan_dd_cpp.h
Programming Conventions
When modifying the interface to Zoltan , you will want to modify
the appropriate C++ header file accordingly. This section describes the
conventions to follow to maintain a consistent and correct library interface
for the C++ user of Zoltan.
In order to maintain portability across platforms, there is no Zoltan
namespace. Many C++ compilers do not support namespaces at this time.
The name of each Zoltan class begins with Zoltan_, and hopefully
this will never clash with another namespace.
Class names are Zoltan_ followed by text indicating the sub
function of Zoltan that is encapsulated by the class.
Method names are derived from the C library function names in such a
way that the name will be obvious to a person familiar with the C library.
We remove the beginning of the C library name, the part that identifies
the subset of the Zoltan library that the function is part of, and keep
the last part of the C library name, the part that describes what the
function does. For example the C function Zoltan_LB_Partition becomes
the C++ method LB_Partition in the class Zoltan and
C function Zoltan_Comm_Create becomes the C++ method
Create in the class Zoltan_Comm.
All class methods which can be declared const, because they
do not modify the object, should be declared const. This allows
C++ programmers to call these methods on their const objects.
Parameters that are not changed in the method should be declared const.
This can get complicated, but it helps to read declarations from right to
left. const int * & p says p is a reference to a pointer to
a const int and means the method will not change the value pointed
to by p. On the other hand int * const & p says that
p is a reference to a const pointer to int so the method will
not change the pointer.
Variables that are passed by value in a C function will be passed by
const reference in the C++ method. This is semantically the same, but
it is more efficient, and it will work with temporary variables created
by a compiler.
If a C function takes a pointer to a single built-in type (not an aggregate
type), the associated C++ method will take a reference variable.
If a C function takes a pointer to a pointer, the C++ function will take
a pointer reference. The references are more efficient, and it is
the behavior a C++ programmer expects.
A pointer to an array remains a pointer to an array.
| C function parameter | C++ method parameter | method's const behavior |
| int val |
const int &val |
won't change value |
| int *singlep |
int &singlep
const int &singlep |
may change value
won't change value |
| int **singlep |
int *&singlep
const int * &p
int *const &p
const int * const &p |
may change pointer or value
won't change value
won't change pointer to value
won't change anything |
| int *arrayp |
int *arrayp
const int * arrayp |
may change array contents
won't change array contents |
If a C function takes a pointer to an array of char, the
associated C++ method will take a string object.
| C function parameter | C++ method parameter |
| char *fname | std::string &fname |
In all honesty, it is tedious to carefully apply const'ness in
parameter declarations, and we did not do it consistently throughout the
C++ wrapping of Zoltan. Please feel free to add const declarations
where they belong, and try to use them correctly if you add or modify Zoltan
C++ methods.
Each class should have a copy constructor and a copy operator.
Keeping the C++ interface up-to-date
Here we provide a checklist of things to be done when the C interface to
the Zoltan library is changed:
- If a new major component is added to Zoltan, create a C++ class for
that component in a new header file, using the programming conventions
described above.
- If functions are added or removed, or their parameter lists are
changed, then update the header file defining the class that contains
those functions.
- When Zoltan data structures are changed, be sure to change the C functions
that copy the data structure. (They contain Copy in their name.)
Correct copying is more important in C++,
where the compiler may generate new temporary objects, than it is in C.
- If you change the C++ API, be sure to change:
- zCPPdrive, the test program for the Zoltan C++ library
- the C++ examples in the Examples directory
- the method prototypes in the Zoltan User's Guide.
[Table of Contents | Next:
References | Previous:
FORTRAN Interface | Privacy and Security]