casacore
TempLattice.h
Go to the documentation of this file.
1 //# TempLattice.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$
28 
29 #ifndef LATTICES_TEMPLATTICE_H
30 #define LATTICES_TEMPLATTICE_H
31 
32 
33 //# Includes
34 #include <casacore/casa/aips.h>
35 #include <casacore/lattices/Lattices/TempLatticeImpl.h>
36 #include <casacore/casa/Utilities/CountedPtr.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 
41 // <summary>
42 // A Lattice that can be used for temporary storage
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTempLattice.cc" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto class="Lattice">Lattice</linkto>
52 // <li> <linkto class="ArrayLattice">ArrayLattice</linkto>
53 // <li> <linkto class="PagedArray">PagedArray</linkto>
54 // </prerequisite>
55 
56 // <etymology>
57 // A TempLattice disappears from both memory and disk when it goes out of
58 // scope. Hence it is only useful for temporary storage of data.
59 // </etymology>
60 
61 // <synopsis>
62 // Lattice classes are designed to allow the memory-efficient handling of large
63 // amounts of data. But they can also used with much smaller arrays. With
64 // large amounts of data the <linkto class="PagedArray">PagedArray</linkto>
65 // class should be used, as this will store the data on disk and efficiently
66 // access specified portions of the data on request. With small amounts of
67 // data the <linkto class="ArrayLattice">ArrayLattice</linkto> class should be
68 // used as all the data is always in memory avoiding the I/O associated with
69 // PagedArrays.
70 // <p>
71 // Applications often cannot predict until run time whether they will
72 // be dealing with a large or small amount of data. So the use of a
73 // PagedArray or an ArrayLattice cannot be made until the size of the arrays
74 // are known. TempLattice makes this decision given the size of the Array. To
75 // help in making a good choice the TempLattice class also examines how much
76 // memory the operating system has (using an aipsrc variable) and compares
77 // it with the size of the requested Array.
78 // <p>
79 // The algorithm currently used is: create an ArrayLattice if the size of the
80 // array is less than a quarter of the total system memory; otherwise a
81 // PagedArray is created. The PagedArray is stored in the current
82 // working directory and given a unique name that contains the string
83 // "pagedArray". This pagedArray will be deleted once the TempLattice goes out
84 // of scope. So unlike PagedArrays which can be made to exist longer than the
85 // time they are used by a process, the PagedArrays created by the
86 // TempLattice class are always scratch arrays.
87 // <p>
88 // It is possible to temporarily close a TempLattice, which only takes effect
89 // when it is created as a PagedArray. In this way it is possible to reduce
90 // the number of open files in case a lot of TempLattice objects are used.
91 // A temporarily closed TempLattice will be reopened automatically when needed.
92 // It can also be reopened explicitly.
93 // <p>
94 // You can force the TempLattice to be disk based by setting the memory
95 // argument in the constructors to 0
96 // <p>
97 // TempLattice is implemented using TempLatticeImpl for reasons explained
98 // in that class.
99 // </synopsis>
100 
101 // <example>
102 // <srcblock>
103 // // Create a temporary lattice and initialize to 0.
104 // TempLattice<Float> myLat (IPosition(2,1024,1024));
105 // myLat.set (0.);
106 // // Temporarily close the lattice.
107 // myLat.tempClose();
108 // // Do an operation, which will automatically reopen the lattice.
109 // myLat.set (1.);
110 // // Note that the destructor deletes the table (if the TempLattice
111 // // was created on disk).
112 // </srcblock>
113 // </example>
114 
115 // <motivation>
116 // I needed a temporary Lattice when converting the Convolver class to using
117 // Lattices. This was to store the Transfer function.
118 // </motivation>
119 
120 // <templating arg=T>
121 // <li> Any type that can be used by the Lattices can also be used by
122 // this class.
123 // </templating>
124 
125 //# <todo asof="yyyy/mm/dd">
126 //# <li> add this feature
127 //# <li> fix this bug
128 //# <li> start discussion of this possible extension
129 //# </todo>
130 
131 
132 template<class T> class TempLattice : public Lattice<T>
133 {
134 public:
135  // The default constructor creates a TempLattice containing a
136  // default ArrayLattice object.
138  : itsImpl (new TempLatticeImpl<T>()) {}
139 
140  // Create a TempLattice of the specified shape. You can specify how much
141  // memory the Lattice can consume before it becomes disk based by giving a
142  // non-negative value to the maxMemoryInMB argument. Otherwise it will assume
143  // it can use up to 25% of the memory on your machine as defined in aipsrc
144  // (this algorithm may change). Setting maxMemoryInMB to zero will force
145  // the lattice to disk.
146  // <group>
147  explicit TempLattice (const TiledShape& shape, Int maxMemoryInMB=-1)
148  : itsImpl (new TempLatticeImpl<T>(shape, maxMemoryInMB)) {}
149  TempLattice (const TiledShape& shape, Double maxMemoryInMB)
150  : itsImpl (new TempLatticeImpl<T>(shape, maxMemoryInMB)) {}
151  // </group>
152 
153  // The copy constructor uses reference semantics. ie modifying data in the
154  // copied TempLattice also modifies the data in the original TempLattice.
155  // Passing by value doesn't make sense, because it may require the creation
156  // of a temporary (but possibly huge) file on disk.
158  : Lattice<T>(other), itsImpl (other.itsImpl) {}
159 
160  // The destructor removes the Lattice from memory and if necessary disk.
161  virtual ~TempLattice();
162 
163  // The assignment operator with reference semantics. As with the copy
164  // constructor assigning by value does not make sense.
166  { itsImpl = other.itsImpl; }
167 
168  // Make a copy of the object (reference semantics).
169  virtual Lattice<T>* clone() const;
170 
171  // Is the TempLattice paged to disk?
172  virtual Bool isPaged() const;
173 
174  // Can the lattice data be referenced as an array section?
175  virtual Bool canReferenceArray() const;
176 
177  // Is the TempLattice writable? It should be.
178  virtual Bool isWritable() const;
179 
180  // Flush the data.
181  virtual void flush();
182 
183  // Close the Lattice temporarily (if it is paged to disk).
184  // It'll be reopened automatically when needed or when
185  // <src>reopen</src> is called explicitly.
186  virtual void tempClose();
187 
188  // If needed, reopen a temporarily closed TempLattice.
189  virtual void reopen();
190 
191  // Return the shape of the Lattice including all degenerate axes.
192  // (ie. axes with a length of one)
193  virtual IPosition shape() const;
194 
195  // Set all of the elements in the Lattice to the given value.
196  virtual void set (const T& value);
197 
198  // Replace every element, x, of the Lattice with the result of f(x). You
199  // must pass in the address of the function -- so the function must be
200  // declared and defined in the scope of your program. All versions of
201  // apply require a function that accepts a single argument of type T (the
202  // Lattice template type) and return a result of the same type. The first
203  // apply expects a function with an argument passed by value; the second
204  // expects the argument to be passed by const reference; the third
205  // requires an instance of the class <src>Functional<T,T></src>. The
206  // first form ought to run faster for the built-in types, which may be an
207  // issue for large Lattices stored in memory, where disk access is not an
208  // issue.
209  // <group>
210  virtual void apply (T (*function)(T));
211  virtual void apply (T (*function)(const T&));
212  virtual void apply (const Functional<T,T>& function);
213  // </group>
214 
215  // This function returns the recommended maximum number of pixels to
216  // include in the cursor of an iterator.
217  virtual uInt advisedMaxPixels() const;
218 
219  // Get the best cursor shape.
220  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
221 
222  // Maximum size - not necessarily all used. In pixels.
223  virtual uInt maximumCacheSize() const;
224 
225  // Set the maximum (allowed) cache size as indicated.
226  virtual void setMaximumCacheSize (uInt howManyPixels);
227 
228  // Set the cache size as to "fit" the indicated path.
229  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
230  const IPosition& windowStart,
231  const IPosition& windowLength,
232  const IPosition& axisPath);
233 
234  // Set the actual cache size for this Array to be be big enough for the
235  // indicated number of tiles. This cache is not shared with PagedArrays
236  // in other rows and is always clipped to be less than the maximum value
237  // set using the setMaximumCacheSize member function.
238  // tiles. Tiles are cached using a first in first out algorithm.
239  virtual void setCacheSizeInTiles (uInt howManyTiles);
240 
241  // Clears and frees up the caches, but the maximum allowed cache size is
242  // unchanged from when setCacheSize was called
243  virtual void clearCache();
244 
245  // Report on cache success.
246  virtual void showCacheStatistics (ostream& os) const;
247 
248  // Get or put a single element in the lattice.
249  // Note that Lattice::operator() can also be used to get a single element.
250  // <group>
251  virtual T getAt (const IPosition& where) const;
252  virtual void putAt (const T& value, const IPosition& where);
253  // </group>
254 
255  // Check class internals - used for debugging. Should always return True
256  virtual Bool ok() const;
257 
258  // This function is used by the LatticeIterator class to generate an
259  // iterator of the correct type for this Lattice. Not recommended
260  // for general use.
261  virtual LatticeIterInterface<T>* makeIter (const LatticeNavigator& navigator,
262  Bool useRef) const;
263 
264  // Do the actual getting of an array of values.
265  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
266 
267  // Do the actual getting of an array of values.
268  virtual void doPutSlice (const Array<T>& sourceBuffer,
269  const IPosition& where,
270  const IPosition& stride);
271 
272 private:
274 };
275 
276 
277 
278 } //# NAMESPACE CASACORE - END
279 
280 #ifndef CASACORE_NO_AUTO_TEMPLATES
281 #include <casacore/lattices/Lattices/TempLattice.tcc>
282 #endif //# CASACORE_NO_AUTO_TEMPLATES
283 #endif
casacore::Slicer
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
casacore::TempLattice::TempLattice
TempLattice(const TiledShape &shape, Int maxMemoryInMB=-1)
Create a TempLattice of the specified shape.
Definition: TempLattice.h:147
casacore::TempLattice::~TempLattice
virtual ~TempLattice()
The destructor removes the Lattice from memory and if necessary disk.
casacore::TempLattice::setCacheSizeFromPath
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
casacore::TempLattice::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
casacore::TempLattice::clone
virtual Lattice< T > * clone() const
Make a copy of the object (reference semantics).
casacore::TempLattice::tempClose
virtual void tempClose()
Close the Lattice temporarily (if it is paged to disk).
casacore::CountedPtr
Referenced counted pointer for constant data.
Definition: CountedPtr.h:80
casacore::TempLattice::isPaged
virtual Bool isPaged() const
Is the TempLattice paged to disk?
casacore::TempLattice::flush
virtual void flush()
Flush the data.
casacore::Functional
Map a domain object into a range object via operator().
Definition: Array.h:53
casacore::TempLattice::reopen
virtual void reopen()
If needed, reopen a temporarily closed TempLattice.
casacore::TempLattice::getAt
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
casacore::TempLattice::apply
virtual void apply(T(*function)(T))
Replace every element, x, of the Lattice with the result of f(x).
casacore::TempLattice::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
casacore::TempLattice::TempLattice
TempLattice()
The default constructor creates a TempLattice containing a default ArrayLattice object.
Definition: TempLattice.h:137
casacore::TempLattice::shape
virtual IPosition shape() const
Return the shape of the Lattice including all degenerate axes.
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::Double
double Double
Definition: aipstype.h:55
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::TempLattice::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
casacore::TempLattice
A Lattice that can be used for temporary storage.
Definition: LatticeCleaner.h:44
casacore::TempLattice::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::TempLattice::doGetSlice
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
casacore::TempLattice::makeIter
virtual 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...
casacore::TempLattice::operator=
TempLattice< T > & operator=(const TempLattice< T > &other)
The assignment operator with reference semantics.
Definition: TempLattice.h:165
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::TempLattice::putAt
virtual void putAt(const T &value, const IPosition &where)
casacore::TempLattice::setCacheSizeInTiles
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
casacore::TempLattice::TempLattice
TempLattice(const TiledShape &shape, Double maxMemoryInMB)
Definition: TempLattice.h:149
casacore::TempLatticeImpl
The class implementing TempLattice.
Definition: TempLatticeImpl.h:69
casacore::TempLattice::ok
virtual Bool ok() const
Check class internals - used for debugging.
casacore::TempLattice::set
virtual void set(const T &value)
Set all of the elements in the Lattice to the given value.
casacore::TempLattice::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
casacore::Lattice
A templated, abstract base class for array-like objects.
Definition: Functional.h:37
casacore::Array
template <class T, class U> class vector;
Definition: Array.h:166
casacore::TempLattice::doPutSlice
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::TempLattice::canReferenceArray
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
casacore::TempLattice::isWritable
virtual Bool isWritable() const
Is the TempLattice writable? It should be.
casacore::TiledShape
Define the shape and tile shape.
Definition: TiledShape.h:99
casacore::TempLattice::TempLattice
TempLattice(const TempLattice< T > &other)
The copy constructor uses reference semantics.
Definition: TempLattice.h:157
casacore::TempLattice::itsImpl
CountedPtr< TempLatticeImpl< T > > itsImpl
Definition: TempLattice.h:273
casacore::LatticeIterInterface
A base class for Lattice iterators.
Definition: ImageExpr.h:47
casacore::TempLattice::advisedMaxPixels
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...