Zoltan Developer's Guide | Next | Previous

## 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
Programming Conventions

Namespaces
Class names
Method names
Const methods
Declaration of method parameters
Copy constructor, copy operator

Keeping the C++ interface up-to-date

### 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.

#### Namespaces

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

Class names are Zoltan_ followed by text indicating the sub function of Zoltan that is encapsulated by the class.

#### Method names

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.

#### Const methods

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.

#### Declaration of method parameters

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.

#### Copy constructor, copy operator

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]