casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TSMCubeMMap.h
Go to the documentation of this file.
1 //# TSMCubeMMap.h: Tiled hypercube in a table
2 //# Copyright (C) 2009
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_TSMCUBEMMAP_H
29 #define TABLES_TSMCUBEMMAP_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward declarations
39 class BucketMapped;
40 
41 // <summary>
42 // Tiled hypercube in a table
43 // </summary>
44 
45 // <use visibility=local>
46 
47 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
48 // </reviewed>
49 
50 // <prerequisite>
51 //# Classes you should understand before using this one.
52 // <li> <linkto class=TiledStMan>TiledStMan</linkto>
53 // <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
54 // for a discussion of the maximum cache size
55 // <li> <linkto class=TSMFile>TSMFile</linkto>
56 // <li> <linkto class=BucketMapped>BucketMapped</linkto>
57 // </prerequisite>
58 
59 // <etymology>
60 // TSMCubeMMap represents a hypercube in the Tiled Storage Manager.
61 // </etymology>
62 
63 // <synopsis>
64 // TSMCubeMMap defines a tiled hypercube. The data is stored in a TSMFile
65 // object and accessed using a BucketMapped object. The hypercube can
66 // be extensible in its last dimension to support tables with a size
67 // which is not known in advance.
68 // <br>
69 // Normally hypercubes share the same TSMFile object, but extensible
70 // hypercubes have their own TSMFile object (to be extensible).
71 // If the hypercolumn has multiple data columns, their cells share the same
72 // tiles. Per tile data column A appears first, thereafter B, etc..
73 // <br>
74 // The data in the cache is held in external format and is converted
75 // when accessed. The alternative would be to hold it in the cache in
76 // local format and convert it when read/written from the file. It was
77 // felt that the latter approach would generate more needless conversions.
78 // <p>
79 // The possible id and coordinate values are stored in a Record
80 // object. They are written in the main hypercube AipsIO file.
81 // <p>
82 // TSMCubeMMap uses the maximum cache size set for a Tiled Storage manager.
83 // The description of class
84 // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
85 // contains a discussion about the effect of setting the maximum cache size.
86 // </synopsis>
87 
88 // <motivation>
89 // TSMCubeMMap encapsulates all operations on a hypercube.
90 // </motivation>
91 
92 //# <todo asof="$DATE:$">
93 //# A List of bugs, limitations, extensions or planned refinements.
94 //# </todo>
95 
96 
97 class TSMCubeMMap: public TSMCube
98 {
99 public:
100  // Construct the hypercube using the given file with the given shape.
101  // The record contains the id and possible coordinate values.
102  // <br>If the cubeshape is empty, the hypercube is still undefined and
103  // can be added later with setShape. That is only used by TiledCellStMan.
104  // <br> The fileOffset argument is meant for class TiledFileAccess.
105  TSMCubeMMap (TiledStMan* stman, TSMFile* file,
106  const IPosition& cubeShape,
107  const IPosition& tileShape,
108  const Record& values,
109  Int64 fileOffset);
110 
111  // Reconstruct the hypercube by reading its data from the AipsIO stream.
112  // It will link itself to the correct TSMFile. The TSMFile objects
113  // must have been reconstructed in advance.
114  TSMCubeMMap (TiledStMan* stman, AipsIO& ios);
115 
116  virtual ~TSMCubeMMap();
117 
118  // Flush the data in the cache.
119  virtual void flushCache();
120 
121  // Show the cache statistics.
122  virtual void showCacheStatistics (ostream& os) const;
123 
124  // Set the hypercube shape.
125  // This is only possible if the shape was not defined yet.
126  virtual void setShape (const IPosition& cubeShape,
127  const IPosition& tileShape);
128 
129  // Extend the last dimension of the cube with the given number.
130  // The record can contain the coordinates of the elements added.
131  virtual void extend (uInt64 nr, const Record& coordValues,
132  const TSMColumn* lastCoordColumn);
133 
134  // Read or write a section in the cube.
135  // It is assumed that the section buffer is long enough.
136  virtual void accessSection (const IPosition& start, const IPosition& end,
137  char* section, uInt colnr,
138  uInt localPixelSize, uInt externalPixelSize,
139  Bool writeFlag);
140 
141  // Read or write a section in a strided way.
142  // It is assumed that the section buffer is long enough.
143  virtual void accessStrided (const IPosition& start, const IPosition& end,
144  const IPosition& stride,
145  char* section, uInt colnr,
146  uInt localPixelSize, uInt externalPixelSize,
147  Bool writeFlag);
148 
149  // Set the cache size for the given slice and access path.
150  virtual void setCacheSize (const IPosition& sliceShape,
151  const IPosition& windowStart,
152  const IPosition& windowLength,
153  const IPosition& axisPath,
154  Bool forceSmaller, Bool userSet);
155 
156  // Resize the cache object.
157  // If forceSmaller is False, the cache will only be resized when it grows.
158  // If the given size exceeds the maximum size with more
159  // than 10%, the maximum size will be used.
160  // The cacheSize has to be given in buckets.
161  // <br>The flag <src>userSet</src> inidicates if the cache size is set by
162  // the user (by an Accessor object) or automatically (by TSMDataColumn).
163  virtual void setCacheSize (uInt cacheSize, Bool forceSmaller, Bool userSet);
164 
165 private:
166  // Forbid copy constructor.
167  TSMCubeMMap (const TSMCubeMMap&);
168 
169  // Forbid assignment.
171 
172  // Get the cache object.
173  // This will construct the cache object if not present yet.
175 
176  // Construct the cache object (if not constructed yet).
177  virtual void makeCache();
178 
179  // Resync the cache object.
180  virtual void resyncCache();
181 
182  // Delete the cache object.
183  virtual void deleteCache();
184 
185  //# Declare member variables.
186  // The bucket cache.
188 };
189 
190 
191 
193 {
194  if (cache_p == 0) {
195  makeCache();
196  }
197  return cache_p;
198 }
199 
200 
201 
202 } //# NAMESPACE CASACORE - END
203 
204 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:118
TSMCubeMMap(TiledStMan *stman, TSMFile *file, const IPosition &cubeShape, const IPosition &tileShape, const Record &values, Int64 fileOffset)
Construct the hypercube using the given file with the given shape.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
TSMCubeMMap & operator=(const TSMCubeMMap &)
Forbid assignment.
const IPosition & tileShape() const
Get the shape of the tiles.
Definition: TSMCube.h:442
Tiled hypercube in a table.
Definition: TSMCube.h:105
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
unsigned long long uInt64
Definition: aipsxtype.h:39
BucketMapped * cache_p
The bucket cache.
Definition: TSMCubeMMap.h:187
Base class for Tiled Storage Manager classes.
Definition: TiledStMan.h:106
virtual void extend(uInt64 nr, const Record &coordValues, const TSMColumn *lastCoordColumn)
Extend the last dimension of the cube with the given number.
uInt cacheSize() const
Get the current cache size (in buckets).
virtual void setCacheSize(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller, Bool userSet)
Set the cache size for the given slice and access path.
virtual void deleteCache()
Delete the cache object.
BucketMapped * getCache()
Get the cache object.
Definition: TSMCubeMMap.h:192
virtual void setShape(const IPosition &cubeShape, const IPosition &tileShape)
Set the hypercube shape.
const IPosition & cubeShape() const
Get the shape of the hypercube.
Definition: TSMCube.h:438
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual void makeCache()
Construct the cache object (if not constructed yet).
A column in the Tiled Storage Manager.
Definition: TSMColumn.h:97
File object for Tiled Storage Manager.
Definition: TSMFile.h:81
Tiled hypercube in a table.
Definition: TSMCubeMMap.h:97
virtual void showCacheStatistics(ostream &os) const
Show the cache statistics.
virtual void flushCache()
Flush the data in the cache.
virtual void accessStrided(const IPosition &start, const IPosition &end, const IPosition &stride, char *section, uInt colnr, uInt localPixelSize, uInt externalPixelSize, Bool writeFlag)
Read or write a section in a strided way.
virtual void accessSection(const IPosition &start, const IPosition &end, char *section, uInt colnr, uInt localPixelSize, uInt externalPixelSize, Bool writeFlag)
Read or write a section in the cube.
Use file mapping for buckets in a part of a file.
Definition: BucketMapped.h:76
unsigned int uInt
Definition: aipstype.h:51
virtual void resyncCache()
Resync the cache object.