casacore
TiledStManAccessor.h
Go to the documentation of this file.
1 //# TiledStManAccessor.h: Gives access to some TiledStMan functions
2 //# Copyright (C) 1994,1995,1996,1997,1999,2000,2001
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_TILEDSTMANACCESSOR_H
29 #define TABLES_TILEDSTMANACCESSOR_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/DataManAccessor.h>
34 #include <casacore/casa/iosfwd.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class TiledStMan;
40 class DataManager;
41 class Table;
42 class IPosition;
43 class String;
44 class Record;
45 
46 // <summary>
47 // Give access to some TiledStMan functions
48 // </summary>
49 
50 // <use visibility=local>
51 
52 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
53 // </reviewed>
54 
55 // <prerequisite>
56 //# Classes you should understand before using this one.
57 // <li> <linkto class=TiledStMan>TiledStMan</linkto>
58 // </prerequisite>
59 
60 // <synopsis>
61 // The Table system has one or more storage managers underneath.
62 // These storage managers are invisible and there is no way to
63 // get access to them.
64 // However, the <linkto class=TiledStMan>TiledStMan</linkto>-type
65 // storage managers are quite specific.
66 // This class ROTiledStManAccessor gives the user the means to
67 // access a TiledStMan-type object and to control it in some way.
68 // <p>
69 // The actions that can be performed deal with the caches used in
70 // a tiled storage manager. Per hypercube a cache is used to keep as many
71 // tiles in memory as needed for efficient access to the data.
72 // The cache size needed is calculated automatically. However,
73 // it may be possible that a cache uses too much memory. Therefore
74 // a maximum cache size can be specified, which can be done in 2 ways:
75 // <ol>
76 // <li> To the constructor of a tiled storage manager. This is
77 // persistent and acts as the default maximum cache size.
78 // <li> Using the function setMaximumCacheSize in this accessor class.
79 // This is not persistent and acts as a temporary overwrite
80 // of the default maximum cache size.
81 // </ol>
82 // It is recommended to set the maximum cache size only when the
83 // tiled storage manager may use too much memory. Setting a
84 // maximum could have the effect that the optimal number of tiles
85 // does not fit in memory leading to excessive read/write activity.
86 // <br>For example:<br>
87 // A hypercube has shape [12,20,30,42] and tile shape [4,5,6,7].
88 // The hypercube contains doubles, so the tilesize is 6720 bytes.
89 // The number of tiles per dimension is [3,4,5,6] resulting in 360 tiles.
90 // Iterating through that hypercube requires that some tiles are kept in
91 // memory to avoid too many read operations. When iterating like
92 // <srcblock>
93 // for (uInt i3=0; i3<42; i3++)
94 // for (uInt i2=0; i2<30; i2++)
95 // for (uInt i1=0; i1<20; i1++)
96 // for (uInt i0=0; i0<12; i0++)
97 // do something with data[i0,i1,i2,i3]
98 // </srcblock>
99 // it is clear that it is best to have a cache which can contain at least
100 // 3*4*5 tiles. In that way each tile is read only once resulting in
101 // 360 reads.
102 // <br>When the cache can hold 3*4 tiles, the first tiles of the 3rd
103 // dimension have been flushed out when the second step in the 4th dimension
104 // gets executed. So the tiles have to be reread for each step in the 4th
105 // dimension, resulting in 3*4*5*42 = 2520 reads.
106 // <br>When the cache can hold only one tile, the situation is dramatic.
107 // A tile has to be read for every 4 pixels, resulting in 75600 reads.
108 // <p>
109 // Apart from setting the maximum cache size, one can also clear the
110 // caches. This can be useful to free memory when an iteration through the
111 // data in the tiled storage manager has been done completely. Clearing
112 // the caches also clears their statistics (see below).
113 // <p>
114 // Showing the statistics of the caches used by a tiled storage
115 // manager is possible. Per cache it shows the number of tiles accessed and
116 // the number of tiles actually read, written, or initialized. The hit ratio
117 // gives a good idea of the cache behaviour.
118 // <p>
119 // Note that the maximum cache size is not an absolute maximum.
120 // When the optimal number of tiles do not fit, it is tried if they fit
121 // when using an overdrawn of maximum 10%. If so, it uses that overdrawn.
122 // If not, it uses the maximum cache size.
123 // <p>
124 // A few functions exist to get information about a hypercube.
125 // The 'get' functions get the information for the given hypercube,
126 // while similar functions without the 'get' prefix do the same for the
127 // given row.
128 // </synopsis>
129 
130 // <motivation>
131 // In principle a pointer to TiledStMan could be used.
132 // However, that would give access to all public functions.
133 // Furthermore it could not distinguish between read/write and readonly
134 // tables.
135 // </motivation>
136 
137 // <example>
138 // This example shows how to set the maximum cache size for
139 // the tiled storage manager with the name "TSMExample". The cache
140 // size is not persistent, i.e. when the same table is reopened
141 // at a later time, this cache size is not remembered.
142 // <srcblock>
143 // // Open a table.
144 // Table table("someName.data");
145 // // Set the maximum cache size of its tiled hypercube storage
146 // // manager TSMExample to 0.5 MiB.
147 // ROTiledStManAccessor accessor(table, "TSMExample");
148 // accessor.setMaximumCacheSize (512*1024);
149 // </srcblock>
150 // </example>
151 
152 //# <todo asof="$DATE:$">
153 //# </todo>
154 
155 
157 {
158 public:
159  // Default constructor should be used with care.
160  // The resulting object cannot be used for any other operation
161  // until a 'true' ROTiledStManAccessor object is assigned to it.
163 
164  // Construct the object for a data manager in the table given the name
165  // of the data manager or the column.
166  // An exception is thrown if the data manager type is not any tiled
167  // storage manager.
168  ROTiledStManAccessor (const Table& table, const String& name,
169  Bool byColumn=False);
170 
172 
173  // Copy constructor (reference semantics).
175 
176  // Assignment (reference semantics).
178 
179  // Set the maximum cache size (in MibiByte) to be used by a hypercube
180  // in the storage manager. Note that each hypercube has its own cache.
181  // 0 means unlimited.
182  // The initial maximum cache size is unlimited.
183  // The maximum cache size given in this way is not persistent.
184  // Only the maximum cache size given to the constructors of the tiled
185  // storage managers, is persistent.
187 
188  // Get the maximum cache size (in MiB).
190 
191  // Get the current cache size (in buckets) for the hypercube in
192  // the given row.
193  uInt cacheSize (uInt rownr) const;
194 
195  // Get the hypercube shape of the data in the given row.
196  const IPosition& hypercubeShape (uInt rownr) const;
197 
198  // Get the tile shape of the data in the given row.
199  const IPosition& tileShape (uInt rownr) const;
200 
201  // Get the bucket size (in bytes) of the hypercube in the given row.
202  uInt bucketSize (uInt rownr) const;
203 
204  // Get coordinate and id values of the hypercube in the given row.
205  const Record& valueRecord (uInt rownr) const;
206 
207  // Return the number of hypercubes.
208  uInt nhypercubes() const;
209 
210  // Get the current cache size (in buckets) for the given hypercube.
211  uInt getCacheSize (uInt hypercube) const;
212 
213  // Get the shape of the given hypercube.
214  const IPosition& getHypercubeShape (uInt hypercube) const;
215 
216  // Get the tile shape of the given hypercube.
217  const IPosition& getTileShape (uInt hypercube) const;
218 
219  // Get the bucket size (in bytes) of the given hypercube.
220  uInt getBucketSize (uInt hypercube) const;
221 
222  // Get coordinate and id values of the given hypercube.
223  const Record& getValueRecord (uInt hypercube) const;
224 
225  // Calculate the cache size (in buckets) for accessing the hypercube
226  // containing the given row. It takes the maximum cache size into
227  // account (allowing an overdraft of 10%).
228  // It uses the given axisPath (i.e. traversal order) to determine
229  // the optimum size. A window can be specified to indicate that only
230  // the given subset of the hypercube will be accessed. The window
231  // defaults to the entire hypercube.
232  // <br>
233  // The length of the slice and window arguments and <src>axisPath</src>
234  // must be less or equal to the dimensionality of the hypercube.
235  // The non-specified <src>windowStart</src> parts default to 0.
236  // The non-specified <src>windowLength</src> parts default to
237  // the hypercube shape.
238  // The non-specified <src>sliceShape</src> parts default to 1.
239  // <br>
240  // Axispath = [2,0,1] indicates that the z-axis changes most rapidly,
241  // thereafter x and y. An axis can occur only once in the axisPath.
242  // The non-specified <src>axisPath</src> parts get the natural order.
243  // E.g. in the previous example axisPath=[2] defines the same path.
244  // <group>
245  uInt calcCacheSize (uInt rownr, const IPosition& sliceShape,
246  const IPosition& axisPath) const;
247  uInt calcCacheSize (uInt rownr, const IPosition& sliceShape,
248  const IPosition& windowStart,
249  const IPosition& windowLength,
250  const IPosition& axisPath) const;
251  // </group>
252 
253  // Set the cache size using the corresponding <src>calcCacheSize</src>
254  // function mentioned above.
255  // <br>When forceSmaller is False, the cache is not resized when the
256  // new size is smaller.
257  // <group>
258  void setCacheSize (uInt rownr, const IPosition& sliceShape,
259  const IPosition& axisPath,
260  Bool forceSmaller = True);
261  void setCacheSize (uInt rownr, const IPosition& sliceShape,
262  const IPosition& windowStart,
263  const IPosition& windowLength,
264  const IPosition& axisPath,
265  Bool forceSmaller = True);
266  // </group>
267 
268  // Set the cache size for accessing the hypercube containing the given row.
269  // When the give cache size exceeds the maximum cache size with more
270  // than 10%, the maximum cache size is used instead.
271  // <br>When forceSmaller is False, the cache is not resized when the
272  // new size is smaller.
273  void setCacheSize (uInt rownr, uInt nbuckets, Bool forceSmaller = True);
274 
275  // This version allows setting the tile cache for a particular hypercube. This
276  // is useful when iterating over the hypercubes in an StMan.
277  void setHypercubeCacheSize (uInt hypercube, uInt nbuckets, Bool forceSmaller = True);
278 
279  // Clear the caches used by the hypercubes in this storage manager.
280  // It will flush the caches as needed and remove all buckets from them
281  // resulting in a possibly large drop in memory used.
282  void clearCaches();
283 
284 
285 protected:
286  // Get the data manager.
288 
289 
290 private:
291  //# Declare the data members.
293 };
294 
295 
296 
297 
298 } //# NAMESPACE CASACORE - END
299 
300 #endif
casacore::ROTiledStManAccessor::getDataManager
DataManager * getDataManager() const
Get the data manager.
casacore::ROTiledStManAccessor::setCacheSize
void setCacheSize(uInt rownr, uInt nbuckets, Bool forceSmaller=True)
Set the cache size for accessing the hypercube containing the given row.
casacore::ROTiledStManAccessor::valueRecord
const Record & valueRecord(uInt rownr) const
Get coordinate and id values of the hypercube in the given row.
casacore::IPosition
Definition: IPosition.h:120
casacore::DataManager
Abstract base class for a data manager.
Definition: DataManager.h:225
casacore::ROTiledStManAccessor::setMaximumCacheSize
void setMaximumCacheSize(uInt nMiB)
Set the maximum cache size (in MibiByte) to be used by a hypercube in the storage manager.
casacore::ROTiledStManAccessor::getCacheSize
uInt getCacheSize(uInt hypercube) const
Get the current cache size (in buckets) for the given hypercube.
casacore::ROTiledStManAccessor::ROTiledStManAccessor
ROTiledStManAccessor()
Default constructor should be used with care.
casacore::ROTiledStManAccessor::~ROTiledStManAccessor
virtual ~ROTiledStManAccessor()
casacore::ROTiledStManAccessor::maximumCacheSize
uInt maximumCacheSize() const
Get the maximum cache size (in MiB).
casacore::ROTiledStManAccessor::tileShape
const IPosition & tileShape(uInt rownr) const
Get the tile shape of the data in the given row.
casacore::ROTiledStManAccessor::setCacheSize
void setCacheSize(uInt rownr, const IPosition &sliceShape, const IPosition &axisPath, Bool forceSmaller=True)
Set the cache size using the corresponding calcCacheSize function mentioned above.
casacore::ROTiledStManAccessor::operator=
ROTiledStManAccessor & operator=(const ROTiledStManAccessor &that)
Assignment (reference semantics).
casacore::ROTiledStManAccessor::clearCaches
void clearCaches()
Clear the caches used by the hypercubes in this storage manager.
casacore::ROTiledStManAccessor
Definition: TiledStManAccessor.h:157
casacore::ROTiledStManAccessor::calcCacheSize
uInt calcCacheSize(uInt rownr, const IPosition &sliceShape, const IPosition &axisPath) const
Calculate the cache size (in buckets) for accessing the hypercube containing the given row.
casacore::ROTiledStManAccessor::ROTiledStManAccessor
ROTiledStManAccessor(const Table &table, const String &name, Bool byColumn=False)
Construct the object for a data manager in the table given the name of the data manager or the column...
casacore::Table
Definition: Table.h:154
casacore::ROTiledStManAccessor::bucketSize
uInt bucketSize(uInt rownr) const
Get the bucket size (in bytes) of the hypercube in the given row.
casacore::ROTiledStManAccessor::hypercubeShape
const IPosition & hypercubeShape(uInt rownr) const
Get the hypercube shape of the data in the given row.
casacore::ROTiledStManAccessor::ROTiledStManAccessor
ROTiledStManAccessor(const ROTiledStManAccessor &that)
Copy constructor (reference semantics).
casacore::TiledStMan
Definition: TiledStMan.h:108
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::RODataManAccessor
Definition: DataManAccessor.h:78
casacore::ROTiledStManAccessor::setCacheSize
void setCacheSize(uInt rownr, const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller=True)
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::ROTiledStManAccessor::getValueRecord
const Record & getValueRecord(uInt hypercube) const
Get coordinate and id values of the given hypercube.
casacore::ROTiledStManAccessor::getBucketSize
uInt getBucketSize(uInt hypercube) const
Get the bucket size (in bytes) of the given hypercube.
casacore::ROTiledStManAccessor::calcCacheSize
uInt calcCacheSize(uInt rownr, const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath) const
casacore::ROTiledStManAccessor::nhypercubes
uInt nhypercubes() const
Return the number of hypercubes.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Record
Definition: Record.h:181
casacore::ROTiledStManAccessor::dataManPtr_p
TiledStMan * dataManPtr_p
Definition: TiledStManAccessor.h:292
casacore::ROTiledStManAccessor::setHypercubeCacheSize
void setHypercubeCacheSize(uInt hypercube, uInt nbuckets, Bool forceSmaller=True)
This version allows setting the tile cache for a particular hypercube.
casacore::ROTiledStManAccessor::getHypercubeShape
const IPosition & getHypercubeShape(uInt hypercube) const
Get the shape of the given hypercube.
casacore::ROTiledStManAccessor::getTileShape
const IPosition & getTileShape(uInt hypercube) const
Get the tile shape of the given hypercube.
casacore::ROTiledStManAccessor::cacheSize
uInt cacheSize(uInt rownr) const
Get the current cache size (in buckets) for the hypercube in the given row.