casacore
TSMCubeBuff.h
Go to the documentation of this file.
1//# TSMCubeBuff.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_TSMCUBEBUFF_H
29#define TABLES_TSMCUBEBUFF_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/DataMan/TSMCube.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward declarations
39class BucketBuffered;
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=BucketBuffered>BucketBuffered</linkto>
57// </prerequisite>
58
59// <etymology>
60// TSMCubeBuff represents a hypercube in the Tiled Storage Manager.
61// </etymology>
62
63// <synopsis>
64// TSMCubeBuff defines a tiled hypercube. The data is stored in a TSMFile
65// object and accessed using a BucketBuffered 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// TSMCubeBuff 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// TSMCubeBuff 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
97class TSMCubeBuff: public TSMCube
98{
99public:
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.
106 const IPosition& cubeShape,
107 const IPosition& tileShape,
108 const Record& values, Int64 fileOffset, uInt bufferSize);
109
110 // Reconstruct the hypercube by reading its data from the AipsIO stream.
111 // It will link itself to the correct TSMFile. The TSMFile objects
112 // must have been reconstructed in advance.
113 TSMCubeBuff (TiledStMan* stman, AipsIO& ios, uInt bufferSize);
114
115 virtual ~TSMCubeBuff();
116
117 // Flush the data in the cache.
118 virtual void flushCache();
119
120 // Show the cache statistics.
121 virtual void showCacheStatistics (ostream& os) const;
122
123 // Set the hypercube shape.
124 // This is only possible if the shape was not defined yet.
125 virtual void setShape (const IPosition& cubeShape,
126 const IPosition& tileShape);
127
128 // Extend the last dimension of the cube with the given number.
129 // The record can contain the coordinates of the elements added.
130 virtual void extend (uInt64 nr, const Record& coordValues,
131 const TSMColumn* lastCoordColumn);
132
133 // Read or write a section in the cube.
134 // It is assumed that the section buffer is long enough.
135 virtual void accessSection (const IPosition& start, const IPosition& end,
136 char* section, uInt colnr,
137 uInt localPixelSize, uInt externalPixelSize,
138 Bool writeFlag);
139
140 // Read or write a section in a strided way.
141 // It is assumed that the section buffer is long enough.
142 virtual void accessStrided (const IPosition& start, const IPosition& end,
143 const IPosition& stride,
144 char* section, uInt colnr,
145 uInt localPixelSize, uInt externalPixelSize,
146 Bool writeFlag);
147
148 // Set the cache size for the given slice and access path.
149 virtual void setCacheSize (const IPosition& sliceShape,
150 const IPosition& windowStart,
151 const IPosition& windowLength,
152 const IPosition& axisPath,
153 Bool forceSmaller, Bool userSet);
154
155 // Resize the cache object.
156 // If forceSmaller is False, the cache will only be resized when it grows.
157 // If the given size exceeds the maximum size with more
158 // than 10%, the maximum size will be used.
159 // The cacheSize has to be given in buckets.
160 // <br>The flag <src>userSet</src> inidicates if the cache size is set by
161 // the user (by an Accessor object) or automatically (by TSMDataColumn).
162 virtual void setCacheSize (uInt cacheSize, Bool forceSmaller, Bool userSet);
163
164private:
165 // Forbid copy constructor.
167
168 // Forbid assignment.
170
171 // Get the cache object.
172 // This will construct the cache object if not present yet.
174
175 // Construct the cache object (if not constructed yet).
176 virtual void makeCache();
177
178 // Resync the cache object.
179 virtual void resyncCache();
180
181 // Delete the cache object.
182 virtual void deleteCache();
183
184 //# Declare member variables.
185 // The bucket cache.
187 // The buffer size to use.
189};
190
191
192
194{
195 if (cache_p == 0) {
196 makeCache();
197 }
198 return cache_p;
199}
200
201
202
203} //# NAMESPACE CASACORE - END
204
205#endif
virtual void extend(uInt64 nr, const Record &coordValues, const TSMColumn *lastCoordColumn)
Extend the last dimension of the cube with the given number.
virtual void makeCache()
Construct the cache object (if not constructed yet).
TSMCubeBuff(TiledStMan *stman, TSMFile *file, const IPosition &cubeShape, const IPosition &tileShape, const Record &values, Int64 fileOffset, uInt bufferSize)
Construct the hypercube using the given file with the given shape.
TSMCubeBuff(TiledStMan *stman, AipsIO &ios, uInt bufferSize)
Reconstruct the hypercube by reading its data from the AipsIO stream.
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 resyncCache()
Resync the cache object.
virtual void deleteCache()
Delete the cache object.
BucketBuffered * cache_p
The bucket cache.
Definition: TSMCubeBuff.h:186
TSMCubeBuff & operator=(const TSMCubeBuff &)
Forbid assignment.
BucketBuffered * getCache()
Get the cache object.
Definition: TSMCubeBuff.h:193
uInt bufferSize_p
The buffer size to use.
Definition: TSMCubeBuff.h:188
virtual void showCacheStatistics(ostream &os) const
Show the cache statistics.
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 setShape(const IPosition &cubeShape, const IPosition &tileShape)
Set the hypercube shape.
TSMCubeBuff(const TSMCubeBuff &)
Forbid copy constructor.
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.
virtual void setCacheSize(uInt cacheSize, Bool forceSmaller, Bool userSet)
Resize the cache object.
virtual void flushCache()
Flush the data in the cache.
uInt cacheSize() const
Get the current cache size (in buckets).
const IPosition & tileShape() const
Get the shape of the tiles.
Definition: TSMCube.h:442
const IPosition & cubeShape() const
Get the shape of the hypercube.
Definition: TSMCube.h:438
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
unsigned long long uInt64
Definition: aipsxtype.h:39