Mesh Oriented datABase  (version 5.4.1)
Array-based unstructured mesh datastructure
VarLenSparseTag.hpp
Go to the documentation of this file.
00001 /**
00002  * MOAB, a Mesh-Oriented datABase, is a software component for creating,
00003  * storing and accessing finite element mesh data.
00004  *
00005  * Copyright 2004 Sandia Corporation.  Under the terms of Contract
00006  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
00007  * retains certain rights in this software.
00008  *
00009  * This library is free software; you can redistribute it and/or
00010  * modify it under the terms of the GNU Lesser General Public
00011  * License as published by the Free Software Foundation; either
00012  * version 2.1 of the License, or (at your option) any later version.
00013  *
00014  */
00015 
00016 #ifndef VAR_LEN_SPARSE_TAG_HPP
00017 #define VAR_LEN_SPARSE_TAG_HPP
00018 
00019 #ifndef IS_BUILDING_MB
00020 #error "VarLenSparseTag.hpp isn't supposed to be included into an application"
00021 #endif
00022 
00023 #ifdef WIN32
00024 #pragma warning( disable : 4786 )
00025 #endif
00026 
00027 #include "moab/MOABConfig.h"
00028 #define STRINGIFY_( X ) #X
00029 #define STRINGIFY( X )  STRINGIFY_( X )
00030 #ifdef MOAB_HAVE_UNORDERED_MAP
00031 #include STRINGIFY( MOAB_HAVE_UNORDERED_MAP )
00032 #else
00033 #include <map>
00034 #endif
00035 #include <vector>
00036 
00037 #include "TagInfo.hpp"
00038 #include "VarLenTag.hpp"
00039 #include <cstdlib>
00040 
00041 namespace moab
00042 {
00043 
00044 //! Sparse tag variable-length data
00045 class VarLenSparseTag : public TagInfo
00046 {
00047   public:
00048     VarLenSparseTag( const char* name, DataType type, const void* default_value, int default_value_bytes );
00049 
00050     ~VarLenSparseTag();
00051 
00052     virtual TagType get_storage_type() const;
00053 
00054     /**\brief Remove/clear tag data for all entities
00055      *
00056      * Remove tag values from entities.
00057      *
00058      *\param delete_pending  If true, then release any global
00059      *          data associated with the tag in preparation for deleting
00060      *          the tag itself.
00061      *
00062      *\Note Invalidates tag if \c tag_delete_pending is true.  The only
00063      *        valid method that can be invoked that is is the destructor.
00064      *
00065      *\param seqman    Pointer to mesh entity database
00066      */
00067     virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool delete_pending );
00068 
00069     /**\brief Get tag value for passed entities
00070      *
00071      * Get tag values for specified entities.
00072      *
00073      *\Note Will fail for variable-length data.
00074      *\param seqman Pointer to mesh entity database
00075      *\param entities Entity handles for which to retrieve tag data
00076      *\param num_entities Length of \c entities array
00077      *\param data Pointer to memory in which to store consecutive tag values,
00078      *            one for each passed entity.
00079      */
00080     virtual ErrorCode get_data( const SequenceManager* seqman,
00081                                 Error* error_handler,
00082                                 const EntityHandle* entities,
00083                                 size_t num_entities,
00084                                 void* data ) const;
00085 
00086     /**\brief Get tag value for passed entities
00087      *
00088      * Get tag values for specified entities.
00089      *
00090      *\Note Will fail for variable-length data.
00091      *\param seqman Pointer to mesh entity database
00092      *\param entities Entity handles for which to retrieve tag data
00093      *\param data Pointer to memory in which to store consecutive tag values,
00094      *            one for each passed entity.
00095      */
00096     virtual ErrorCode get_data( const SequenceManager* seqman,
00097                                 Error* error_handler,
00098                                 const Range& entities,
00099                                 void* data ) const;
00100 
00101     /**\brief Get tag value for passed entities
00102      *
00103      * Get tag values for specified entities.
00104      *
00105      *\param seqman    Pointer to mesh entity database
00106      *\param entities  Entity handles for which to retrieve tag data
00107      *\param num_entities Length of \c entities array
00108      *\param data_ptrs Array of pointers to tag values, one pointer
00109      *                 for each passed entity.
00110      *\param data_lengths One value for each entity specifying the
00111      *                length of the tag value for the corresponding
00112      *                entity.
00113      */
00114     virtual ErrorCode get_data( const SequenceManager* seqman,
00115                                 Error* error_handler,
00116                                 const EntityHandle* entities,
00117                                 size_t num_entities,
00118                                 const void** data_ptrs,
00119                                 int* data_lengths ) const;
00120 
00121     /**\brief Get tag value for passed entities
00122      *
00123      * Get tag values for specified entities.
00124      *
00125      *\param seqman    Pointer to mesh entity database
00126      *\param entities  Entity handles for which to retrieve tag data
00127      *\param data_ptrs Array of pointers to tag values, one pointer
00128      *                 for each passed entity.
00129      *\param data_lengths One value for each entity specifying the
00130      *                length of the tag value for the corresponding
00131      *                entity.
00132      */
00133     virtual ErrorCode get_data( const SequenceManager* seqman,
00134                                 Error* error_handler,
00135                                 const Range& entities,
00136                                 const void** data_ptrs,
00137                                 int* data_lengths ) const;
00138 
00139     /**\brief Set tag value for passed entities
00140      *
00141      * Store tag data or update stored tag values
00142      *\Note Will fail for variable-length data.
00143      *\param seqman Pointer to mesh entity database
00144      *\param entities Entity handles for which to store tag data
00145      *\param num_entities Length of \c entities array
00146      *\param data Pointer to memory holding consecutive tag values,
00147      *            one for each passed entity.
00148      */
00149     virtual ErrorCode set_data( SequenceManager* seqman,
00150                                 Error* error_handler,
00151                                 const EntityHandle* entities,
00152                                 size_t num_entities,
00153                                 const void* data );
00154 
00155     /**\brief Set tag value for passed entities
00156      *
00157      * Store tag data or update stored tag values
00158      *\Note Will fail for variable-length data.
00159      *\param seqman Pointer to mesh entity database
00160      *\param entities Entity handles for which to store tag data
00161      *\param data Pointer to memory holding consecutive tag values,
00162      *            one for each passed entity.
00163      */
00164     virtual ErrorCode set_data( SequenceManager* seqman,
00165                                 Error* error_handler,
00166                                 const Range& entities,
00167                                 const void* data );
00168 
00169     /**\brief Set tag value for passed entities
00170      *
00171      * Store tag data or update stored tag values
00172      *
00173      *\param seqman    Pointer to mesh entity database
00174      *\param entities  Entity handles for which to store tag data
00175      *\param num_entities Length of \c entities array
00176      *\param data_ptrs Array of pointers to tag values, one pointer
00177      *                 for each passed entity.
00178      *\param data_lengths One value for each entity specifying the
00179      *                length of the tag value for the corresponding
00180      *                entity.  Array is required for variable-length
00181      *                tags and is ignored for fixed-length tags.
00182      */
00183     virtual ErrorCode set_data( SequenceManager* seqman,
00184                                 Error* error_handler,
00185                                 const EntityHandle* entities,
00186                                 size_t num_entities,
00187                                 void const* const* data_ptrs,
00188                                 const int* data_lengths );
00189 
00190     /**\brief Set tag value for passed entities
00191      *
00192      * Store tag data or update stored tag values
00193      *
00194      *\param seqman    Pointer to mesh entity database
00195      *\param entities  Entity handles for which to store tag data
00196      *\param data_ptrs Array of pointers to tag values, one pointer
00197      *                 for each passed entity.
00198      *\param data_lengths One value for each entity specifying the
00199      *                length of the tag value for the corresponding
00200      *                entity.  Array is required for variable-length
00201      *                tags and is ignored for fixed-length tags.
00202      */
00203     virtual ErrorCode set_data( SequenceManager* seqman,
00204                                 Error* error_handler,
00205                                 const Range& entities,
00206                                 void const* const* data_ptrs,
00207                                 const int* data_lengths );
00208 
00209     /**\brief Set tag value for passed entities
00210      *
00211      * Store tag data or update stored tag values.
00212      *
00213      *\param seqman    Pointer to mesh entity database
00214      *\param entities  Entity handles for which to store tag data
00215      *\param num_entities Length of \c entities array
00216      *\param value_ptr Pointer to a single tag value which is to be
00217      *                 stored for each of the passed entities.
00218      *\param value_len Length of tag value in bytes.  Ignored for
00219      *                 fixed-length tags.  Required for variable-
00220      *                 length tags.
00221      */
00222     virtual ErrorCode clear_data( SequenceManager* seqman,
00223                                   Error* error_handler,
00224                                   const EntityHandle* entities,
00225                                   size_t num_entities,
00226                                   const void* value_ptr,
00227                                   int value_len = 0 );
00228 
00229     /**\brief Set tag value for passed entities
00230      *
00231      * Store tag data or update stored tag values.
00232      *
00233      *\param seqman    Pointer to mesh entity database
00234      *\param entities  Entity handles for which to store tag data
00235      *\param value_ptr Pointer to a single tag value which is to be
00236      *                 stored for each of the passed entities.
00237      *\param value_len Length of tag value in bytes.  Ignored for
00238      *                 fixed-length tags.  Required for variable-
00239      *                 length tags.
00240      */
00241     virtual ErrorCode clear_data( SequenceManager* seqman,
00242                                   Error* error_handler,
00243                                   const Range& entities,
00244                                   const void* value_ptr,
00245                                   int value_len = 0 );
00246 
00247     /**\brief Remove/clear tag data for entities
00248      *
00249      * Remove tag values from entities.
00250      *
00251      *\param seqman    Pointer to mesh entity database
00252      *\param entities  Entity handles for which to store tag data
00253      *\param num_entities Length of \c entities array
00254      */
00255     virtual ErrorCode remove_data( SequenceManager* seqman,
00256                                    Error* error_handler,
00257                                    const EntityHandle* entities,
00258                                    size_t num_entities );
00259 
00260     /**\brief Remove/clear tag data for entities
00261      *
00262      * Remove tag values from entities.
00263      *
00264      *\param seqman    Pointer to mesh entity database
00265      *\param entities  Entity handles for which to store tag data
00266      */
00267     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );
00268 
00269     /**\brief Access tag data via direct pointer into contiguous blocks
00270      *
00271      * Iteratively obtain direct access to contiguous blocks of tag
00272      * storage.  This function cannot be used with bit tags because
00273      * of the compressed bit storage.  This function cannot be used
00274      * with variable length tags because it does not provide a mechanism
00275      * to determine the length of the value for each entity.  This
00276      * function may be used with sparse tags, but if it is used, it
00277      * will return data for a single entity at a time.
00278      *
00279      *\param iter        As input, the first entity for which to return
00280      *                   data.  As output, one past the last entity for
00281      *                   which data was returned.
00282      *\param end         One past the last entity for which data is desired
00283      *\param data_ptr    Output: pointer to tag storage.
00284      *
00285      *\Note If this function is called for entities for which no tag value
00286      *      has been set, but for which a default value exists, it will
00287      *      force the allocation of explicit storage for each such entity
00288      *      even though MOAB would normally not explicitly store tag values
00289      *      for such entities.
00290      */
00291     virtual ErrorCode tag_iterate( SequenceManager* seqman,
00292                                    Error* error_handler,
00293                                    Range::iterator& iter,
00294                                    const Range::iterator& end,
00295                                    void*& data_ptr,
00296                                    bool allocate = true );
00297 
00298     /**\brief Get all tagged entities
00299      *
00300      * Get the list of entities for which the a tag value has been set,
00301      * or a close approximation if the tag storage scheme cannot
00302      * accurately determine exactly which entities have explicit values.
00303      *
00304      *\param seqman   Pointer to entity storage database
00305      *\param output_entities Results *appended* to this range
00306      *\param type     Optional entity type.  If specified, search is
00307      *                limited to entities of specified type.
00308      *\param intersect Optional intersect list.  If specified,
00309      *                search is restricted to entities in this list.
00310      */
00311     virtual ErrorCode get_tagged_entities( const SequenceManager* seqman,
00312                                            Range& output_entities,
00313                                            EntityType type        = MBMAXTYPE,
00314                                            const Range* intersect = 0 ) const;
00315 
00316     /**\brief Count all tagged entities
00317      *
00318      * Count the entities for which the a tag value has been set,
00319      * or a close approximation if the tag storage scheme cannot
00320      * accurately determine exactly which entities have explicit values.
00321      *
00322      *\param seqman   Pointer to entity storage database
00323      *\param output_count This is *incremented* for each detected entity.
00324      *\param type     Optional entity type.  If specified, search is
00325      *                limited to entities of specified type.
00326      *\param intersect Optional intersect list.  If specified,
00327      *                search is restricted to entities in this list.
00328      */
00329     virtual ErrorCode num_tagged_entities( const SequenceManager* seqman,
00330                                            size_t& output_count,
00331                                            EntityType type        = MBMAXTYPE,
00332                                            const Range* intersect = 0 ) const;
00333 
00334     /**\brief Get all tagged entities with tag value
00335      *
00336      * Get the list of entities which have the specified tag value.
00337      *
00338      *\param seqman   Pointer to entity storage database
00339      *\param output_entities Results *appended* to this range
00340      *\param value    Pointer to tag value
00341      *\param value_bytes Size of tag value in bytes.
00342      *\param type     Optional entity type.  If specified, search is
00343      *                limited to entities of specified type.
00344      *\param intersect_entities Optional intersect list.  If specified,
00345      *                search is restricted to entities in this list.
00346      */
00347     virtual ErrorCode find_entities_with_value( const SequenceManager* seqman,
00348                                                 Error* error_handler,
00349                                                 Range& output_entities,
00350                                                 const void* value,
00351                                                 int value_bytes                 = 0,
00352                                                 EntityType type                 = MBMAXTYPE,
00353                                                 const Range* intersect_entities = 0 ) const;
00354 
00355     /**\brief Check if entity is tagged */
00356     virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;
00357 
00358     /**\brief Get memory use for tag data.
00359      *
00360      */
00361     virtual ErrorCode get_memory_use( const SequenceManager* seqman,
00362                                       unsigned long& total,
00363                                       unsigned long& per_entity ) const;
00364 
00365     //! get number of entities
00366     unsigned long get_number_entities()
00367     {
00368         return mData.size();
00369     }
00370 
00371     //! map of entity id and tag data
00372 #ifdef MOAB_HAVE_UNORDERED_MAP
00373     typedef MOAB_UNORDERED_MAP_NS::unordered_map< EntityHandle, VarLenTag > MapType;
00374 #else
00375     typedef std::map< EntityHandle, VarLenTag > MapType;
00376 #endif
00377 
00378   private:
00379     VarLenSparseTag( const VarLenSparseTag& );
00380     VarLenSparseTag& operator=( const VarLenSparseTag& );
00381 
00382     //! get the variable-length data for an entity id
00383     inline ErrorCode get_data_ptr( Error* error_handler,
00384                                    EntityHandle entity_handle,
00385                                    const void*& data,
00386                                    int& size ) const;
00387 
00388     MapType mData;
00389 };
00390 
00391 }  // namespace moab
00392 
00393 #endif  // VAR_LEN_SPARSE_TAG_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines