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.
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
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
virtual Bool isWritable() const
Is the TempLattice writable? It should be.
virtual Lattice< T > * clone() const
Make a copy of the object (reference semantics).
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
virtual void reopen()
If needed, reopen a temporarily closed TempLattice.
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
virtual Bool ok() const
Check class internals - used for debugging.
virtual void apply(T(*function)(const T &))
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual void apply(const Functional< T, T > &function)
CountedPtr< TempLatticeImpl< T > > itsImpl
Definition: TempLattice.h:273
virtual void tempClose()
Close the Lattice temporarily (if it is paged to disk).
virtual IPosition shape() const
Return the shape of the Lattice including all degenerate axes.
TempLattice(const TempLattice< T > &other)
The copy constructor uses reference semantics.
Definition: TempLattice.h:157
TempLattice(const TiledShape &shape, Int maxMemoryInMB=-1)
Create a TempLattice of the specified shape.
Definition: TempLattice.h:147
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
TempLattice< T > & operator=(const TempLattice< T > &other)
The assignment operator with reference semantics.
Definition: TempLattice.h:165
virtual Bool isPaged() const
Is the TempLattice paged to disk?
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
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...
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
virtual void apply(T(*function)(T))
Replace every element, x, of the Lattice with the result of f(x).
virtual ~TempLattice()
The destructor removes the Lattice from memory and if necessary disk.
TempLattice(const TiledShape &shape, Double maxMemoryInMB)
Definition: TempLattice.h:149
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
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.
virtual void set(const T &value)
Set all of the elements in the Lattice to the given value.
virtual void flush()
Flush the data.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
TempLattice()
The default constructor creates a TempLattice containing a default ArrayLattice object.
Definition: TempLattice.h:137
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.
double Double
Definition: aipstype.h:55