Zoltan User's Guide: Interface

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.

*Return codes defined in include/zoltan_types.h.*
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.

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]