casacore
TempLatticeImpl.h
Go to the documentation of this file.
1 //# TempLatticeImpl.h: A Lattice that can be used for temporary storage
2 //# Copyright (C) 1997,1998,1999,2000,2003
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 //#
27 //# $Id: TempLatticeImpl.h 20739 2009-09-29 01:15:15Z Malte.Marquarding $
28 
29 #ifndef LATTICES_TEMPLATTICEIMPL_H
30 #define LATTICES_TEMPLATTICEIMPL_H
31 
32 
33 //# Includes
34 #include <casacore/casa/aips.h>
35 #include <casacore/lattices/Lattices/Lattice.h>
36 #include <casacore/lattices/Lattices/TiledShape.h>
37 #include <casacore/tables/Tables/Table.h>
38 #include <casacore/casa/Utilities/CountedPtr.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class Table;
44 
45 
46 // <summary>
47 // The class implementing TempLattice
48 // </summary>
49 
50 // <use visibility=local>
51 
52 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTempLattice.cc" demos="">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto class="TempLattice">Lattice</linkto>
57 // </prerequisite>
58 
59 // <synopsis>
60 // The class is used as <src>CountedPtr<TempLatticeImpl></src> in class
61 // TempLattice. In that way the making a copy of a TempLattice uses the
62 // same object underneath.
63 // This was needed to have a correct implementation of tempClose. Otherwise
64 // when deleting a copy of a TempLattice, that destructor would delete the
65 // underlying table and the original TempLattice could not reopen it.
66 // </synopsis>
67 
68 
69 template<class T> class TempLatticeImpl
70 {
71 public:
72  // The default constructor creates a TempLatticeImpl containing a
73  // default ArrayLattice object.
75 
76  // Create a TempLatticeImpl of the specified shape. You can specify how much
77  // memory the Lattice can consume before it becomes disk based by giving a
78  // non-negative value to the maxMemoryInMB argument. Otherwise it will assume
79  // it can use up to 25% of the memory on your machine as defined in aipsrc
80  // (this algorithm may change). Setting maxMemoryInMB to zero will force
81  // the lattice to disk.
82  // <group>
83  TempLatticeImpl (const TiledShape& shape, Int maxMemoryInMB);
84  TempLatticeImpl (const TiledShape& shape, Double maxMemoryInMB);
85  // </group>
86 
87  // The destructor removes the Lattice from memory and if necessary disk.
89 
90  // Is the TempLattice paged to disk?
91  Bool isPaged() const
92  { return (! itsTableName.empty()); }
93 
94  // Can the lattice data be referenced as an array section?
96  { return (itsTableName.empty()); }
97 
98  // Is the TempLattice writable? It should be.
99  Bool isWritable() const
100  { return True; }
101 
102  // Flush the data.
103  void flush()
104  { if (itsTablePtr != 0) itsTablePtr->flush(); }
105 
106  // Close the Lattice temporarily (if it is paged to disk).
107  // It'll be reopened automatically when needed or when
108  // <src>reopen</src> is called explicitly.
109  void tempClose();
110 
111  // If needed, reopen a temporarily closed TempLatticeImpl.
112  void reopen();
113 
114  // Return the shape of the Lattice including all degenerate axes.
115  // (ie. axes with a length of one)
116  IPosition shape() const
117  { doReopen(); return itsLatticePtr->shape(); }
118 
119  // Set all of the elements in the Lattice to the given value.
120  void set (const T& value)
121  { doReopen(); itsLatticePtr->set (value); }
122 
123  // Replace every element, x, of the Lattice with the result of f(x). You
124  // must pass in the address of the function -- so the function must be
125  // declared and defined in the scope of your program. All versions of
126  // apply require a function that accepts a single argument of type T (the
127  // Lattice template type) and return a result of the same type. The first
128  // apply expects a function with an argument passed by value; the second
129  // expects the argument to be passed by const reference; the third
130  // requires an instance of the class <src>Functional<T,T></src>. The
131  // first form ought to run faster for the built-in types, which may be an
132  // issue for large Lattices stored in memory, where disk access is not an
133  // issue.
134  // <group>
135  void apply (T (*function)(T))
136  { doReopen(); itsLatticePtr->apply (function); }
137  void apply (T (*function)(const T&))
138  { doReopen(); itsLatticePtr->apply (function); }
139  void apply (const Functional<T,T>& function)
140  { doReopen(); itsLatticePtr->apply (function); }
141  // </group>
142 
143  // This function returns the recommended maximum number of pixels to
144  // include in the cursor of an iterator.
146  { doReopen(); return itsLatticePtr->advisedMaxPixels(); }
147 
148  // Get the best cursor shape.
150  { doReopen(); return itsLatticePtr->niceCursorShape (maxPixels); }
151 
152  // Maximum size - not necessarily all used. In pixels.
154  { return itsLatticePtr->maximumCacheSize(); }
155 
156  // Set the maximum (allowed) cache size as indicated.
157  void setMaximumCacheSize (uInt howManyPixels)
158  { itsLatticePtr->setMaximumCacheSize (howManyPixels); }
159 
160  // Set the cache size as to "fit" the indicated path.
161  void setCacheSizeFromPath (const IPosition& sliceShape,
162  const IPosition& windowStart,
163  const IPosition& windowLength,
164  const IPosition& axisPath)
165  { itsLatticePtr->setCacheSizeFromPath (sliceShape, windowStart, windowLength,
166  axisPath); }
167 
168  // Set the actual cache size for this Array to be be big enough for the
169  // indicated number of tiles. This cache is not shared with PagedArrays
170  // in other rows and is always clipped to be less than the maximum value
171  // set using the setMaximumCacheSize member function.
172  // tiles. Tiles are cached using a first in first out algorithm.
173  void setCacheSizeInTiles (uInt howManyTiles)
174  { itsLatticePtr->setCacheSizeInTiles (howManyTiles); }
175 
176  // Clears and frees up the caches, but the maximum allowed cache size is
177  // unchanged from when setCacheSize was called
178  void clearCache()
179  { itsLatticePtr->clearCache(); }
180 
181  // Report on cache success.
182  void showCacheStatistics (ostream& os) const
183  { itsLatticePtr->showCacheStatistics (os); }
184 
185  // Get or put a single element in the lattice.
186  // Note that Lattice::operator() can also be used to get a single element.
187  // <group>
188  T getAt (const IPosition& where) const
189  { doReopen(); return itsLatticePtr->getAt (where); }
190  void putAt (const T& value, const IPosition& where)
191  { doReopen(); itsLatticePtr->putAt (value, where); }
192  // </group>
193 
194  // Check class internals - used for debugging. Should always return True
195  Bool ok() const
196  { doReopen(); return itsLatticePtr->ok(); }
197 
198  // This function is used by the LatticeIterator class to generate an
199  // iterator of the correct type for this Lattice. Not recommended
200  // for general use.
202  Bool useRef) const
203  { doReopen(); return itsLatticePtr->makeIter (navigator, useRef); }
204 
205  // Do the actual getting of an array of values.
206  Bool doGetSlice (Array<T>& buffer, const Slicer& section)
207  { doReopen(); return itsLatticePtr->doGetSlice (buffer, section); }
208 
209  // Do the actual getting of an array of values.
210  void doPutSlice (const Array<T>& sourceBuffer,
211  const IPosition& where,
212  const IPosition& stride)
213  { doReopen(); itsLatticePtr->putSlice (sourceBuffer, where, stride); }
214 
215  // Do the reopen of the table (if not open already).
216  void doReopen() const
217  { if (itsIsClosed) tempReopen(); }
218 
219 private:
220  // The copy constructor cannot be used.
222 
223  // The assignment operator cannot be used.
225 
226  // Initialize the object.
227  void init (const TiledShape& shape, Double maxMemoryInMB=-1);
228 
229  // Do the actual reopen of the temporarily closed table (if not open already).
230  void tempReopen() const;
231 
232  // Make sure that the temporary table gets deleted.
233  void deleteTable();
234 
235 
236  mutable Table* itsTablePtr;
239  mutable Bool itsIsClosed;
240 };
241 
242 
243 
244 } //# NAMESPACE CASACORE - END
245 
246 #ifndef CASACORE_NO_AUTO_TEMPLATES
247 #include <casacore/lattices/Lattices/TempLatticeImpl.tcc>
248 #endif //# CASACORE_NO_AUTO_TEMPLATES
249 #endif
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Bool empty() const
Test for empty.
Definition: String.h:377
void flush(Bool fsync=False, Bool recursive=False)
Flush the table, i.e.
Definition: Table.h:1101
void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This function is used by the LatticeIterator class to generate an iterator of the correct type for th...
void init(const TiledShape &shape, Double maxMemoryInMB=-1)
Initialize the object.
void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
Bool isWritable() const
Is the TempLattice writable? It should be.
void tempClose()
Close the Lattice temporarily (if it is paged to disk).
CountedPtr< Lattice< T > > itsLatticePtr
void deleteTable()
Make sure that the temporary table gets deleted.
IPosition doNiceCursorShape(uInt maxPixels)
Get the best cursor shape.
Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
void apply(T(*function)(const T &))
void set(const T &value)
Set all of the elements in the Lattice to the given value.
void putAt(const T &value, const IPosition &where)
uInt maximumCacheSize() const
Maximum size - not necessarily all used.
TempLatticeImpl()
The default constructor creates a TempLatticeImpl containing a default ArrayLattice object.
TempLatticeImpl(const TempLatticeImpl< T > &other)
The copy constructor cannot be used.
void apply(const Functional< T, T > &function)
Bool ok() const
Check class internals - used for debugging.
TempLatticeImpl(const TiledShape &shape, Double maxMemoryInMB)
void showCacheStatistics(ostream &os) const
Report on cache success.
uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
TempLatticeImpl< T > & operator=(const TempLatticeImpl< T > &other)
The assignment operator cannot be used.
void doReopen() const
Do the reopen of the table (if not open already).
T getAt(const IPosition &where) const
Get or put a single element in the lattice.
~TempLatticeImpl()
The destructor removes the Lattice from memory and if necessary disk.
TempLatticeImpl(const TiledShape &shape, Int maxMemoryInMB)
Create a TempLatticeImpl of the specified shape.
void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
void apply(T(*function)(T))
Replace every element, x, of the Lattice with the result of f(x).
void reopen()
If needed, reopen a temporarily closed TempLatticeImpl.
void tempReopen() const
Do the actual reopen of the temporarily closed table (if not open already).
Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
Bool isPaged() const
Is the TempLattice paged to disk?
void flush()
Flush the data.
IPosition shape() const
Return the shape of the Lattice including all degenerate axes.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55