|
MOAB: Mesh Oriented datABase
(version 5.4.1)
|
|
MOAB: Mesh Oriented datABase
(version 5.4.1)
|
00001 #ifndef _ITAPS_iBase 00002 #define _ITAPS_iBase 00003 00004 /***************************************************************************/ /** 00005 * \ingroup 00006 *VersionNumbers 00007 * \brief Compile time 00008 *version number 00009 *digits 00010 * 00011 * iBase maintains a 00012 *major, minor and 00013 *patch digit in its 00014 *version number. 00015 * Technically 00016 *speaking, there is 00017 *not much practical 00018 *value in patch digit 00019 * for an interface 00020 *specification. A 00021 *patch release is 00022 *typically only used 00023 * for bug fix 00024 *releases. Although 00025 *it is rare, 00026 *sometimes a bug fix 00027 * necessitates an API 00028 *change. So, we 00029 *define a patch digit 00030 *for iBase. 00031 * 00032 * Although each 00033 *interface in ITAPS 00034 *has been designed to 00035 *support its own 00036 * unique version 00037 *numbers, apart from 00038 *other ITAPS 00039 *interfaces, as 00040 *currently used, we 00041 *require all ITAPS 00042 *interfaces to use 00043 *the same ITAPS-wide 00044 *version number 00045 *derived from the 00046 *version number 00047 *defined by these 00048 *three digits. 00049 ******************************************************************************/ 00050 #define IBASE_VERSION_MAJOR 1 00051 #define IBASE_VERSION_MINOR 4 00052 #define IBASE_VERSION_PATCH 1 00053 00054 /***************************************************************************/ /** 00055 * \ingroup 00056 *VersionNumbers 00057 * \brief Version 00058 *Comparison 00059 * 00060 * Evaluates to true 00061 *at CPP time if the 00062 *version of iBase 00063 *currently being 00064 * compiled is greater 00065 *than or equal to the 00066 *version specified. 00067 ******************************************************************************/ 00068 #define IBASE_VERSION_GE( Maj, Min, Pat ) \ 00069 ( ( ( IBASE_VERSION_MAJOR == ( Maj ) ) && ( IBASE_VERSION_MINOR == ( Min ) ) && \ 00070 ( IBASE_VERSION_PATCH >= ( Pat ) ) ) || \ 00071 ( ( IBASE_VERSION_MAJOR == ( Maj ) ) && ( IBASE_VERSION_MINOR > ( Min ) ) ) || \ 00072 ( IBASE_VERSION_MAJOR > ( Maj ) ) ) 00073 00074 /***************************************************************************/ /** 00075 * \ingroup 00076 *VersionNumbers 00077 * \brief Compose 00078 *compile-time string 00079 *represention of the 00080 *version number 00081 ******************************************************************************/ 00082 #define IBASE_VERSION_STRING___( I, X, Y, Z ) #I "_Version_" #X "." #Y "." #Z 00083 #define IBASE_VERSION_STRING__( I, X, Y, Z ) IBASE_VERSION_STRING___( I, X, Y, Z ) 00084 #define IBASE_VERSION_STRING_( I ) \ 00085 IBASE_VERSION_STRING__( I, IBASE_VERSION_MAJOR, IBASE_VERSION_MINOR, IBASE_VERSION_PATCH ) 00086 #define IBASE_VERSION_STRING IBASE_VERSION_STRING_( iBase ) 00087 00088 /***************************************************************************/ /** 00089 * \ingroup 00090 *VersionNumbers 00091 * \brief Compose 00092 *compile-time symbol 00093 *name derived from 00094 *the version number. 00095 ******************************************************************************/ 00096 #define IBASE_VERSION_TAG__( I, X, Y, Z ) I##_Version_##X##_##Y##_##Z 00097 #define IBASE_VERSION_TAG_( I, X, Y, Z ) IBASE_VERSION_TAG__( I, X, Y, Z ) 00098 #define IBASE_VERSION_TAG( I ) IBASE_VERSION_TAG_( I, IBASE_VERSION_MAJOR, IBASE_VERSION_MINOR, IBASE_VERSION_PATCH ) 00099 00100 /***************************************************************************/ /** 00101 * \ingroup 00102 *VersionNumbers 00103 * \brief ITAPS-wide 00104 *(across all ITAPS 00105 *APIs) version 00106 *handling 00107 ******************************************************************************/ 00108 #define ITAPS_VERSION_MAJOR IBASE_VERSION_MAJOR 00109 #define ITAPS_VERSION_MINOR IBASE_VERSION_MINOR 00110 #define ITAPS_VERSION_PATCH IBASE_VERSION_PATCH 00111 #define ITAPS_VERSION_GE( Maj, Min, Pat ) IBASE_VERSION_GE( Maj, Min, Pat ) 00112 #define ITAPS_VERSION_STRING_( I ) IBASE_VERSION_STRING_( I ) 00113 #define ITAPS_VERSION_STRING ITAPS_VERSION_STRING_( ITAPS ) 00114 #define ITAPS_VERSION_TAG_( I ) IBASE_VERSION_TAG( I ) 00115 #define ITAPS_VERSION_TAG ITAPS_VERSION_TAG_( I ) 00116 00117 /***************************************************************************/ /** 00118 * \defgroup 00119 *EnumIterators 00120 *Enum-Iterators 00121 * \ingroup iBase 00122 * \brief Convenience 00123 *macros for iterating 00124 *over all possible 00125 *values in an enum 00126 * 00127 * These convenience 00128 *macros are provided 00129 *to facilitate 00130 *iterating over all 00131 * possible values in 00132 *an enumerated type. 00133 *To use these macros, 00134 *for example... \code 00135 * for 00136 *(iBase_EntityType i 00137 *= 00138 *IBASE_MINENUM(iBase_EntityType); 00139 * i 00140 *<= 00141 *IBASE_MAXENUM(iBase_EntityType); 00142 * IBASE_INCENUM(i,iBase_EntityType)) 00143 * { 00144 * } 00145 * \endcode 00146 * Be aware that some 00147 *enumerated types 00148 *include a <em>wild 00149 *card</em> often used 00150 * in queries to 00151 *represent all 00152 *possible values and 00153 *you may or may not 00154 *want to include such 00155 *a value in your 00156 *iteration. 00157 ******************************************************************************/ 00158 00159 /***************************************************************************/ /** 00160 * \ingroup 00161 *EnumIterators 00162 * @{ 00163 ******************************************************************************/ 00164 #define IBASE_MINENUM( enumName ) enumName##_MIN 00165 #define IBASE_MAXENUM( enumName ) enumName##_MAX 00166 #define IBASE_NUMENUM( enumName ) ( (int)IBASE_MAXENUM( enumName ) - (int)IBASE_MINENUM( enumName ) + 1 ) 00167 #define IBASE_INCENUM( enumName, I ) ( ( I ) = ( enum( enumName ) )( (int)( I ) + 1 ) ) 00168 /** @} */ 00169 00170 #ifdef __cplusplus 00171 extern "C" { 00172 #endif 00173 00174 typedef void* iBase_Instance; 00175 typedef struct iBase_EntityHandle_Private* iBase_EntityHandle; 00176 typedef struct iBase_EntitySetHandle_Private* iBase_EntitySetHandle; 00177 typedef struct iBase_TagHandle_Private* iBase_TagHandle; 00178 typedef struct iBase_EntityIterator_Private* iBase_EntityIterator; 00179 typedef struct iBase_EntityArrIterator_Private* iBase_EntityArrIterator; 00180 00181 enum iBase_EntityType 00182 { 00183 iBase_EntityType_MIN = 0, 00184 /**< facilitates iteration over all values */ 00185 iBase_VERTEX = iBase_EntityType_MIN, 00186 /**< A topological dimension 0 entity */ 00187 iBase_EDGE, 00188 /**< A topological dimension 1 entity */ 00189 iBase_FACE, 00190 /**< A topological dimension 2 entity */ 00191 iBase_REGION, 00192 /**< A topological dimension 3 entity */ 00193 iBase_ALL_TYPES, 00194 /**< used only in queries to request information about all types */ 00195 iBase_EntityType_MAX = iBase_ALL_TYPES 00196 /**< facilitates iteration over all values */ 00197 }; 00198 00199 enum iBase_AdjacencyCost 00200 { 00201 iBase_AdjacencyCost_MIN = 0, 00202 /**< facilitates iteration over all values */ 00203 iBase_UNAVAILABLE = iBase_AdjacencyCost_MIN, 00204 /**< Adjacency information not supported */ 00205 iBase_ALL_ORDER_1, 00206 /**< No more than local mesh traversal required (i!=j) */ 00207 iBase_ALL_ORDER_LOGN, 00208 /**< Global tree search (i!=j) */ 00209 iBase_ALL_ORDER_N, 00210 /**< Global exhaustive search (i!=j) */ 00211 iBase_SOME_ORDER_1, 00212 /**< Only some adjacency info, local (i!=j) */ 00213 iBase_SOME_ORDER_LOGN, 00214 /**< Only some adjacency info, tree (i!=j) */ 00215 iBase_SOME_ORDER_N, 00216 /**< Only some adjacency info, exhaustive (i!=j) */ 00217 iBase_AVAILABLE, 00218 /**< ALL (intermediate) entities available. (i==j) */ 00219 iBase_AdjacencyCost_MAX = iBase_AVAILABLE 00220 /**< facilitates iteration over all values */ 00221 }; 00222 00223 enum iBase_CreationStatus 00224 { 00225 iBase_CreationStatus_MIN = 0, 00226 /**< facilitates iteration over all values */ 00227 iBase_NEW = iBase_CreationStatus_MIN, 00228 /**< The entity was newly created */ 00229 iBase_ALREADY_EXISTED, 00230 /**< The entity already existed and the handle for that 00231 already existing handle was returned */ 00232 iBase_CREATED_DUPLICATE, 00233 /**< The entity already existed but a new, duplicate entity was 00234 nevertheless created */ 00235 iBase_CREATION_FAILED, 00236 /**< Creation of the entity did not succeed */ 00237 iBase_CreationStatus_MAX = iBase_CREATION_FAILED 00238 /**< facilitates iteration over all values */ 00239 }; 00240 00241 enum iBase_ErrorType 00242 { 00243 iBase_ErrorType_MIN = 0, 00244 /**< facilitates iteration over all values */ 00245 iBase_SUCCESS = iBase_ErrorType_MIN, 00246 iBase_MESH_ALREADY_LOADED, 00247 iBase_FILE_NOT_FOUND, 00248 iBase_FILE_WRITE_ERROR, 00249 iBase_NIL_ARRAY, 00250 iBase_BAD_ARRAY_SIZE, 00251 iBase_BAD_ARRAY_DIMENSION, 00252 iBase_INVALID_ENTITY_HANDLE, 00253 iBase_INVALID_ENTITY_COUNT, 00254 iBase_INVALID_ENTITY_TYPE, 00255 iBase_INVALID_ENTITY_TOPOLOGY, 00256 iBase_BAD_TYPE_AND_TOPO, 00257 iBase_ENTITY_CREATION_ERROR, 00258 iBase_INVALID_TAG_HANDLE, 00259 iBase_TAG_NOT_FOUND, 00260 iBase_TAG_ALREADY_EXISTS, 00261 iBase_TAG_IN_USE, 00262 iBase_INVALID_ENTITYSET_HANDLE, 00263 iBase_INVALID_ITERATOR_HANDLE, 00264 iBase_INVALID_ARGUMENT, 00265 iBase_MEMORY_ALLOCATION_FAILED, 00266 iBase_NOT_SUPPORTED, 00267 iBase_FAILURE, 00268 iBase_ErrorType_MAX = iBase_FAILURE 00269 /**< facilitates iteration over all values */ 00270 }; 00271 00272 /***************************************************************************/ /** 00273 * \details 00274 * Many of the 00275 *functions in iMesh 00276 *can return arrays of 00277 *tuples; that is, 00278 *arrays of 00279 *multi-valued type. 00280 *For example, the 00281 *function 00282 *iMesh_getVtxArrCoords, 00283 * returns an array of 00284 *xyz coordinate 00285 *3-tuples (or, 00286 *perhaps for 00287 *geometrically 2D 00288 *meshes, xy 00289 *2-tuples). In these 00290 *situations, there 00291 *are multiple ways 00292 *the data can be 00293 *organized in memory. 00294 *For example, it 00295 *could be stored 00296 *xyz,xyz,xyz or 00297 *xxx...,yyy...,zzz.... 00298 *These two different 00299 *storage orders are 00300 *referred to as 00301 *INTERLEAVED and 00302 *BLOCKED, 00303 *respectively. For 00304 *some functions in 00305 *iMesh, the storage 00306 *order is explicitly 00307 *specified as an 00308 *argument to the 00309 *function. For other 00310 *functions, the 00311 *storage order is not 00312 *explicitly 00313 *specified. And, in 00314 *these cases, it 00315 *shall always be 00316 *implicitly assumed 00317 *to be INTERLEAVED. 00318 * This fact will be 00319 *mentioned in the 00320 *documentation for 00321 *each specific 00322 *function where it 00323 *applies. For 00324 *example, in case of 00325 *iMesh_getEntArrAdj, 00326 *the returned array 00327 *of adjacent entities 00328 *is multi-valued in 00329 *that it stores for 00330 *each entity queried, 00331 *all its adjacent 00332 *entities. Such an 00333 *array will be stored 00334 * INTERLEAVED with 00335 *all adjacent 00336 *entities for the 00337 *first entity in the 00338 *query followed by 00339 *all adjacent 00340 *entities for the 00341 *second entity in the 00342 *query and so forth. 00343 ******************************************************************************/ 00344 enum iBase_StorageOrder 00345 { 00346 iBase_StorageOrder_MIN = 0, 00347 /**< facilitates iteration over all values */ 00348 iBase_BLOCKED = iBase_StorageOrder_MIN, 00349 /**< xxx...yyy...zzz... */ 00350 iBase_INTERLEAVED, 00351 /**< xyzxyzxyz... */ 00352 iBase_StorageOrder_MAX = iBase_INTERLEAVED 00353 /**< facilitates iteration over all values */ 00354 }; 00355 00356 enum iBase_TagValueType 00357 { 00358 iBase_TagValueType_MIN = 0, 00359 /**< facilitates iteration over all values */ 00360 iBase_BYTES = iBase_TagValueType_MIN, 00361 /**< An opaque sequence of bytes, size always measured in bytes */ 00362 iBase_INTEGER, 00363 /**< A value of type \c int */ 00364 iBase_DOUBLE, 00365 /**< A value of type \c double */ 00366 iBase_ENTITY_HANDLE, 00367 /**< A value of type \c iBase_EntityHandle */ 00368 iBase_ENTITY_SET_HANDLE, 00369 /**< A value of type \c iBase_EntitySetHandle */ 00370 iBase_TagValueType_MAX = iBase_ENTITY_SET_HANDLE 00371 /**< facilitates iteration over all values */ 00372 }; 00373 00374 /***************************************************************************/ /** 00375 * \page ibase iBase: 00376 *ITAPS Base Interface 00377 ******************************************************************************/ 00378 00379 /***************************************************************************/ /** 00380 * \defgroup iBase 00381 *iBase 00382 ******************************************************************************/ 00383 00384 /***************************************************************************/ /** 00385 * \defgroup 00386 *VersionNumbers 00387 *Version Numbers 00388 * \ingroup iBase 00389 ******************************************************************************/ 00390 00391 /***************************************************************************/ /** 00392 * \defgroup 00393 *ErrorHandling Error 00394 *Handling \ingroup 00395 *iBase 00396 ******************************************************************************/ 00397 00398 /***************************************************************************/ /** 00399 * \defgroup Datatypes 00400 *Datatypes \ingroup 00401 *iBase 00402 ******************************************************************************/ 00403 00404 /***************************************************************************/ /** 00405 * \page The ITAPS Interfaces 00406 * 00407 * \subpage ibase 00408 * 00409 * \subpage imesh 00410 * 00411 * \subpage imeshp 00412 * 00413 * \subpage error 00414 * 00415 * \subpage trio 00416 * 00417 * \subpage strlen 00418 * 00419 * \subpage options 00420 * 00421 * \subpage numhops 00422 * 00423 * \subpage resilient 00424 * 00425 * \page error Error Handling 00426 * 00427 * With few exceptions, every iMesh function includes an output argument, 00428 * 'int *err', which returns an error code indicating if the function call 00429 * may have failed. If the value returned for the 'err' argument is NOT 00430 * iBase_SUCCESS, the caller should NOT attempt to interpret (read the 00431 * values in) any of the other return arguments of the call. While some 00432 * implementations may actually return valid/useful results in other 00433 * return arguments of a call that has failed, there is no guarentee that 00434 * ALL implementations will do similarly and so depending on such behavior 00435 * is neither portable nor safe. This is true even if the returned values 00436 * are different from the values of the arguments before the call was 00437 * made. 00438 * 00439 * \page trio Array pointer, allocated and occupied sizes argument trio 00440 * 00441 * Many of the functions in iMesh have arguments corresponding to lists of 00442 * objects. In-type arguments for lists consist of a pointer to an array and 00443 * a list size. Lists returned from functions are passed in three arguments, 00444 * a pointer to the array representing the list, and pointers to the 00445 * allocated and occupied lengths of the array. These three arguments are 00446 * inout-type arguments, because they can be allocated by the application and 00447 * passed into the interface to hold the results of the function. Lists 00448 * which are pre-allocated must be large enough to hold the results of the 00449 * function; if this is not the case, an error is generated. Otherwise, the 00450 * occupied size is changed to the size output from the function. If a list 00451 * argument is unallocated (the list pointer points to a NULL value) or if 00452 * the incoming value of the allocated size is zero, the list storage will be 00453 * allocated by the implementation. 00454 * 00455 * IN ALL CASES, MEMORY ALLOCATED BY ITAPS INTERFACE IMPLEMENTATIONS IS DONE 00456 * USING THE C MALLOC FUNCTION, AND MUST BE DE-ALLOCATED USING THE C FREE 00457 * FUNCTION. 00458 * 00459 * \page strlen String Length Arguments 00460 * 00461 * Many of the functions in iMesh involve passing a string and also the length 00462 * of that string. How is the null character is handled? 00463 * For users of the iMesh interface calling iMesh functions, it is optional 00464 * as to whether or not to include the null character in computing the length 00465 * of the string. So, for example, calling iMesh from a C program, users could 00466 * pass strlen(my_string) or strlen(my_string)+1 as the length of the string. 00467 * 00468 * <em>Note to implementors</em>: However, it should be noted that the situation 00469 * is different for implementers of the iMesh interface. In implementing an 00470 * iMesh interface function, there can be no assumption that the string is 00471 * indeed null terminated. The length argument the caller passes in may or may 00472 * NOT include the null character and implementations must be coded to 00473 * accommodate this. This requirement is primarily due to differences in how 00474 * Fortran and C/C++ handle passing of strings as function arguments. 00475 * Furthermore, because of the way Fortran clients pass strings (Fortran always 00476 * passes the length of the string as declared in the source code), there 00477 * may be trailing spaces in the string that need to be truncated. 00478 * 00479 * \page numhops Indirection in Set-Inclusion and Parent-Child structures 00480 * 00481 * Various functions to query entities, entity sets and parent or child sets 00482 * as well as the numbers of these involve a num_hops argument. If the set 00483 * upon which the query is originated is the root set, the num_hops argument 00484 * is irrelevant and is ignored by the implementation. Otherwise, the num_hops 00485 * argument represents the maximum number of levels of indirection employed in 00486 * satisfying the query not including the originating set. For example, using 00487 * value for num_hops of 0 (zero) in iMesh_getEntSets will return all the 00488 * entity sets that are immediately contained in a given set. Likewise, a 00489 * value for num_hops of 1 (one) will return all entity sets that are 00490 * immediately contained in the given set plus all entity sets that 00491 * are contained in those immediately contained sets (e.g. one level of 00492 * indirection). Using a value of -1 for num_hops will return results for 00493 * all possible levels of indirection. In other words, using a value of 00494 * -1 for num_hops is equivalent to setting the maximum number of levels 00495 * of indirection to infinity. 00496 * 00497 * \page options Option Strings 00498 * 00499 * A few of the functions in iMesh support arbitrary options passed as a 00500 * character string, called an 'Option String'. The format of and handling 00501 * of an Option String is as follows... 00502 * 00503 * 1. Option Strings are INsensitive to case. 00504 * 00505 * 2. Each option in an Option String is pre-pended with the implementation 00506 * name followed by a special character called the separator character. 00507 * 00508 * 3. The separator is a colon, ':'. 00509 * 00510 * 4. Multiple options existing in a single Option String are separated by a 00511 * special character called the delimiter character. 00512 * 00513 * 5. The delimiter character is a space, ' '. 00514 * 00515 * 6. The effect of multiple options in a single Option String is 00516 * INsensitive to order of occurrence in the string. 00517 * 00518 * 7. By default, implementations silently ignore any options that 00519 * do not match on the implementation name part (everything before 00520 * the separator character). This way, a caller may included options 00521 * in a single string intended for multiple different implementations. 00522 * 00523 * 8. Implementations may (or may not) warn or error for option strings 00524 * that match on implementation name part but are found to be in error 00525 * for other reasons the implementation decides. 00526 * 00527 * 9. Whenever either the separator character, ':', or delimiter character, 00528 * ' ', need to appear in an option, they must be escaped with the 00529 * backslash character, '\'. 00530 * 00531 * For example, consider the Options String 00532 * 00533 * "grummp:silant FMDB:TwoPhaseIO moab:mpiio_hints\ foo\:bar" 00534 * 00535 * In the above example, the space serves as the delimiter character 00536 * between multiple options in the string. The colon serves as the 00537 * implementation-name/option separator character. Because options are 00538 * required to be insensitive to case, the caller is free to use case as a 00539 * word separator as in 'TwoPhaseIO' and even in the implementation name, 00540 * as in 'FMDB:', although 'fmdb:twophaseio' and 'fmdb:TWOPHASEIO' would 00541 * all have the same effect. In the moab option, both the separator 00542 * character and delimiter character appear in the option and so are 00543 * pre-pended (e.g. escaped) with the backslash character. 00544 00545 * GRUMMP will silently ignore the FMDB: and moab: options because they do 00546 * NOT match on the implementation name part. However, GRUMMP may 00547 * optionally error out, or warn or silently ignore 'grummp:silant' (it was 00548 * supposed to be spelled 'silent') as an invalid option. 00549 * 00550 * Note that iMesh itself currently does not define any options. In order 00551 * to discover options a given implementation defines, users are directed 00552 * to the developers of the respective implementations. 00553 * 00554 * \page resilient Resilient and Non-Resilient Iterators 00555 * 00556 * A resilient iterator is one that can deal with modifications to the container 00557 * it is iterating over. 00558 * 00559 * A common concern about an iterator is how it behaves when the container 00560 * over which it is iterating is modified. For example, in STL, iterators 00561 * for std::set<> and std::map<> and std::list<> containers are guaranteed 00562 * to <em>work</em> in the presence of modifications to the associated 00563 * containers with one exception; they don't handle the case when the 00564 * container member the iterator is currently pointed at is deleted. However, 00565 * iterators for std::vector<> are not guaranteed to work under any kinds of 00566 * modification. 00567 * 00568 * In the ITAPS interfaces, a <em>resilient</em> iterator is one that makes 00569 * certain guarantees (described below) about how it behaves when the 00570 * container being iterated is modified. On the other hand, a 00571 * <em>non-resilient</em> is one that does not make such guarantees. 00572 * 00573 * In all cases, the <em>container</em> associated with an iterator in the 00574 * ITAPS interfaces is an entity set of some sort. This is the only container 00575 * type for which iterators are defined. 00576 * 00577 * Here, we characterize the behavior of iterators in the presence of 00578 * container modifications. There are a number of (subtle) aspects to 00579 * keep in mind. 00580 * 00581 * 1. There are set-type (<em>duplicate preventing</em>) sets and list-type 00582 * (<em>order preserving</em>) sets and iterators behave differently for each. 00583 * 00584 * 2. Sets can have <em>set</em> members and <em>entity</em> members. However, 00585 * iterators are currently defined to iterate over <em>only</em> the entity 00586 * members. That said, the question arises as to whether modifications that 00587 * involve only set members nonetheless <em>effect</em> iterator behavior. 00588 * 00589 * 3. There are array-type iterators that upon each step in the iteration 00590 * return a whole array of entity member handles and single entity iterators 00591 * that upon each step return just a single entity member handle. 00592 * 00593 * 4. The iterators support type/topology <em>filtering</em>. Iterators do not 00594 * (always) strictly iterate over <em>all</em> entities in a set; just 00595 * <em>all</em> entities matching the type/topology criteria. When 00596 * type/topology specifies either all types or all topologies, then indeed 00597 * the iterator will iterate over all entities. 00598 * 00599 * 5. There are add/remove operations that add/remove <em>entity members</em> or 00600 * <em>set members</em> to a set. 00601 * 00602 * 6. There are create/delete operations that create and delete 00603 * <em>entities</em> from the whole iMesh_Instance. 00604 * 00605 * 7. There are create/destroy operations that create and destroy 00606 * <em>sets</em> from the whole interface instance. 00607 * 00608 * 8. There is the <em>root set</em> which is special and may have different 00609 * iterator behavior than all other sets. By definition, the root set is a set-type 00610 * (<em>duplicate prevent</em>) set. 00611 * 00612 * Modification means addition/removal and/or create/destroy and/or create/delete 00613 * <em>after</em> iterator initialization. When we talk about 00614 * <em>container modification</em> here, we are talking about any of the 00615 * following operations. 00616 * 00617 * A. addition and removal of entity members 00618 * \code 00619 * void iMesh_rmvEntFromSet(iMesh_Instance instance, 00620 * void iMesh_rmvEntArrFromSet(iMesh_Instance instance, 00621 * void iMesh_addEntToSet(iMesh_Instance instance, 00622 * void iMesh_addEntArrToSet(iMesh_Instance instance, 00623 * \endcode 00624 * B. addition and removal of set members 00625 * \code 00626 * void iMesh_rmvEntSet(iMesh_Instance instance, 00627 * void iMesh_addEntSet(iMesh_Instance instance, 00628 * \endcode 00629 * C. deletion of entities from whole iMesh_Instance 00630 * \code 00631 * void iMesh_deleteEntArr(iMesh_Instance instance, 00632 * void iMesh_deleteEnt(iMesh_Instance instance, 00633 * \endcode 00634 * D. creation of entities (effects root set) 00635 * \code 00636 * void iMesh_createEntSet(iMesh_Instance instance, 00637 * void iMesh_createVtxArr(iMesh_Instance instance, 00638 * void iMesh_createEntArr(iMesh_Instance instance, 00639 * void iMesh_createVtx(iMesh_Instance instance, 00640 * void iMesh_createEnt(iMesh_Instance instance, 00641 * \endcode 00642 * E. destruction of entity sets 00643 * \code 00644 * void iMesh_destroyEntSet(iMesh_Instance instance, 00645 * \endcode 00646 00647 * By container modification, we mean that of the above operations occur on 00648 * the container between iterator initialization and reset. 00649 * 00650 * For purposes of this discussion, there is no distinction between any of 00651 * these <em>kinds of</em> modifications. What is true for any is true for 00652 * all. Below, the words <em>add</em> and <em>remove</em> are used to 00653 * represent any of the modifications that add members or remove members 00654 * regardless of the <em>kind of operation</em> above. 00655 * 00656 * Resilient iterators are not effected by modifications involving set members: 00657 * 00658 * Iterators are currently defined to iterate over *only* the entity members 00659 * of a container. In particular, if the container is modified by 00660 * adding/removing sets from the container, this will have no impact on 00661 * the iterator. This is true for set-type sets and list-type sets. 00662 * 00663 * Resilient iterator's <em>current position</em> not effected by modification: 00664 * 00665 * If the container is modified, the iterator will continue to properly 00666 * <em>keep track of</em> the member it was currently pointing at. If a 00667 * modification occurs that removes the member it was currently pointing at, 00668 * the iterator will be advanced to the <em>next</em> (not already deleted) 00669 * member it would have proceeded to. In this way, the iterator is guaranteed 00670 * to always point at a valid member or to the end of the set, in the case 00671 * that the member being removed is the last one. 00672 * 00673 * A resilient iterator must skip over removed members: 00674 * 00675 * If the container is modified by removing members, the iterator will guarantee 00676 * not to <em>land on</em> (e.g. return) those members as iteration proceeds. 00677 * This is true of set-type sets and list-type sets. 00678 * 00679 * A resilient iterator on set-type sets <em>may</em> fail to return added members: 00680 * 00681 * If the container is a set-type (<em>duplicate preventing</em>) container and 00682 * it is modified by adding members, the iterator <em>may</em> skip over (e.g. 00683 * fail to return) members that have been added. In other words, there is no 00684 * guarantee in this circumstance that an iterator will return added members. 00685 * 00686 * A resilient iterator on list-type sets <em>must</em> return added members. 00687 * If it is a list-type (<em>order preserving</em>) container, then the iterator 00688 * <em>must</em> guarantee to return the added members. 00689 * 00690 * A non-resilient iterator may or may not behave like a resilient iterator in 00691 * some or all of the circumstances described above. There are no guarantees 00692 * about how a non-resilient iterator will behave. The behavior of a non-resilient 00693 * iterator in the presence of container modifications is left entirely up 00694 * to the implementation. 00695 * 00696 * If upon initializing an iterator, an application requests it be resilient and 00697 * the implementation is unable to support that, the iterator initialization 00698 * request shall fail and return error iBase_NOT_SUPPORTED. 00699 ******************************************************************************/ 00700 00701 #ifdef __cplusplus 00702 } 00703 #endif 00704 00705 #endif /* #ifndef _ITAPS_iBase */
1.7.6.1 
