Mesh Oriented datABase  (version 5.4.1)
Array-based unstructured mesh datastructure
iBase.h
Go to the documentation of this file.
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 */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines