Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
DenseTag.hpp
Go to the documentation of this file.
1 /** \file DenseTag.hpp
2  * \author Jason Kraftcheck
3  * \date 2010-12-14
4  */
5 
6 #ifndef DENSE_TAG_HPP
7 #define DENSE_TAG_HPP
8 
9 #include "TagInfo.hpp"
10 
11 namespace moab
12 {
13 
14 class EntitySequence;
15 
16 /**\brief Dense storage of fixed-length tag data
17  *
18  * Implement normal dense tag.
19  */
20 class DenseTag : public TagInfo
21 {
22  private:
23  int mySequenceArray; //!< Array index in SequenceManager used to store tag data.
24 
25  unsigned char* meshValue;
26 
27  DenseTag( int array_index, const char* name, int size, DataType type, const void* default_value );
28 
29  public:
30  static DenseTag* create_tag( SequenceManager* seqman,
31  Error* error,
32  const char* name,
33  int bytes,
34  DataType type,
35  const void* default_value );
36 
37  virtual ~DenseTag();
38 
39  virtual TagType get_storage_type() const;
40 
41  /**\brief Remove/clear tag data for all entities
42  *
43  * Remove tag values from entities.
44  *
45  *\param delete_pending If true, then release any global
46  * data associated with the tag in preparation for deleting
47  * the tag itself.
48  *
49  *\Note Invalidates tag if \c tag_delete_pending is true. The only
50  * valid method that can be invoked that is is the destructor.
51  *
52  *\param seqman Pointer to mesh entity database
53  */
54  virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool delete_pending );
55 
56  /**\brief Get tag value for passed entities
57  *
58  * Get tag values for specified entities.
59  *
60  *\Note Will fail for variable-length data.
61  *\param seqman Pointer to mesh entity database
62  *\param entities Entity handles for which to retrieve tag data
63  *\param num_entities Length of \c entities array
64  *\param data Pointer to memory in which to store consecutive tag values,
65  * one for each passed entity.
66  */
67  virtual ErrorCode get_data( const SequenceManager* seqman,
68  Error* error_handler,
69  const EntityHandle* entities,
70  size_t num_entities,
71  void* data ) const;
72 
73  /**\brief Get tag value for passed entities
74  *
75  * Get tag values for specified entities.
76  *
77  *\Note Will fail for variable-length data.
78  *\param seqman Pointer to mesh entity database
79  *\param entities Entity handles for which to retrieve tag data
80  *\param data Pointer to memory in which to store consecutive tag values,
81  * one for each passed entity.
82  */
83  virtual ErrorCode get_data( const SequenceManager* seqman,
84  Error* error_handler,
85  const Range& entities,
86  void* data ) const;
87 
88  /**\brief Get tag value for passed entities
89  *
90  * Get tag values for specified entities.
91  *
92  *\param seqman Pointer to mesh entity database
93  *\param entities Entity handles for which to retrieve tag data
94  *\param num_entities Length of \c entities array
95  *\param data_ptrs Array of pointers to tag values, one pointer
96  * for each passed entity.
97  *\param data_lengths One value for each entity specifying the
98  * length of the tag value for the corresponding
99  * entity.
100  */
101  virtual ErrorCode get_data( const SequenceManager* seqman,
102  Error* error_handler,
103  const EntityHandle* entities,
104  size_t num_entities,
105  const void** data_ptrs,
106  int* data_lengths ) const;
107 
108  /**\brief Get tag value for passed entities
109  *
110  * Get tag values for specified entities.
111  *
112  *\param seqman Pointer to mesh entity database
113  *\param entities Entity handles for which to retrieve tag data
114  *\param data_ptrs Array of pointers to tag values, one pointer
115  * for each passed entity.
116  *\param data_lengths One value for each entity specifying the
117  * length of the tag value for the corresponding
118  * entity.
119  */
120  virtual ErrorCode get_data( const SequenceManager* seqman,
121  Error* error_handler,
122  const Range& entities,
123  const void** data_ptrs,
124  int* data_lengths ) const;
125 
126  /**\brief Set tag value for passed entities
127  *
128  * Store tag data or update stored tag values
129  *\Note Will fail for variable-length data.
130  *\param seqman Pointer to mesh entity database
131  *\param entities Entity handles for which to store tag data
132  *\param num_entities Length of \c entities array
133  *\param data Pointer to memory holding consecutive tag values,
134  * one for each passed entity.
135  */
136  virtual ErrorCode set_data( SequenceManager* seqman,
137  Error* error_handler,
138  const EntityHandle* entities,
139  size_t num_entities,
140  const void* data );
141 
142  /**\brief Set tag value for passed entities
143  *
144  * Store tag data or update stored tag values
145  *\Note Will fail for variable-length data.
146  *\param seqman Pointer to mesh entity database
147  *\param entities Entity handles for which to store tag data
148  *\param data Pointer to memory holding consecutive tag values,
149  * one for each passed entity.
150  */
151  virtual ErrorCode set_data( SequenceManager* seqman,
152  Error* error_handler,
153  const Range& entities,
154  const void* data );
155 
156  /**\brief Set tag value for passed entities
157  *
158  * Store tag data or update stored tag values
159  *
160  *\param seqman Pointer to mesh entity database
161  *\param entities Entity handles for which to store tag data
162  *\param num_entities Length of \c entities array
163  *\param data_ptrs Array of pointers to tag values, one pointer
164  * for each passed entity.
165  *\param data_lengths One value for each entity specifying the
166  * length of the tag value for the corresponding
167  * entity. Array is required for variable-length
168  * tags and is ignored for fixed-length tags.
169  */
170  virtual ErrorCode set_data( SequenceManager* seqman,
171  Error* error_handler,
172  const EntityHandle* entities,
173  size_t num_entities,
174  void const* const* data_ptrs,
175  const int* data_lengths );
176 
177  /**\brief Set tag value for passed entities
178  *
179  * Store tag data or update stored tag values
180  *
181  *\param seqman Pointer to mesh entity database
182  *\param entities Entity handles for which to store tag data
183  *\param data_ptrs Array of pointers to tag values, one pointer
184  * for each passed entity.
185  *\param data_lengths One value for each entity specifying the
186  * length of the tag value for the corresponding
187  * entity. Array is required for variable-length
188  * tags and is ignored for fixed-length tags.
189  */
190  virtual ErrorCode set_data( SequenceManager* seqman,
191  Error* error_handler,
192  const Range& entities,
193  void const* const* data_ptrs,
194  const int* data_lengths );
195 
196  /**\brief Set tag value for passed entities
197  *
198  * Store tag data or update stored tag values.
199  *
200  *\param seqman Pointer to mesh entity database
201  *\param entities Entity handles for which to store tag data
202  *\param num_entities Length of \c entities array
203  *\param value_ptr Pointer to a single tag value which is to be
204  * stored for each of the passed entities.
205  *\param value_len Length of tag value in bytes. Ignored for
206  * fixed-length tags. Required for variable-
207  * length tags.
208  */
209  virtual ErrorCode clear_data( SequenceManager* seqman,
210  Error* error_handler,
211  const EntityHandle* entities,
212  size_t num_entities,
213  const void* value_ptr,
214  int value_len = 0 );
215 
216  /**\brief Set tag value for passed entities
217  *
218  * Store tag data or update stored tag values.
219  *
220  *\param seqman Pointer to mesh entity database
221  *\param entities Entity handles for which to store tag data
222  *\param value_ptr Pointer to a single tag value which is to be
223  * stored for each of the passed entities.
224  *\param value_len Length of tag value in bytes. Ignored for
225  * fixed-length tags. Required for variable-
226  * length tags.
227  */
228  virtual ErrorCode clear_data( SequenceManager* seqman,
229  Error* error_handler,
230  const Range& entities,
231  const void* value_ptr,
232  int value_len = 0 );
233 
234  /**\brief Remove/clear tag data for entities
235  *
236  * Remove tag values from entities.
237  *
238  *\param seqman Pointer to mesh entity database
239  *\param entities Entity handles for which to store tag data
240  *\param num_entities Length of \c entities array
241  */
242  virtual ErrorCode remove_data( SequenceManager* seqman,
243  Error* error_handler,
244  const EntityHandle* entities,
245  size_t num_entities );
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  */
254  virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );
255 
256  /**\brief Access tag data via direct pointer into contiguous blocks
257  *
258  * Iteratively obtain direct access to contiguous blocks of tag
259  * storage. This function cannot be used with bit tags because
260  * of the compressed bit storage. This function cannot be used
261  * with variable length tags because it does not provide a mechanism
262  * to determine the length of the value for each entity. This
263  * function may be used with sparse tags, but if it is used, it
264  * will return data for a single entity at a time.
265  *
266  *\param iter As input, the first entity for which to return
267  * data. As output, one past the last entity for
268  * which data was returned.
269  *\param end One past the last entity for which data is desired
270  *\param data_ptr Output: pointer to tag storage.
271  *
272  *\Note If this function is called for entities for which no tag value
273  * has been set, but for which a default value exists, it will
274  * force the allocation of explicit storage for each such entity
275  * even though MOAB would normally not explicitly store tag values
276  * for such entities.
277  */
278  virtual ErrorCode tag_iterate( SequenceManager* seqman,
279  Error* error_handler,
280  Range::iterator& iter,
281  const Range::iterator& end,
282  void*& data_ptr,
283  bool allocate = true );
284 
285  /**\brief Get all tagged entities
286  *
287  * Get the list of entities for which the a tag value has been set,
288  * or a close approximation if the tag storage scheme cannot
289  * accurately determine exactly which entities have explicit values.
290  *
291  *\param seqman Pointer to entity storage database
292  *\param output_entities Results *appended* to this range
293  *\param type Optional entity type. If specified, search is
294  * limited to entities of specified type.
295  *\param intersect Optional intersect list. If specified,
296  * search is restricted to entities in this list.
297  */
298  virtual ErrorCode get_tagged_entities( const SequenceManager* seqman,
299  Range& output_entities,
300  EntityType type = MBMAXTYPE,
301  const Range* intersect = 0 ) const;
302 
303  /**\brief Count all tagged entities
304  *
305  * Count the entities for which the a tag value has been set,
306  * or a close approximation if the tag storage scheme cannot
307  * accurately determine exactly which entities have explicit values.
308  *
309  *\param seqman Pointer to entity storage database
310  *\param output_count This is *incremented* for each detected entity.
311  *\param type Optional entity type. If specified, search is
312  * limited to entities of specified type.
313  *\param intersect Optional intersect list. If specified,
314  * search is restricted to entities in this list.
315  */
316  virtual ErrorCode num_tagged_entities( const SequenceManager* seqman,
317  size_t& output_count,
318  EntityType type = MBMAXTYPE,
319  const Range* intersect = 0 ) const;
320 
321  /**\brief Get all tagged entities with tag value
322  *
323  * Get the list of entities which have the specified tag value.
324  *
325  *\param seqman Pointer to entity storage database
326  *\param output_entities Results *appended* to this range
327  *\param value Pointer to tag value
328  *\param value_bytes Size of tag value in bytes.
329  *\param type Optional entity type. If specified, search is
330  * limited to entities of specified type.
331  *\param intersect_entities Optional intersect list. If specified,
332  * search is restricted to entities in this list.
333  */
334  virtual ErrorCode find_entities_with_value( const SequenceManager* seqman,
335  Error* error_handler,
336  Range& output_entities,
337  const void* value,
338  int value_bytes = 0,
339  EntityType type = MBMAXTYPE,
340  const Range* intersect_entities = 0 ) const;
341 
342  /**\brief Check if entity is tagged */
343  virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;
344 
345  /**\brief Get memory use for tag data.
346  *
347  */
348  virtual ErrorCode get_memory_use( const SequenceManager* seqman,
349  unsigned long& total,
350  unsigned long& per_entity ) const;
351 
352  /**\brief Get read-only tag storage
353  *
354  *\param seqman Sequence manager
355  *\param error Error object through which to report errors
356  *\param h First entity for which to return storage.
357  *\param ptr Pointer to dag storage. This pointer will be set
358  * to null and \c MB_SUCCESS will be returned if the handle
359  * is valid but no tag storage has been allocated.
360  *\param count Number of consecutive entities for which tag storage
361  * is returned. This value will be valid even if null
362  * is returned for \c ptr and indicates the number of
363  * consecutive entities for which no tag storage has been
364  * allocated.
365  *\return MB_SUCCESS if handle is valid (regardless of whether
366  * or not any tag storage is allocated).
367  */
368  ErrorCode get_array( const SequenceManager* seqman,
369  Error* error,
370  EntityHandle h,
371  const unsigned char* const& ptr,
372  size_t& count ) const;
373 
374  /**\brief Get read-only tag storage for entire sequence
375  *
376  *\param seq Sequence
377  *\param ptr Pointer to dag storage. This pointer will be set
378  * to null and \c MB_SUCCESS will be returned if no tag storage has been
379  *allocated. \return MB_SUCCESS if sequence is valid (regardless of whether or not any
380  *tag storage is allocated).
381  */
382  ErrorCode get_array( const EntitySequence* seq, const unsigned char* const& ptr ) const;
383 
384  private:
385  DenseTag( const DenseTag& );
386  DenseTag& operator=( const DenseTag& );
387 
388  /**\brief Get or allocated tag storage
389  *
390  *\param h First entity for which to return storage.
391  *\param ptr Pointer to dag storage. This pointer will be set
392  * to null and \c MB_SUCCESS will be returned if the handle
393  * is valid but no tag storage has been allocated.
394  *\param count Number of consecutive entities for which tag storage
395  * is returned. This value will be valid even if null
396  * is returned for \c ptr and indicates the number of
397  * consecutive entities for which no tag storage has been
398  * allocated.
399  *\param allocate If true storage will be allocated and initialized
400  * if it has not already been allocated.
401  *\return MB_SUCCESS if handle is valid (regardless of whether
402  * or not any tag storage is allocated).
403  */
404  inline ErrorCode get_array_private( SequenceManager* seqman,
405  Error* error,
406  EntityHandle h,
407  unsigned char*& ptr,
408  size_t& count,
409  bool allocate );
410 
411  /**\brief Get tag storage
412  *
413  *\param h First entity for which to return storage.
414  *\param ptr Pointer to dag storage. This pointer will be set
415  * to null and \c MB_SUCCESS will be returned if the handle
416  * is valid but no tag storage has been allocated.
417  *\param count Number of consecutive entities for which tag storage
418  * is returned. This value will be valid even if null
419  * is returned for \c ptr and indicates the number of
420  * consecutive entities for which no tag storage has been
421  * allocated.
422  *\return MB_SUCCESS if handle is valid (regardless of whether
423  * or not any tag storage is allocated).
424  */
425  inline ErrorCode get_array_private( const SequenceManager* seqman,
426  Error* error,
427  EntityHandle h,
428  const unsigned char*& ptr,
429  size_t& count ) const;
430 
431  /**\brief Get non-read-only tag storage for entire sequence
432  *
433  *\param seq Sequence
434  *\param ptr Pointer to dag storage. This pointer will be set
435  * to null and \c MB_SUCCESS will be returned if no tag storage has been
436  *allocated. \return MB_SUCCESS if sequence is valid (regardless of whether or not any
437  *tag storage is allocated).
438  */
439  ErrorCode get_array_private( const EntitySequence* seq, const unsigned char*& ptr ) const;
440 
441  /**\brief Common implementation of public clear_data and remove_data */
442  ErrorCode clear_data( bool allocate,
443  SequenceManager* seqman,
444  Error* error,
445  const EntityHandle* entities,
446  size_t num_entities,
447  const void* value_ptr );
448 
449  /**\brief Common implementation of public clear_data and remove_data */
450  ErrorCode clear_data( bool allocate,
451  SequenceManager* seqman,
452  Error* error,
453  const Range& entities,
454  const void* value_ptr );
455 };
456 
457 } // namespace moab
458 
459 #endif // DENSE_TAG_HPP