Zoltan Developer's Guide  |  Next  |  Previous

Coding Principles in Zoltan

    Include files
    Global Variables
    Function Names
    Parallel Communication
    Memory Management
    Errors, Warnings and Return Codes

Include files

Include files should be used for function prototypes, macro definitions, and data structure definitions. The convention used is that external function prototypes and data structure definitions required by more than one module are stored in include files named *_const.h (e.g., zz/zz_const.h). Include files with static function prototypes or static data structure definitions (i.e., files that are included in only one module) are named *.h (e.g., rcb/rcb.h).

The include file include/zoltan.h contains the Zoltan interface; it should be included by C application source files that call Zoltan. C++ applications that use the C++ interface should include include/zoltan_cpp.h instead.

The include file zz/zz_const.h describes the principle Zoltan data structures. As these data structures are used heavily by the algorithms in Zoltan, zz/zz_const.h should be included in most source files of Zoltan.

Every Zoltan C language header file should be surrounded with an extern "C" {} declaration. The declaration must occur after every other #include statement, and before all function declarations. This declaration tells a C++ compiler not to mangle the names of functions declared in that header file.

#ifndef __EXAMPLE_H
#define __EXAMPLE_H

#include "mpi.h"
#include "zoltan_types.h"
#include "zoltan_align.h"

#ifdef __cplusplus
extern "C" {

int func1(int a, int b);
double dfunc(int a, int b, int c);

#ifdef __cplusplus
} /* closing bracket for extern "C" */

#endif /* __EXAMPLE_H */
Example of C language header file with extern "C"

If an #include statement appears after the opening of the extern "C" {} declaration, the included file may cause mpi.h or some other system header file to be processed. When compiling with a C++ compiler, this usually leads to compile errors because the function names in some of those headers are supposed to be mangled.

It should not be necessary to use the declaration in all header files, but rather only in header files that are used in C++ applications. But experience has taught us that you never know what header files will end up being included, and that one that is not included now, may be included in the future when someone adds an #include statement to a file. To save someone the effort later on of figuring out why their C++ compilation is failing, please include the extern "C" {} declaration in every header file, even if at this point in time you do not believe it will ever be included in the compilation of a C++ application.

Global variables

The use of global variables is highly discouraged in Zoltan. In limited cases, static global variables can be tolerated within a source file of an algorithm. However, developers should keep in mind that several Zoltan structures may be used by an application, with each structure using the same algorithm. Thus, global variables set by one invocation of a routine may be reset by other invocations, causing errors in the algorithms. Global variable names may also conflict with variables used elsewhere in the library or application, causing unintended side-effects and complicating debugging. For greatest robustness, developers are asked NOT to use global variables in their algorithms. See Data Structures for ideas on avoiding the use of global variables.

Function Names

In order to avoid name conflicts with applications and other libraries, all non-static functions should be prepended with Zoltan_.  Moreover, function names should, in general, include their module names; e.g., Zoltan_HSFC_Box_Assign is part of the HSFC module of Zoltan. As a general rule, each new word in a function name should be capitalized (for example, Zoltan_Invert_Lists). Static Zoltan functions do not have to follow these rules.

Parallel Communication

All communication in the Zoltan library should be performed through MPI communication routines. The MPI interface was chosen to enable portability to many different platforms. It will be especially important as the code is extended to heterogeneous computing systems.

Some useful communication utilities are provided within the library to perform unstructured communication and synchronization. See Unstructured Communication Utilities and Parallel Computing.

Memory Management

It is strongly suggested that all memory allocation in the library is handled using the functions supplied in Utilities/Memory. Use of these functions will make debugging and maintenance of the library much easier as the library gets larger. See Memory Management Utilities for more information on these utilities.

For memory that is returned by Zoltan to an application, however, special memory allocation functions must be used to maintain compatibility with both C and Fortran90 applications. See Memory Management in Zoltan Algorithms for more information.

One of the few data types specified for use in the Zoltan interface is the ZOLTAN_ID_PTR type used for global and local object identifiers (IDs). Macros simplifying and providing error checking for ID allocation and manipulation are provided.

Errors, Warnings, and Return Codes

If an error or warning occurs in the Zoltan library, a message should be printed to stderr (using one of the printing macros below), all memory allocated in the current function should be freed, and an error code should be returned. The Zoltan library should never "exit"; control should always be returned to the application with an error code. The error codes are defined in include/zoltan_types.h.

Currently, this philosophy is not strictly followed in all portions of Zoltan. Efforts are underway to bring existing code up-to-date, and to follow this rule in all future development.

ZOLTAN_PRINT_ERROR(int processor_number, char *function_name, char *message)
ZOLTAN_PRINT_WARN(int processor_number, char *function_name, char *message)

Macros for printing error and warning messages in Zoltan. The macros are defined in Utilities/shared/zoltan_util.h.
    processor_number The processor's rank in the Zoltan communicator. The value -1 can be used if the rank is not available.
    function_name A string containing the name of the function in which the error or warning occurred.
    message A string containing the error or warning message.

[Table of Contents  |  Next:  Zoltan Quality Assurance  |  Previous:  Philosophy  |  Privacy and Security]