Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
VarLenSparseTag.hpp
Go to the documentation of this file.
1 /**
2  * MOAB, a Mesh-Oriented datABase, is a software component for creating,
3  * storing and accessing finite element mesh data.
4  *
5  * Copyright 2004 Sandia Corporation. Under the terms of Contract
6  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
7  * retains certain rights in this software.
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public
11  * License as published by the Free Software Foundation; either
12  * version 2.1 of the License, or (at your option) any later version.
13  *
14  */
15 
16 #ifndef VAR_LEN_SPARSE_TAG_HPP
17 #define VAR_LEN_SPARSE_TAG_HPP
18 
19 #ifndef IS_BUILDING_MB
20 #error "VarLenSparseTag.hpp isn't supposed to be included into an application"
21 #endif
22 
23 #ifdef WIN32
24 #pragma warning( disable : 4786 )
25 #endif
26 
27 #include "moab/MOABConfig.h"
28 #define STRINGIFY_( X ) #X
29 #define STRINGIFY( X ) STRINGIFY_( X )
30 #ifdef MOAB_HAVE_UNORDERED_MAP
31 #include STRINGIFY( MOAB_HAVE_UNORDERED_MAP )
32 #else
33 #include <map>
34 #endif
35 #include <vector>
36 
37 #include "TagInfo.hpp"
38 #include "VarLenTag.hpp"
39 #include <cstdlib>
40 
41 namespace moab
42 {
43 
44 //! Sparse tag variable-length data
45 class VarLenSparseTag : public TagInfo
46 {
47  public:
48  VarLenSparseTag( const char* name, DataType type, const void* default_value, int default_value_bytes );
49 
50  ~VarLenSparseTag();
51 
52  virtual TagType get_storage_type() const;
53 
54  /**\brief Remove/clear tag data for all entities
55  *
56  * Remove tag values from entities.
57  *
58  *\param delete_pending If true, then release any global
59  * data associated with the tag in preparation for deleting
60  * the tag itself.
61  *
62  *\Note Invalidates tag if \c tag_delete_pending is true. The only
63  * valid method that can be invoked that is is the destructor.
64  *
65  *\param seqman Pointer to mesh entity database
66  */
67  virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool delete_pending );
68 
69  /**\brief Get tag value for passed entities
70  *
71  * Get tag values for specified entities.
72  *
73  *\Note Will fail for variable-length data.
74  *\param seqman Pointer to mesh entity database
75  *\param entities Entity handles for which to retrieve tag data
76  *\param num_entities Length of \c entities array
77  *\param data Pointer to memory in which to store consecutive tag values,
78  * one for each passed entity.
79  */
80  virtual ErrorCode get_data( const SequenceManager* seqman,
81  Error* error_handler,
82  const EntityHandle* entities,
83  size_t num_entities,
84  void* data ) const;
85 
86  /**\brief Get tag value for passed entities
87  *
88  * Get tag values for specified entities.
89  *
90  *\Note Will fail for variable-length data.
91  *\param seqman Pointer to mesh entity database
92  *\param entities Entity handles for which to retrieve tag data
93  *\param data Pointer to memory in which to store consecutive tag values,
94  * one for each passed entity.
95  */
96  virtual ErrorCode get_data( const SequenceManager* seqman,
97  Error* error_handler,
98  const Range& entities,
99  void* data ) const;
100 
101  /**\brief Get tag value for passed entities
102  *
103  * Get tag values for specified entities.
104  *
105  *\param seqman Pointer to mesh entity database
106  *\param entities Entity handles for which to retrieve tag data
107  *\param num_entities Length of \c entities array
108  *\param data_ptrs Array of pointers to tag values, one pointer
109  * for each passed entity.
110  *\param data_lengths One value for each entity specifying the
111  * length of the tag value for the corresponding
112  * entity.
113  */
114  virtual ErrorCode get_data( const SequenceManager* seqman,
115  Error* error_handler,
116  const EntityHandle* entities,
117  size_t num_entities,
118  const void** data_ptrs,
119  int* data_lengths ) const;
120 
121  /**\brief Get tag value for passed entities
122  *
123  * Get tag values for specified entities.
124  *
125  *\param seqman Pointer to mesh entity database
126  *\param entities Entity handles for which to retrieve tag data
127  *\param data_ptrs Array of pointers to tag values, one pointer
128  * for each passed entity.
129  *\param data_lengths One value for each entity specifying the
130  * length of the tag value for the corresponding
131  * entity.
132  */
133  virtual ErrorCode get_data( const SequenceManager* seqman,
134  Error* error_handler,
135  const Range& entities,
136  const void** data_ptrs,
137  int* data_lengths ) const;
138 
139  /**\brief Set tag value for passed entities
140  *
141  * Store tag data or update stored tag values
142  *\Note Will fail for variable-length data.
143  *\param seqman Pointer to mesh entity database
144  *\param entities Entity handles for which to store tag data
145  *\param num_entities Length of \c entities array
146  *\param data Pointer to memory holding consecutive tag values,
147  * one for each passed entity.
148  */
149  virtual ErrorCode set_data( SequenceManager* seqman,
150  Error* error_handler,
151  const EntityHandle* entities,
152  size_t num_entities,
153  const void* data );
154 
155  /**\brief Set tag value for passed entities
156  *
157  * Store tag data or update stored tag values
158  *\Note Will fail for variable-length data.
159  *\param seqman Pointer to mesh entity database
160  *\param entities Entity handles for which to store tag data
161  *\param data Pointer to memory holding consecutive tag values,
162  * one for each passed entity.
163  */
164  virtual ErrorCode set_data( SequenceManager* seqman,
165  Error* error_handler,
166  const Range& entities,
167  const void* data );
168 
169  /**\brief Set tag value for passed entities
170  *
171  * Store tag data or update stored tag values
172  *
173  *\param seqman Pointer to mesh entity database
174  *\param entities Entity handles for which to store tag data
175  *\param num_entities Length of \c entities array
176  *\param data_ptrs Array of pointers to tag values, one pointer
177  * for each passed entity.
178  *\param data_lengths One value for each entity specifying the
179  * length of the tag value for the corresponding
180  * entity. Array is required for variable-length
181  * tags and is ignored for fixed-length tags.
182  */
183  virtual ErrorCode set_data( SequenceManager* seqman,
184  Error* error_handler,
185  const EntityHandle* entities,
186  size_t num_entities,
187  void const* const* data_ptrs,
188  const int* data_lengths );
189 
190  /**\brief Set tag value for passed entities
191  *
192  * Store tag data or update stored tag values
193  *
194  *\param seqman Pointer to mesh entity database
195  *\param entities Entity handles for which to store tag data
196  *\param data_ptrs Array of pointers to tag values, one pointer
197  * for each passed entity.
198  *\param data_lengths One value for each entity specifying the
199  * length of the tag value for the corresponding
200  * entity. Array is required for variable-length
201  * tags and is ignored for fixed-length tags.
202  */
203  virtual ErrorCode set_data( SequenceManager* seqman,
204  Error* error_handler,
205  const Range& entities,
206  void const* const* data_ptrs,
207  const int* data_lengths );
208 
209  /**\brief Set tag value for passed entities
210  *
211  * Store tag data or update stored tag values.
212  *
213  *\param seqman Pointer to mesh entity database
214  *\param entities Entity handles for which to store tag data
215  *\param num_entities Length of \c entities array
216  *\param value_ptr Pointer to a single tag value which is to be
217  * stored for each of the passed entities.
218  *\param value_len Length of tag value in bytes. Ignored for
219  * fixed-length tags. Required for variable-
220  * length tags.
221  */
222  virtual ErrorCode clear_data( SequenceManager* seqman,
223  Error* error_handler,
224  const EntityHandle* entities,
225  size_t num_entities,
226  const void* value_ptr,
227  int value_len = 0 );
228 
229  /**\brief Set tag value for passed entities
230  *
231  * Store tag data or update stored tag values.
232  *
233  *\param seqman Pointer to mesh entity database
234  *\param entities Entity handles for which to store tag data
235  *\param value_ptr Pointer to a single tag value which is to be
236  * stored for each of the passed entities.
237  *\param value_len Length of tag value in bytes. Ignored for
238  * fixed-length tags. Required for variable-
239  * length tags.
240  */
241  virtual ErrorCode clear_data( SequenceManager* seqman,
242  Error* error_handler,
243  const Range& entities,
244  const void* value_ptr,
245  int value_len = 0 );
246 
247  /**\brief Remove/clear tag data for entities
248  *
249  * Remove tag values from entities.
250  *
251  *\param seqman Pointer to mesh entity database
252  *\param entities Entity handles for which to store tag data
253  *\param num_entities Length of \c entities array
254  */
255  virtual ErrorCode remove_data( SequenceManager* seqman,
256  Error* error_handler,
257  const EntityHandle* entities,
258  size_t num_entities );
259 
260  /**\brief Remove/clear tag data for entities
261  *
262  * Remove tag values from entities.
263  *
264  *\param seqman Pointer to mesh entity database
265  *\param entities Entity handles for which to store tag data
266  */
267  virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );
268 
269  /**\brief Access tag data via direct pointer into contiguous blocks
270  *
271  * Iteratively obtain direct access to contiguous blocks of tag
272  * storage. This function cannot be used with bit tags because
273  * of the compressed bit storage. This function cannot be used
274  * with variable length tags because it does not provide a mechanism
275  * to determine the length of the value for each entity. This
276  * function may be used with sparse tags, but if it is used, it
277  * will return data for a single entity at a time.
278  *
279  *\param iter As input, the first entity for which to return
280  * data. As output, one past the last entity for
281  * which data was returned.
282  *\param end One past the last entity for which data is desired
283  *\param data_ptr Output: pointer to tag storage.
284  *
285  *\Note If this function is called for entities for which no tag value
286  * has been set, but for which a default value exists, it will
287  * force the allocation of explicit storage for each such entity
288  * even though MOAB would normally not explicitly store tag values
289  * for such entities.
290  */
291  virtual ErrorCode tag_iterate( SequenceManager* seqman,
292  Error* error_handler,
293  Range::iterator& iter,
294  const Range::iterator& end,
295  void*& data_ptr,
296  bool allocate = true );
297 
298  /**\brief Get all tagged entities
299  *
300  * Get the list of entities for which the a tag value has been set,
301  * or a close approximation if the tag storage scheme cannot
302  * accurately determine exactly which entities have explicit values.
303  *
304  *\param seqman Pointer to entity storage database
305  *\param output_entities Results *appended* to this range
306  *\param type Optional entity type. If specified, search is
307  * limited to entities of specified type.
308  *\param intersect Optional intersect list. If specified,
309  * search is restricted to entities in this list.
310  */
311  virtual ErrorCode get_tagged_entities( const SequenceManager* seqman,
312  Range& output_entities,
313  EntityType type = MBMAXTYPE,
314  const Range* intersect = 0 ) const;
315 
316  /**\brief Count all tagged entities
317  *
318  * Count the entities for which the a tag value has been set,
319  * or a close approximation if the tag storage scheme cannot
320  * accurately determine exactly which entities have explicit values.
321  *
322  *\param seqman Pointer to entity storage database
323  *\param output_count This is *incremented* for each detected entity.
324  *\param type Optional entity type. If specified, search is
325  * limited to entities of specified type.
326  *\param intersect Optional intersect list. If specified,
327  * search is restricted to entities in this list.
328  */
329  virtual ErrorCode num_tagged_entities( const SequenceManager* seqman,
330  size_t& output_count,
331  EntityType type = MBMAXTYPE,
332  const Range* intersect = 0 ) const;
333 
334  /**\brief Get all tagged entities with tag value
335  *
336  * Get the list of entities which have the specified tag value.
337  *
338  *\param seqman Pointer to entity storage database
339  *\param output_entities Results *appended* to this range
340  *\param value Pointer to tag value
341  *\param value_bytes Size of tag value in bytes.
342  *\param type Optional entity type. If specified, search is
343  * limited to entities of specified type.
344  *\param intersect_entities Optional intersect list. If specified,
345  * search is restricted to entities in this list.
346  */
347  virtual ErrorCode find_entities_with_value( const SequenceManager* seqman,
348  Error* error_handler,
349  Range& output_entities,
350  const void* value,
351  int value_bytes = 0,
352  EntityType type = MBMAXTYPE,
353  const Range* intersect_entities = 0 ) const;
354 
355  /**\brief Check if entity is tagged */
356  virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;
357 
358  /**\brief Get memory use for tag data.
359  *
360  */
361  virtual ErrorCode get_memory_use( const SequenceManager* seqman,
362  unsigned long& total,
363  unsigned long& per_entity ) const;
364 
365  //! get number of entities
366  unsigned long get_number_entities()
367  {
368  return mData.size();
369  }
370 
371  //! map of entity id and tag data
372 #ifdef MOAB_HAVE_UNORDERED_MAP
373  typedef MOAB_UNORDERED_MAP_NS::unordered_map< EntityHandle, VarLenTag > MapType;
374 #else
375  typedef std::map< EntityHandle, VarLenTag > MapType;
376 #endif
377 
378  private:
379  VarLenSparseTag( const VarLenSparseTag& );
380  VarLenSparseTag& operator=( const VarLenSparseTag& );
381 
382  //! get the variable-length data for an entity id
383  inline ErrorCode get_data_ptr( Error* error_handler,
384  EntityHandle entity_handle,
385  const void*& data,
386  int& size ) const;
387 
388  MapType mData;
389 };
390 
391 } // namespace moab
392 
393 #endif // VAR_LEN_SPARSE_TAG_HPP