Zoltan User's Guide: Memory Management Utilities

Zoltan User's Guide | Next | Previous

Memory Management Utilities

This package consists of wrappers around the standard C memory allocation and deallocation routines which add error-checking and debugging capabilities. These routines are packaged separately from Zoltan to allow their independent use in other applications. A Fortran90 interface is not yet available. C++ programmers can include the header file "zoltan_mem.h" and use the C functions. This header file, and in fact all of Zoltan's C language header files, are surrounded by an extern "C" {} declaration to prevent name mangling when compiled with a C++ compiler.

Source code location:	Utilities/Memory
Function prototypes file:	Utilities/Memory/zoltan_mem.h or include/zoltan_mem.h
Library name:	libzoltan_mem.a
Other libraries used by this library:	libmpi.a. (See note below.)
Routines: Zoltan_Array_Alloc: Allocates arrays of dimension n, n=0,1,...,4 Zoltan_Malloc: Wrapper for system malloc. Zoltan_Calloc: Wrapper for system calloc. Zoltan_Realloc: Wrapper for system realloc. Zoltan_Free: Frees memory and sets the pointer to NULL. Zoltan_Memory_Debug: Sets the debug level used by the memory utilities; see the description below. Zoltan_Memory_Stats: Prints memory debugging statistics, such as memory leak information. Zoltan_Memory_Usage: Returns user-specified information about memory usage (i.e. maximum memory used, total memory currently allocated). Zoltan_Memory_Reset: Sets the memory usage total specified by the user (i.e. maximum memory used, total memory currently allocated) back to zero.
Use in Zoltan: The memory management utility routines are used extensively in Zoltan and in some individual algorithms. Zoltan developers use these routines directly for most memory management, taking advantage of the error checking and debugging capabilities of the library. Rather than call Zoltan_Memory_Debug directly, applications using Zoltan can set the DEBUG_MEMORY parameter used by this utility through calls to Zoltan_Set_Param.
Note on MPI usage: MPI is used only to obtain the processor number (through a call to MPI_Comm_rank) for print statements and error messages. If an application does not link with MPI, the memory utilities should be compiled with -DZOLTAN_NO_MPI; all output will then appear to be from processor zero, even if it is actually from other processors.

double *Zoltan_Array_Alloc(char * file, int line, int n, int d1, int d2, ..., int dn, int size);

The Zoltan_Array_Alloc routine dynamically allocates an array of dimension n, n = 0, 1, ..., 4 with size (d1 x d2 x ... x dn). It is intended to be used for 2, 3 and 4 dimensional arrays; Zoltan_Malloc should be used for the simpler cases. The memory allocated by Zoltan_Array_Alloc is contiguous, and can be freed by a single call to Zoltan_Free.

Arguments:
file	A string containing the name of the file calling the function. The __FILE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
line	The line number within file of the call to the function. The __LINE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
n	The number of dimensions in the array to be allocated. Valid values are 0, 1, 2, 3, or 4.
d1, d2, ..., dn	The size of each dimension to be allocated. One argument is included for each dimension.
size	The size (in bytes) of the data objects to be stored in the array.
Returned Value:
double *	A pointer to the starting address of the n-dimensional array, or NULL if the allocation fails.
Example:
	int x = (int ) Zoltan_Array_Alloc ( __FILE__ , __LINE__ , 2, 5, 6, sizeof (int));
	Allocates a two-dimensional, 5x6-element array of integers.

double *Zoltan_Malloc(size_t n, char * file , int line);

The Zoltan_Malloc function is a wrapper around the standard C malloc routine. It allocates a block of memory of size n bytes. The principle advantage of using the wrapper is that it allows memory leaks to be tracked via the DEBUG_MEMORY variable (set in Zoltan_Memory_Debug).

A macro ZOLTAN_MALLOC is defined in zoltan_mem.h. It takes the argument n, and adds the __FILE__ and __LINE__ macros to the argument list of the Zoltan_Malloc call:

#define ZOLTAN_MALLOC(n) Zoltan_Malloc((n), __FILE__, __LINE__)

Using this macro, the developer gains the file and line debugging information without having to type file and line information in each memory allocation call.

Arguments:
n	The size (in bytes) of the memory-allocation request.
file	A string containing the name of the file calling the function. The __FILE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
line	The line number within file of the call to the function. The __LINE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
Returned Value:
double *	A pointer to the starting address of memory allocated. NULL is returned if n = 0 or the routine is unsuccessful.
Example:
	struct Zoltan_Struct b = (struct Zoltan_Struct* ) ZOLTAN_MALLOC(sizeof(struct Zoltan_Struct*));
	Allocates memory for one Zoltan_Struct data structure.

double *Zoltan_Calloc(size_t num, size_t size, char * file, int line);

The Zoltan_Calloc function is a wrapper around the standard C calloc routine. It allocates a block of memory of size num * size bytes and initializes the memory to zeros. The principle advantage of using the wrapper is that it allows memory leaks to be tracked via the DEBUG_MEMORY variable (set in Zoltan_Set_Memory_Debug).

A macro ZOLTAN_CALLOC is defined in zoltan_mem.h. It takes the arguments num and size, and adds the __FILE__ and __LINE__ macros to the argument list of the Zoltan_Calloc call:

#define ZOLTAN_CALLOC(num, size) Zoltan_Calloc((num), (size), __FILE__, __LINE__)

Using this macro, the developer gains the file and line debugging information without having to type file and line information in each memory allocation call.

Arguments:
num	The number of elements of the following size to allocate.
size	The size of each element. Hence, the total allocation is num * size bytes.
file	A string containing the name of the file calling the function. The __FILE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
line	The line number within file of the call to the function. The __LINE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
Returned Value:
double *	A pointer to the starting address of memory allocated. NULL is returned if n = 0 or the routine is unsuccessful.
Example:
	int b = (int ) ZOLTAN_CALLOC( 10, sizeof(int));
	Allocates memory for 10 integers and initializes the memory to zeros.

double *Zoltan_Realloc(void *ptr, size_t n, char *file, int line);

The Zoltan_Realloc function is a "safe" version of realloc. It changes the size of the object pointed to by ptr to n bytes. The contents of ptr are unchanged up to a minimum of the old and new sizes. Error tests ensuring that n is a positive number and that space is available to be allocated are performed.

A macro ZOLTAN_REALLOC is defined in zoltan_mem.h. It takes the arguments ptr and n, and adds the __FILE__ and __LINE__ macros to the argument list of the Zoltan_Realloc call:

#define ZOLTAN_REALLOC(ptr, n) Zoltan_Realloc((ptr), (n), __FILE__, __LINE__)

Using this macro, the developer gains the file and line debugging information without having to type file and line information in each memory allocation call.

Arguments:
ptr	Pointer to allocated memory to be re-sized.
n	The size (in bytes) of the memory-allocation request.
file	A string containing the name of the file calling the function. The __FILE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
line	The line number within file of the call to the function. The __LINE__ macro can be passed as this argument. This argument is useful for debugging memory allocation problems.
Returned Value:
double *	A pointer to the starting address of memory allocated. If the routine is unsuccessful, NULL is returned and *ptr is unchanged.
Example:
	int n = sizeof(struct Zoltan_Struct); int b = (int* ) ZOLTAN_MALLOC* (n)); b = (int ) ZOLTAN_REALLOC* (b, 2*n);
	Reallocates memory for b from length n to length 2*n.

void Zoltan_Free(void **ptr, char * file , int line);

The Zoltan_Free function calls the system's "free" function for the memory pointed to by *ptr. Note that the argument to this routine has an extra level of indirection when compared to the standard C "free" call. This allows the pointer being freed to be set to NULL, which can help find errors in which a pointer is used after it is deallocated. Error checking is performed to prevent attempts to free NULL pointers. When Zoltan_Free is used with the DEBUG_MEMORY options (set in Zoltan_Memory_Debug), it can help identify memory leaks.

A macro ZOLTAN_FREE is defined in zoltan_mem.h. It takes the argument ptr, and adds the __FILE__ and __LINE__ macros to the argument list of the Zoltan_Free call:

#define ZOLTAN_FREE(ptr) Zoltan_Free((void **)(ptr), __FILE__, __LINE__)

Using this macro, the developer gains the file and line debugging information without having to type file and line information in each memory allocation call.

Arguments:
ptr	Address of a pointer to the memory to be freed. Upon return, ptr is set to NULL.
Example:
	ZOLTAN_FREE(& x);
	Frees memory associated with the variable x; upon return, x is NULL.

Debugging Memory Errors

One important reason to use the memory-management utilities' wrappers around the system memory routines is to facilitate debugging of memory problems. Various amounts of information can about memory allocation and deallocation are stored, depending on the debug level set through a call to Zoltan_Memory_Debug. This information is printed either when an error or warning occurs, or when Zoltan_Memory_Stats is called. We have found values of one and two to be very helpful in our development efforts. The routine Zoltan_Memory_Usage can be called to return user-specified information about memory utilization to the user's program, and Zoltan_Memory_Reset can be called to set totals back to zero.

void Zoltan_Memory_Debug(int new_level);

The Zoltan_Memory_Debug function sets the level of memory debugging to be used.

Arguments:
new_level	Integer indicating the amount of debugging to use. Valid options include: 0 -- No debugging. 1 -- The number of calls to Zoltan_Malloc and Zoltan_Free are tallied, and can be printed by a call to Zoltan_Memory_Stats. 2 -- A list of all calls to Zoltan_Malloc which have not yet been freed is kept. This list is printed by Zoltan_Memory_Stats (useful for detecting memory leaks). Any calls to Zoltan_Free with addresses not in this list trigger warning messages. (Note that allocations that occurred prior to setting the debug level to 2 will not be in this list and thus can generate spurious warnings.) 3 -- Information about each allocation is printed as it happens.
Default:
	Memory debug level is 1.

void Zoltan_Memory_Stats();

The Zoltan_Memory_Stats function prints information about memory allocation and deallocation. The amount of information printed is determined by the debug level set through a call to Zoltan_Memory_Debug.

Arguments:
	None.

size_t Zoltan_Memory_Usage(int type);

The Zoltan_Memory_Usage function returns information about memory utilization. The memory debug level (set through a call to Zoltan_Set_Memory_Debug) must be at least 2 for this function to return non-zero values.

Arguments:
type	Integer to request type of information required. These integers are defined in zoltan_mem.h. Valid options include: ZOLTAN_MEM_STAT_TOTAL -- The function will return the current total memory allocated via Zoltan's memory allocation routines. ZOLTAN_MEM_STAT_MAXIMUM -- The function will return the maximum total memory allocated via Zoltan's memory allocation routines up to this point.
Default:
	type = ZOLTAN_MEM_STAT_MAXIMUM
Returned Value:
int	The number in bytes of the specific requested memory statistic.
Example:
	total = Zoltan_Memory_Usage (ZOLTAN_MEM_STAT_TOTAL);

void Zoltan_Memory_Reset(int type);

The Zoltan_Memory_Reset function sets the specified count to zero.

Arguments:
type	Integer to specify the type of information to be reset . These integers are defined in zoltan_mem.h. Valid options include: ZOLTAN_MEM_STAT_TOTAL -- The function will set the count of total memory allocated via Zoltan's memory allocation routines to zero. ZOLTAN_MEM_STAT_MAXIMUM -- The function will set the count of maximum total memory allocated via Zoltan's memory allocation routines back to zero.
Default:
	type = ZOLTAN_MEM_STAT_MAXIMUM
Example:
	Zoltan_Memory_Reset (ZOLTAN_MEM_STAT_TOTAL);

[Table of Contents | Next: Unstructured Communication Utilities | Previous: Utilities | Privacy and Security]