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" {
#endif
int func1(int a, int b);
double dfunc(int a, int b, int c);
#ifdef __cplusplus
} /* closing bracket for extern "C" */
#endif
#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.
| Arguments: |
|
| 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]