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 | Zoltan_LB_function() Zoltan_LB_Partition() Zoltan_LB_Point_Assign() | Zoltan::function() Zoltan::LB_Partition() Zoltan::LB_Point_Assign()
Unstructured communication example: perform communication | Zoltan_Comm_function Zoltan_Comm_Do() | Zoltan_Comm::function Zoltan_Comm::Do()
Distributed data example: find objects in a remote process | Zoltan_DD_function Zoltan_DD_Find() | Zoltan_DD::function Zoltan_DD::Find()
Timers example: print timing results | Zoltan_Timer_function Zoltan_Timer_Print() | Zoltan_Timer::function Zoltan_Timer::Print()

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 Contents | Next: Initialization Functions | Previous: FORTRAN Interface | Privacy and Security]