Req-7: Global IDs ----------------------------------------------------------------------------- Notes: - An ITAPS global ID is represented as an array of integers, int*. Is default storage an issue for arrays of global IDs? We propose storage should be in xyzxyz format; that is, an array of two global IDs of size 3 is stored [globalID1[0] globalID1[1] globalID1[2] globalID2[0] globalID2[1] globalID2[2]]. - ITAPS global IDs are unique over entities needed for services using them. Will more than one service be using global IDs simultaneously? To prevent conflicts or errors, we will require global IDs to be unique across all entities. (This requirement is easily satisfied by appending entity type to the global ID.) - We will require that an application either sets global IDs itself or explicitly requests the implementation to create global IDs. Requests for global IDs that are made before either setting or creating global IDs will generate an error. This requirement is important for interoperability; all implementations should report errors for missing global IDs consistently. - For now, we assume no locking or immutability rules for global IDs. Caveat emptor. - Still to be determined: How are invalid results handled, particularly for array-based functions? E.g., iPart_getGlobalID finds 90% of the requested global IDs; how do we let the application know which 10% were not found? - The definition of a partition should be expanded to include a mesh or set of meshes. ----------------------------------------------------------------------------- Agreed at the Bootcamp: An ITAPS global ID would be represented as an array of integers. The size of the array can be computed by the user (for user-defined global IDs) or the implementation (for implementation-generated global IDs). ----------------------------------------------------------------------------- Getting Global ID Information iPart_getGlobalSize Given a partition, return the number of integers per ID. This number must be the same over all parts. iPart_getGlobalID Given an entity handle, return its global ID and a flag/error code indicating whether a valid global ID exists for the entity. iPart_getGlobalIDArr Given an array of entity handles, return the global ID for each handle (in xyzxyz format above) and the number of valid global IDs returned. May also want to indicate for which entities valid IDs were returned. iPart_getEntHandle Given a global ID, return the entity handle associated with the global ID and a flag/error code indicating whether the entiry handle returned is valid. iPart_getEntHandleArr Given an array of global IDs, return the entity handle for each global ID and the number of valid entity handles returned. May also want to indicate for which global IDs valid entity handles were returned. ----------------------------------------------------------------------------- Setting Global ID Information iPart_setGlobalSize Given a partition and an integer N, set the number of integers per ID to N. N should be the same across all parts. iPart_setGlobalID Given an entity handle and a global ID, store the global ID with the entity. Return a flag indicating whether the entity was found. iPart_setGlobalIDArr Given an array of entity handles and an array of global IDs, store the global IDs with the entity handles. Return the number of successful assignments and, perhaps, an array indicating which assignments were (un)successful. iPart_createGlobalID Given an entity handle, generate a unique global IDs for the entity. Return a flag indicating whether the entity was found. The generated global ID is NOT returned by this function. This function simply says that the implementation is responsible for generating the global ID for the entity; the implementation can choose to generate and store the global ID now or generate it on the fly when the global ID is requested. This function may override any set Global ID size. iPart_createGlobalIDArr Given an array of entity handles, generate unique global IDs for the entities. Return the number of entities found and, perhaps, an array of entities that were (un)successfully found. The generated global IDs are NOT returned by this function. This function simply says that the implementation is responsible for generating the global IDs for the entities; the implementation can choose to generate and store global ID now or generate them on the fly when global IDs are requested. This function may override any set Global ID size. Note: Allowing applications to set global IDs for some entities and ask the implementation to generate global IDs for other entities is dangerous; there is no guarantee that the two sets of IDs will be unique. Perhaps we need an all-or-nothing test. ----------------------------------------------------------------------------- Comparing global IDs: iPart_cmpGlobalIDs Given two global IDs A and B, return -1 if A < B, 0 if A == B, and 1 if A > B. (Analogous to strcmp()). This function can be in-lined in the interface. % CVS File Information % $RCSfile: GlobalIDs.txt,v $ % $Author: vjleung $ % $Date: 2007/10/15 14:34:20 $ % $Revision: 1.5 $