XdmfHeavyDataController.hpp 9.14 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 <map>
36
#include "XdmfSharedPtr.hpp"
37 38 39 40

/**
 * @brief Couples an XdmfArray with heavy data stored on disk.
 *
41 42 43 44 45 46 47 48
 * 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.
49
 */
50
class XDMFCORE_EXPORT XdmfHeavyDataController {
51

52
public:
53 54 55

  virtual ~XdmfHeavyDataController() = 0;

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
  /**
   * 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
   */
Andrew J. Burns (Cont's avatar
Andrew J. Burns (Cont committed
79
  virtual std::string getDescriptor() const = 0;
80

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

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 133
  /**
   * 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;

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

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

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

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

Andrew J. Burns (Cont's avatar
Andrew J. Burns (Cont committed
239 240
  virtual void getProperties(std::map<std::string, std::string> & collectedProperties) const = 0;

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

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

293
protected:
294

295
  XdmfHeavyDataController(const std::string & filePath,
Andrew J. Burns (Cont's avatar
Andrew J. Burns (Cont committed
296
                          const shared_ptr<const XdmfArrayType> & type,
297
                          const std::vector<unsigned int> & dimensions);
298

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

304
private:
305 306 307

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

};

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

316
#endif /* XDMFHEAVYDATACONTROLLER_HPP_ */