TempLattice.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1