00001 //# TempLattice.h: A Lattice that can be used for temporary storage 00002 //# Copyright (C) 1997,1998,1999,2000,2003 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# 00027 //# $Id$ 00028 00029 #ifndef LATTICES_TEMPLATTICE_H 00030 #define LATTICES_TEMPLATTICE_H 00031 00032 00033 //# Includes 00034 #include <casacore/casa/aips.h> 00035 #include <casacore/lattices/Lattices/TempLatticeImpl.h> 00036 #include <casacore/casa/Utilities/CountedPtr.h> 00037 00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00039 00040 00041 // <summary> 00042 // A Lattice that can be used for temporary storage 00043 // </summary> 00044 00045 // <use visibility=export> 00046 00047 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTempLattice.cc" demos=""> 00048 // </reviewed> 00049 00050 // <prerequisite> 00051 // <li> <linkto class="Lattice">Lattice</linkto> 00052 // <li> <linkto class="ArrayLattice">ArrayLattice</linkto> 00053 // <li> <linkto class="PagedArray">PagedArray</linkto> 00054 // </prerequisite> 00055 00056 // <etymology> 00057 // A TempLattice disappears from both memory and disk when it goes out of 00058 // scope. Hence it is only useful for temporary storage of data. 00059 // </etymology> 00060 00061 // <synopsis> 00062 // Lattice classes are designed to allow the memory-efficient handling of large 00063 // amounts of data. But they can also used with much smaller arrays. With 00064 // large amounts of data the <linkto class="PagedArray">PagedArray</linkto> 00065 // class should be used, as this will store the data on disk and efficiently 00066 // access specified portions of the data on request. With small amounts of 00067 // data the <linkto class="ArrayLattice">ArrayLattice</linkto> class should be 00068 // used as all the data is always in memory avoiding the I/O associated with 00069 // PagedArrays. 00070 // <p> 00071 // Applications often cannot predict until run time whether they will 00072 // be dealing with a large or small amount of data. So the use of a 00073 // PagedArray or an ArrayLattice cannot be made until the size of the arrays 00074 // are known. TempLattice makes this decision given the size of the Array. To 00075 // help in making a good choice the TempLattice class also examines how much 00076 // memory the operating system has (using an aipsrc variable) and compares 00077 // it with the size of the requested Array. 00078 // <p> 00079 // The algorithm currently used is: create an ArrayLattice if the size of the 00080 // array is less than a quarter of the total system memory; otherwise a 00081 // PagedArray is created. The PagedArray is stored in the current 00082 // working directory and given a unique name that contains the string 00083 // "pagedArray". This pagedArray will be deleted once the TempLattice goes out 00084 // of scope. So unlike PagedArrays which can be made to exist longer than the 00085 // time they are used by a process, the PagedArrays created by the 00086 // TempLattice class are always scratch arrays. 00087 // <p> 00088 // It is possible to temporarily close a TempLattice, which only takes effect 00089 // when it is created as a PagedArray. In this way it is possible to reduce 00090 // the number of open files in case a lot of TempLattice objects are used. 00091 // A temporarily closed TempLattice will be reopened automatically when needed. 00092 // It can also be reopened explicitly. 00093 // <p> 00094 // You can force the TempLattice to be disk based by setting the memory 00095 // argument in the constructors to 0 00096 // <p> 00097 // TempLattice is implemented using TempLatticeImpl for reasons explained 00098 // in that class. 00099 // </synopsis> 00100 00101 // <example> 00102 // <srcblock> 00103 // // Create a temporary lattice and initialize to 0. 00104 // TempLattice<Float> myLat (IPosition(2,1024,1024)); 00105 // myLat.set (0.); 00106 // // Temporarily close the lattice. 00107 // myLat.tempClose(); 00108 // // Do an operation, which will automatically reopen the lattice. 00109 // myLat.set (1.); 00110 // // Note that the destructor deletes the table (if the TempLattice 00111 // // was created on disk). 00112 // </srcblock> 00113 // </example> 00114 00115 // <motivation> 00116 // I needed a temporary Lattice when converting the Convolver class to using 00117 // Lattices. This was to store the Transfer function. 00118 // </motivation> 00119 00120 // <templating arg=T> 00121 // <li> Any type that can be used by the Lattices can also be used by 00122 // this class. 00123 // </templating> 00124 00125 //# <todo asof="yyyy/mm/dd"> 00126 //# <li> add this feature 00127 //# <li> fix this bug 00128 //# <li> start discussion of this possible extension 00129 //# </todo> 00130 00131 00132 template<class T> class TempLattice : public Lattice<T> 00133 { 00134 public: 00135 // The default constructor creates a TempLattice containing a 00136 // default ArrayLattice object. 00137 TempLattice() 00138 : itsImpl (new TempLatticeImpl<T>()) {} 00139 00140 // Create a TempLattice of the specified shape. You can specify how much 00141 // memory the Lattice can consume before it becomes disk based by giving a 00142 // non-negative value to the maxMemoryInMB argument. Otherwise it will assume 00143 // it can use up to 25% of the memory on your machine as defined in aipsrc 00144 // (this algorithm may change). Setting maxMemoryInMB to zero will force 00145 // the lattice to disk. 00146 // <group> 00147 explicit TempLattice (const TiledShape& shape, Int maxMemoryInMB=-1) 00148 : itsImpl (new TempLatticeImpl<T>(shape, maxMemoryInMB)) {} 00149 TempLattice (const TiledShape& shape, Double maxMemoryInMB) 00150 : itsImpl (new TempLatticeImpl<T>(shape, maxMemoryInMB)) {} 00151 // </group> 00152 00153 // The copy constructor uses reference semantics. ie modifying data in the 00154 // copied TempLattice also modifies the data in the original TempLattice. 00155 // Passing by value doesn't make sense, because it may require the creation 00156 // of a temporary (but possibly huge) file on disk. 00157 TempLattice (const TempLattice<T>& other) 00158 : Lattice<T>(other), itsImpl (other.itsImpl) {} 00159 00160 // The destructor removes the Lattice from memory and if necessary disk. 00161 virtual ~TempLattice(); 00162 00163 // The assignment operator with reference semantics. As with the copy 00164 // constructor assigning by value does not make sense. 00165 TempLattice<T>& operator= (const TempLattice<T>& other) 00166 { itsImpl = other.itsImpl; } 00167 00168 // Make a copy of the object (reference semantics). 00169 virtual Lattice<T>* clone() const; 00170 00171 // Is the TempLattice paged to disk? 00172 virtual Bool isPaged() const; 00173 00174 // Can the lattice data be referenced as an array section? 00175 virtual Bool canReferenceArray() const; 00176 00177 // Is the TempLattice writable? It should be. 00178 virtual Bool isWritable() const; 00179 00180 // Flush the data. 00181 virtual void flush(); 00182 00183 // Close the Lattice temporarily (if it is paged to disk). 00184 // It'll be reopened automatically when needed or when 00185 // <src>reopen</src> is called explicitly. 00186 virtual void tempClose(); 00187 00188 // If needed, reopen a temporarily closed TempLattice. 00189 virtual void reopen(); 00190 00191 // Return the shape of the Lattice including all degenerate axes. 00192 // (ie. axes with a length of one) 00193 virtual IPosition shape() const; 00194 00195 // Set all of the elements in the Lattice to the given value. 00196 virtual void set (const T& value); 00197 00198 // Replace every element, x, of the Lattice with the result of f(x). You 00199 // must pass in the address of the function -- so the function must be 00200 // declared and defined in the scope of your program. All versions of 00201 // apply require a function that accepts a single argument of type T (the 00202 // Lattice template type) and return a result of the same type. The first 00203 // apply expects a function with an argument passed by value; the second 00204 // expects the argument to be passed by const reference; the third 00205 // requires an instance of the class <src>Functional<T,T></src>. The 00206 // first form ought to run faster for the built-in types, which may be an 00207 // issue for large Lattices stored in memory, where disk access is not an 00208 // issue. 00209 // <group> 00210 virtual void apply (T (*function)(T)); 00211 virtual void apply (T (*function)(const T&)); 00212 virtual void apply (const Functional<T,T>& function); 00213 // </group> 00214 00215 // This function returns the recommended maximum number of pixels to 00216 // include in the cursor of an iterator. 00217 virtual uInt advisedMaxPixels() const; 00218 00219 // Get the best cursor shape. 00220 virtual IPosition doNiceCursorShape (uInt maxPixels) const; 00221 00222 // Maximum size - not necessarily all used. In pixels. 00223 virtual uInt maximumCacheSize() const; 00224 00225 // Set the maximum (allowed) cache size as indicated. 00226 virtual void setMaximumCacheSize (uInt howManyPixels); 00227 00228 // Set the cache size as to "fit" the indicated path. 00229 virtual void setCacheSizeFromPath (const IPosition& sliceShape, 00230 const IPosition& windowStart, 00231 const IPosition& windowLength, 00232 const IPosition& axisPath); 00233 00234 // Set the actual cache size for this Array to be be big enough for the 00235 // indicated number of tiles. This cache is not shared with PagedArrays 00236 // in other rows and is always clipped to be less than the maximum value 00237 // set using the setMaximumCacheSize member function. 00238 // tiles. Tiles are cached using a first in first out algorithm. 00239 virtual void setCacheSizeInTiles (uInt howManyTiles); 00240 00241 // Clears and frees up the caches, but the maximum allowed cache size is 00242 // unchanged from when setCacheSize was called 00243 virtual void clearCache(); 00244 00245 // Report on cache success. 00246 virtual void showCacheStatistics (ostream& os) const; 00247 00248 // Get or put a single element in the lattice. 00249 // Note that Lattice::operator() can also be used to get a single element. 00250 // <group> 00251 virtual T getAt (const IPosition& where) const; 00252 virtual void putAt (const T& value, const IPosition& where); 00253 // </group> 00254 00255 // Check class internals - used for debugging. Should always return True 00256 virtual Bool ok() const; 00257 00258 // This function is used by the LatticeIterator class to generate an 00259 // iterator of the correct type for this Lattice. Not recommended 00260 // for general use. 00261 virtual LatticeIterInterface<T>* makeIter (const LatticeNavigator& navigator, 00262 Bool useRef) const; 00263 00264 // Do the actual getting of an array of values. 00265 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section); 00266 00267 // Do the actual getting of an array of values. 00268 virtual void doPutSlice (const Array<T>& sourceBuffer, 00269 const IPosition& where, 00270 const IPosition& stride); 00271 00272 private: 00273 CountedPtr<TempLatticeImpl<T> > itsImpl; 00274 }; 00275 00276 00277 00278 } //# NAMESPACE CASACORE - END 00279 00280 #ifndef CASACORE_NO_AUTO_TEMPLATES 00281 #include <casacore/lattices/Lattices/TempLattice.tcc> 00282 #endif //# CASACORE_NO_AUTO_TEMPLATES 00283 #endif