Zoltan Developer's Guide  |  Next  |  Previous

Memory Management in Zoltan Algorithms

Zoltan uses a memory management package to simplify debugging of memory problems. It is strongly recommended that algorithm developers use the routines in this package, such as ZOLTAN_MALLOC , ZOLTAN_CALLOC and ZOLTAN_FREE, instead of the standard C routines for most memory management.

Macros that simplify the allocation of global and local identifiers (IDs) are defined in zz/zz_id_const.h. These macros are described in the ID Data Types section. The macros include error checking for the allocations and, thus, their use is highly recommended.

When a dynamic structure needs to be returned to the application, special memory allocation routines are needed.  For example, the import and export lists of data to migrate are returned to an application from Zoltan_LB_Partition and Zoltan_Invert_Lists. There are two special routines for managing memory for such situations, called Zoltan_Special_Malloc and Zoltan_Special_Free. Algorithms must use these functions to maintain compatibility with both C and Fortran90 applications; these special routines manage memory in a way that is compatible with both languages.

Some load-balancing algorithms may contain persistent data structures, that is, data structures that are preserved between calls to the load-balancing routine. The Zoltan_Struct structure contains a field LB.Data_Structure for this purpose, allowing multiple Zoltan structures to preserve their own decomposition data. The developer should write a function that frees this data structure.  Use Zoltan_RCB_Free_Structure as an example.

int Zoltan_Special_Malloc(struct Zoltan_Struct *zz, void **array, int size, ZOLTAN_SPECIAL_MALLOC_TYPEtype); 

The Zoltan_Special_Malloc routine allocates memory to be returned to the application by Zoltan (e.g., the result arrays of Zoltan_LB_Partition and Zoltan_Invert_Lists). Returned memory must be allocated by Zoltan_Special_Malloc to insure it is allocated by the same language as the application. Memory allocated by Zoltan_Special_Malloc must be deallocated by Zoltan_Special_Free.
 
Arguments:
    zz The Zoltan structure currently in use.
    array Upon return, a pointer to the allocated space. Usually of type int** or ZOLTAN_ID_PTR*.
    size The number of elements (not bytes) to be allocated.
    type The type of array to allocate. Must be one of ZOLTAN_SPECIAL_MALLOC_INT, ZOLTAN_SPECIAL_MALLOC_GID or ZOLTAN_SPECIAL_MALLOC_LID for processor numbers, global IDs and local IDs, respectively.
Returned Value:
   int 1 if the allocation succeeded; 0 if it failed.
Example:
ierr = Zoltan_Special_Malloc(zz, (void **)import_gid,
                             num_import,
                             ZOLTAN_SPECIAL_MALLOC_GID);
Allocates an array with num_import global IDs and returns a pointer to the allocated space in import_gid.

int Zoltan_Special_Free(struct Zoltan_Struct *zz, void **array, ZOLTAN_SPECIAL_MALLOC_TYPE type); 

Zoltan_Special_Free frees memory allocated by Zoltan_Special_Malloc. The array pointer is set to NULL upon return.
 
Arguments:
    zz The Zoltan structure currently in use.
    array The array to be freed. Upon return, the pointer is set to NULL.
    type The type of the array. Must be one of ZOLTAN_SPECIAL_MALLOC_INT, ZOLTAN_SPECIAL_MALLOC_GID or ZOLTAN_SPECIAL_MALLOC_LID for processor numbers, global IDs and local IDs, respectively.
Returned Value:
   int 1 if the deallocation succeeded; 0 if it failed.
Example:
ierr = Zoltan_Special_Free(zz, (void **)import_gid,
                       ZOLTAN_SPECIAL_MALLOC_GID);
Frees the global IDs array import_gid and sets it to NULL.

 


[Table of Contents  |  Next:  Parameters  |  Previous:  Data Structures  |  Privacy and Security]