Migration

  In order to migrate entities, the user should take three steps: First, all the data which are attached to the entities should be registered with its four character MDB identification tag. This registration process is done only once at the beginning of the program. During the program run, it is also possible to unregister tags which have already been registered. If an entity which has unregistered data attached is migrated, memory leaks will result since there is no way for PMDB (which does not have access to MDB internal data structures) to find out whether any data is attached to an entity. There may be unintentional attempts by different library writers to use identical tags for their own attached data. Such actions can have disastrous effects. The return codes from registration mechanism also provides a means to prevent such scenarios.

Having registered attached data, the user needs to prepare arrays which contain the entities to be migrated and their destination processor ids. Since preparing these arrays maybe cumbersome, a utility routine is provided to do this. The user can call pmdb_insert_mig_entity() repeatedly with the entity address and the destination processor for migration to prepare these arrays.

Finally, the migration routines themselves can be called to perform the movement of entities to destination processors and to do a follow-up link update procedure.

int pmdb_tag_registerI(
pMeshPB pmeshpb,       /* IN */
eType   etype,         /* IN */
char   *tag,           /* IN */
unsigned char opts)    /* IN */

This function registers an integer attached data for entities of etype. The integer data is of length sizeof(long) bytes. Once a tag has been registered, when entities of etype are migrated, the attached data is also migrated and attached back when the entity is created at the target processor.

It returns 1 if the tag has been successfully registered and 0 if it has not successfully been registered due to presence of a duplicate tag.

The additional options allow the attachment of data with a requirement that the tag be unique and that the data should not be migrated. To obtain the default behavior, PMDB_TAG_DEFAULT should be passed in for opts. Other options are PMDB_TAG_NOMIGRATE to specify attachments that should not be migrated, but are being registered for the purpose of ensuring uniqueness, and PMDB_TAG_UNIQUE causes the program to abort if the same tag has been registered twice. To specify both, pass in PMDB_TAG_NOMIGRATE|PMDB_TAG_UNIQUE.

int pmdb_tag_unregisterI(
pMeshPB pmeshpb,         /* IN */
eType   etype,           /* IN */
char   *tag)             /* IN */

This routine deletes a registered integer data tag. It returns 1 if the tag has been successfully unregistered (deleted) and 0 if the tag could not be found for unregistering.

int pmdb_tag_registerP(
pMeshPB pmeshpb,       /* IN */
eType   etype,         /* IN */
char   *tag,           /* IN */
int     size,          /* IN */
unsigned char opts)    /* IN */

This function registers a pointer attached data for entities of etype. The data is assumed to be in contiguous block. It is possible to handle structures containing pointers to other data by allocating all the data including the structure itself in one contiguous block.

If size > 0, then the attached data is assumed to have fixed length and its length in bytes is given by size. If, on the other hand, size < 0, then the attached data has variable length and the first integer (sizeof(int) bytes) of the attached data is assumed to contain the size of the attached data in bytes including the first integer itself.

At its completion, the routine returns 1 if the tag has been successfully registered and 0 otherwise.

See pmdb_tag_registerI for a description of the opts argument.

int pmdb_tag_unregisterP(
pMeshPB pmeshpb,          /* IN */
eType   etype,            /* IN */
char   *tag)              /* IN */

This routine deletes a registered pointer attached data tag. It returns 1 if the tag has been successfully unregistered (deleted) and 0 if it could not be found for unregistering.

void pmdb_insert_mig_entity(
pEntity     entity,         /* IN  */
int         pid,            /* IN  */
int        *num_procs,      /* OUT */
int       **procids,        /* OUT */
long      **num_entities,   /* OUT */
pEntity  ***send_entities)  /* OUT */

This function is used to prepare arrays of entities and target processor to be fed into the migration operators pmdb_migrate_faces and pmdb_migrate_regions .

void pmdb_migrate_faces(
pMeshPB     pmeshpb,           /* IN  */
int         num_sends,         /* IN  */
long       *num_send_faces,    /* IN  */
pEntity   **send_faces,        /* IN  */
int        *dest_pid,          /* IN  */
int        *num_recvs,         /* OUT */
long      **num_recv_faces,    /* OUT */
pEntity  ***recv_faces,        /* OUT */
int       **src_pid)           /* OUT */

This routine migrates faces to other processors. It needs to be called by all processors.

void pmdb_migrate_regions(
pMeshPB     pmeshpb,
int         num_sends,
long       *num_send_regions,
pEntity   **send_regions,
int        *dest_pid,
int        *num_recvs,
long      **num_recv_regions,
pEntity  ***recv_regions,
int       **src_pid)

This routine migrates regions to other processors. It needs to be called by all processors. The arguments are the same as pmdb_migrate_faces with faces replaced by regions.