Zoltan User's Guide  |  Next  |  Previous

Zoltan Interface Functions

An application calls a series of dynamic load-balancing library functions to initialize the load balancer, perform load balancing and migrate data. This section describes the syntax of each type of interface function:
General Zoltan Interface Functions
Load-Balancing Interface Functions
Functions for Augmenting a Decomposition
Migration Interface Functions
Graph Coloring Functions
Graph Ordering Functions
Examples of the calling sequences for initialization, load-balancing, and data migration are included in the Initialization, Load-Balancing, and Migration sections, respectively, of the Examples of Library Usage.

Error Codes

All interface functions, with the exception of Zoltan_Create, return an error code to the application. The possible return codes are defined in include/zoltan_types.h and Fortran module zoltan, and are listed in the table below.

Note:  Robust error handling in parallel has not yet been achieved in Zoltan.  When a processor returns from Zoltan due to an error condition, other processors do not necessarily return the same condition.  In fact, other processors may not know that the original processor has returned from Zoltan, and may wait indefinitely in a communication routine (e.g., waiting for a message from the original processor that is not sent due to the error condition).  The parallel error-handling capabilities of Zoltan will be improved in future releases.

ZOLTAN_OK Function returned without warnings or errors.
ZOLTAN_WARN  Function returned with warnings. The application will probably be able to continue to run.
ZOLTAN_FATAL  A fatal error occured within the Zoltan library.
ZOLTAN_MEMERR An error occurred while allocating memory. When this error occurs, the library frees any allocated memory and returns control to the application. If the application then wants to try to use another, less memory-intensive algorithm, it can do so.
Return codes defined in include/zoltan_types.h.

Naming conventions

The C, Fortran and C++ interfaces follow consistent naming conventions, as illustrated in the following table.

C and Fortran C++
Partitioning and migration functions
example: perform partitioning
example: assign a point to a part
Unstructured communication
example: perform communication
Distributed data
example: find objects in a remote process
example: print timing results

In particular, the C++ Zoltan class represents a load balancing instance and the methods that operate on it. The method name is identical to the part of the C and Fortran function name that indicates the function performed. A C++ Zoltan_Comm object represents an instance of unstructured communication, a C++ Zoltan_DD object represents a distributed directory, and a C++ Zoltan_Timer object is a timer. Their method names are derived similarly.

[Table of ContentsNext:  Initialization Functions  |  Previous:  FORTRAN Interface  |  Privacy and Security]