Zoltan Developer's Guide  |  Next  |  Previous

ID Data Types

Within Zoltan, objects are identified by a global identification (ID) value provided by the application. This global ID must be unique across all processors. The application may also provide a local ID value that it can use for faster location of objects within its own data structure. For example, local array indices to objects' data may be provided as the local IDs; these indices can then be used to directly access data in the query functions. Zoltan does not use these local IDs, but since it must pass them to the application in the interface query functions, it must store them with the objects' data.  ID data types and macros for manipulating IDs are described below.
IDs and Arrays of IDs
Allocating IDs
Common Operations on IDs

IDs and Arrays of IDs

Zoltan stores each global and local ID as an array of unsigned integers. Arrays of IDs are passed to the application as a one-dimensional array of unsigned integers with size number_of_IDs * number_of_entries_per_ID. A type definition ZOLTAN_ID_PTR (in include/zoltan_types.h) points to an ID or array of IDs. The number of array entries per ID can be set by the application using the NUM_GID_ENTRIES and NUM_LID_ENTRIES parameters.

Allocating IDs

Macros that simplify the allocation of global and local IDs are described in the table below. These macros provide consistent, easy-to-use memory allocation with error checking and, thus, their use is highly recommended.  Each macro returns NULL if either a memory error occurs or the number of IDs requested is zero.
 
ZOLTAN_ID_PTR ZOLTAN_MALLOC_GID(struct Zoltan_Struct *zz); Allocates and returns a pointer to a single global ID.
ZOLTAN_ID_PTR ZOLTAN_MALLOC_LID(struct Zoltan_Struct *zz); Allocates and returns a pointer to a single local ID.
ZOLTAN_ID_PTR ZOLTAN_MALLOC_GID_ARRAY(struct Zoltan_Struct *zz, int n); Allocates and returns a pointer to an array of n global IDs, where the index into the array for the ith global ID is i*NUM_GID_ENTRIES.
ZOLTAN_ID_PTR ZOLTAN_MALLOC_LID_ARRAY(struct Zoltan_Struct *zz, int n); Allocates and returns a pointer to an array of n local IDs, where the index into the array for the ith local ID is i*NUM_LID_ENTRIES.
ZOLTAN_ID_PTR ZOLTAN_REALLOC_GID_ARRAY(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR ptr, int n); Reallocates and returns a pointer to an array of n global IDs, replacing the current array pointed to by ptr.
ZOLTAN_ID_PTR ZOLTAN_REALLOC_LID_ARRAY(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR ptr, int n); Reallocates and returns a pointer to an array of n local IDs, replacing the current array pointed to by ptr.

Common Operations on IDs

In addition, macros are defined for common operations on global and local IDs.  These macros include error checking when appropriate and account for different values of NUM_GID_ENTRIES and NUM_LID_ENTRIES.  Use of these macros improves code robustness and simplifies code maintenance; their use is highly recommended.
 
void ZOLTAN_INIT_GID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR id); Initializes all entries of the global ID id to zero; id  must be allocated before calling ZOLTAN_INIT_GID.
void ZOLTAN_INIT_LID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR id); Initializes all entries of the local ID id to zero; id  must be allocated before calling ZOLTAN_INIT_LID.
void ZOLTAN_SET_GID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR tgt, ZOLTAN_ID_PTR src); Copies the global ID src into the global ID tgt.  Both src and tgt must be allocated before calling ZOLTAN_SET_LID.
void ZOLTAN_SET_LID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR tgt, ZOLTAN_ID_PTR src); Copies the local ID src into the local ID tgt.  Both src and tgt must be allocated before calling ZOLTAN_SET_LID.
int ZOLTAN_EQ_GID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR a, ZOLTAN_ID_PTR b); Returns TRUE if global ID a is equal to global ID b.
void ZOLTAN_PRINT_GID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR id); Prints all entries of a single global ID id.
void ZOLTAN_PRINT_LID(struct Zoltan_Struct *zz, ZOLTAN_ID_PTR id); Prints all entries of a single local ID id.


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