XdmfHeavyDataController.hpp 9.12 KB
Newer Older
Kenneth Leiter's avatar
Kenneth Leiter committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*****************************************************************************/
/*                                    XDMF                                   */
/*                       eXtensible Data Model and Format                    */
/*                                                                           */
/*  Id : XdmfHeavyDataController.hpp                                         */
/*                                                                           */
/*  Author:                                                                  */
/*     Kenneth Leiter                                                        */
/*     kenneth.leiter@arl.army.mil                                           */
/*     US Army Research Laboratory                                           */
/*     Aberdeen Proving Ground, MD                                           */
/*                                                                           */
/*     Copyright @ 2011 US Army Research Laboratory                          */
/*     All Rights Reserved                                                   */
/*     See Copyright.txt for details                                         */
/*                                                                           */
/*     This software is distributed WITHOUT ANY WARRANTY; without            */
/*     even the implied warranty of MERCHANTABILITY or FITNESS               */
/*     FOR A PARTICULAR PURPOSE.  See the above copyright notice             */
/*     for more information.                                                 */
/*                                                                           */
/*****************************************************************************/

24 25 26 27 28 29 30 31
#ifndef XDMFHEAVYDATACONTROLLER_HPP_
#define XDMFHEAVYDATACONTROLLER_HPP_

// Forward Declarations
class XdmfArray;
class XdmfArrayType;

// Includes
32
#include "XdmfCore.hpp"
33
#include <string>
34
#include <vector>
35
#include "XdmfSharedPtr.hpp"
36 37 38 39

/**
 * @brief Couples an XdmfArray with heavy data stored on disk.
 *
40 41 42 43 44 45 46 47
 * This is an abstract base class to support the reading of different
 * heavy data formats.
 *
 * Serves as an interface between data stored in XdmfArrays and data
 * stored on disk. When an Xdmf file is read from or written to disk
 * an XdmfHeavyController is attached to XdmfArrays. This allows data
 * to be released from memory but still be accessible or have its
 * location written to light data.
48
 */
49
class XDMFCORE_EXPORT XdmfHeavyDataController {
50

51
public:
52 53 54

  virtual ~XdmfHeavyDataController() = 0;

55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
  /**
   * Gets the controller in string form. For writing to file.
   *
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDescriptor
   * @until //#getDescriptor
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDescriptor
   * @until #//getDescriptor
   *
   * @return    A string that contains relevant information for the controller
   */
  virtual std::string getDescriptor() const;

80 81 82
  /**
   * Get the dimensions of the heavy data set owned by this controller.
   *
83 84 85 86
   * Example of use:
   *
   * C++
   *
87
   * @dontinclude ExampleXdmfHeavyDataController.cpp
88 89 90 91
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDimensions
   * @until //#getDimensions
92 93 94
   *
   * Python
   *
95
   * @dontinclude XdmfExampleHeavyDataController.py
96 97 98 99
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDimensions
   * @until #//getDimensions
100
   *
101 102
   * @return    A vector containing the size in each dimension of the heavy data
   *            set owned by this controller.
103 104 105
   */
  std::vector<unsigned int> getDimensions() const;

106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
  /**
   * Get the absolute path to the heavy data file on disk where the
   * data set owned by this controller resides.
   * For "/home/output.h5:/foo/data" this is "/home/output.h5"
   *
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getFilePath
   * @until //#getFilePath
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getFilePath
   * @until #//getFilePath
   *
   * @return    A std::string containing the path to the heavy data file.
   */
  std::string getFilePath() const;

133
  /**
134 135
   * Get the name of this heavy data format. E.g. "HDF" for hdf5
   * format.
136
   *
137 138 139 140
   * Example of use:
   *
   * C++
   *
141
   * @dontinclude ExampleXdmfHeavyDataController.cpp
142 143 144 145
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getName
   * @until //#getName
146 147 148
   *
   * Python
   *
149
   * @dontinclude XdmfExampleHeavyDataController.py
150 151 152 153
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getName
   * @until #//getName
154
   *
155
   * @return    std::string containing the name of this heavy data format
156 157 158 159 160 161
   */
  virtual std::string getName() const = 0;

  /**
   * Get the size of the heavy data set owned by this controller.
   *
162 163 164 165
   * Example of use:
   *
   * C++
   *
166
   * @dontinclude ExampleXdmfHeavyDataController.cpp
167 168 169 170
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getSize
   * @until //#getSize
171 172 173
   *
   * Python
   *
174
   * @dontinclude XdmfExampleHeavyDataController.py
175 176 177 178
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getSize
   * @until #//getSize
179
   *
180
   * @return    An int containing the size of the heavy data set.
181 182 183
   */
  unsigned int getSize() const;

184
  /**
185 186
   * For use in conjunction with heavy data controllers set to arrays
   * the offset within the array from which the controller will be inserted
187 188 189 190 191
   * Is also set when created by a writer.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
192 193 194 195
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
196 197 198 199
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
200 201 202 203
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
204
   *
205
   * @param     newOffset       The new index at which the controller will be written
206 207 208 209
   */
  void setArrayOffset(unsigned int newOffset);

  /**
210 211
   * Gets the index at which the controller will offset when
   * an array reads it from its associated controllers.
212 213 214 215 216
   * Set when created by a Writer or set manually.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
217 218 219 220 221 222
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
   * @skipline //#getArrayOffset
   * @until //#getArrayOffset
223 224 225 226
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
227 228 229 230 231 232
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
   * @skipline #//getArrayOffset
   * @until #//getArrayOffset
233
   *
234
   * @return    The offset that the array will read from
235 236 237
   */
  unsigned int getArrayOffset() const;

238 239
  virtual void getProperties(std::map<std::string, std::string> & collectedProperties) const = 0;

240
  /**
241 242
   * Get the array type of the heavy data set owned by this
   * controller.
243
   *
244 245 246 247
   * Example of use:
   *
   * C++
   *
248
   * @dontinclude ExampleXdmfHeavyDataController.cpp
249 250 251 252
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getType
   * @until //#getType
253 254 255
   *
   * Python
   *
256
   * @dontinclude XdmfExampleHeavyDataController.py
257 258 259 260
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getType
   * @until #//getType
261
   *
262
   * @return    An XdmfArrayType containing the array type of the heavy data set.
263
   */
264
  shared_ptr<const XdmfArrayType> getType() const;
265 266

  /**
267 268
   * Read data owned by this controller on disk into the passed
   * XdmfArray.
269
   *
270 271 272 273
   * Example of use:
   *
   * C++
   *
274
   * @dontinclude ExampleXdmfHeavyDataController.cpp
275 276 277 278
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#read
   * @until //#read
279 280 281
   *
   * Python
   *
282
   * @dontinclude XdmfExampleHeavyDataController.py
283 284 285 286
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//read
   * @until #//read
287
   *
288
   * @param     array   An XdmfArray to read data into.
289 290 291
   */
  virtual void read(XdmfArray * const array) = 0;

292
protected:
293

294
  XdmfHeavyDataController(const std::string & filePath,
295
                          const shared_ptr<const XdmfArrayType> & type,
296
                          const std::vector<unsigned int> & dimensions);
297

298 299
  const std::vector<unsigned int> mDimensions;
  const std::string mFilePath;
300
  unsigned int mArrayStartOffset;
301
  const shared_ptr<const XdmfArrayType> mType;
302

303
private:
304 305 306

  XdmfHeavyDataController(const XdmfHeavyDataController&);  // Not implemented.
  void operator=(const XdmfHeavyDataController &);  // Not implemented.
307 308 309

};

310
#ifdef _WIN32
311
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
312
shared_ptr<const XdmfArrayType>;
313 314
#endif

315
#endif /* XDMFHEAVYDATACONTROLLER_HPP_ */