Zoltan Developer's Guide | Next | Previous

## Debugging Services

Execution of code for debugging can be controlled by algorithm specific parameters or by the Zoltan key parameter DEBUG_LEVEL. The value of the Debug_Level field of the Zoltan_Struct structure can be tested to determine whether the user desires debugging information. Several constants (ZOLTAN_DEBUG_*) are defined in zz/zz_const.h; the Debug_Level field should be compared to these values so that future changes to the debugging levels can be made easily. An example is included below.

Several macros for common debugging operations are provided. The macros can be used to generate function trace information, such as when control enters or exits a function or reaches a certain point in the execution of a function.

> ZOLTAN_TRACE_ENTER
> ZOLTAN_TRACE_EXIT
> ZOLTAN_TRACE_DETAIL

These macros produce output depending upon the value of the DEBUG_LEVEL parameter set in Zoltan by a call to Zoltan_Set_Param. The macros are defined in zz/zz_const.h.

Examples of the use of these macros can be found below and in lb/lb_balance.c and rcb/rcb.c.

ZOLTAN_TRACE_ENTER(struct Zoltan_Struct *zz, char *function_name);

ZOLTAN_TRACE_ENTER prints to stdout a message stating that a given processor is entering a function. The call to the macro should be included at the beginning of major functions for which debugging information is desired. Output includes the processor number and the function name passed as an argument to the macro. The amount of output produced is controlled by the value of the DEBUG_LEVEL parameter set in Zoltan by a call to Zoltan_Set_Param.

Arguments: |
zz | Pointer to a Zoltan structure.
function_name | Character string containing the function's name.
Output: |
| ZOLTAN (Processor #) Entering function_name

ZOLTAN_TRACE_EXIT(struct Zoltan_Struct *zz, char *function_name);

ZOLTAN_TRACE_EXIT prints to stdout a message stating that a given processor is exiting a function. The call to the macro should be included at the end of major functions (and before return statements) for which debugging information is desired. Output includes the processor number and the function name passed as an argument to the macro. The amount of output produced is controlled by the value of the DEBUG_LEVEL parameter set in Zoltan by a call to Zoltan_Set_Param.

Arguments: |
zz | Pointer to a Zoltan structure.
function_name | Character string containing the function's name.
Output: |
| ZOLTAN (Processor #) Leaving function_name

ZOLTAN_TRACE_DETAIL(struct Zoltan_Struct *zz, char *function_name, char *message);

ZOLTAN_TRACE_DETAIL prints to stdout a message specified by the developer. It can be used to indicate how far execution has progressed through a routine. It can also be used to print values of variables. See the example below. Output includes the processor number, the function name passed as an argument to the macro, and a user-defined message passed to the macro. The amount of output produced is controlled by the value of the DEBUG_LEVEL parameter set in Zoltan by a call to Zoltan_Set_Param.

Arguments: |
zz | Pointer to a Zoltan structure.
function_name | Character string containing the function's name.
message | Character string containing a message defined by the developer.
Output: |
| ZOLTAN (Processor #) function_name: message

Example:
An example using the debugging macros in shown below. `

#include "zoltan.h"
void example(struct Zoltan_Struct *zz)
{
char *yo = "example";
char tmp[80];
int a, b;

ZOLTAN_TRACE_ENTER(zz, yo);
a = function_one(zz);
ZOLTAN_TRACE_DETAIL(zz, yo, "After function_one");
b = function_two(zz);
sprintf(tmp, "b = %d a = %d", b, a);
ZOLTAN_TRACE_DETAIL(zz, yo, tmp);
if (zz->Debug_Level >= ZOLTAN_DEBUG_ALL)
printf("Total = %d\n", a+b);
ZOLTAN_TRACE_EXIT(zz, yo);

}

`

[Table of Contents | Next: Adding New Load-Balancing Algorithms | Previous: ZOLTAN_TIMER | Privacy and Security]