casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
LatticeCache.h
Go to the documentation of this file.
00001 //# LatticeCache: Cache for accessing a Lattice in Tiles
00002 //# Copyright (C) 1995,1996,1997,1999,2000,2001
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 //# $Id: LatticeCache.h 20403 2008-09-15 07:02:01Z gervandiepen $
00027 
00028 #ifndef LATTICES_LATTICECACHE_H
00029 #define LATTICES_LATTICECACHE_H
00030 
00031 
00032 //# Includes
00033 #include <casa/aips.h>
00034 #include <casa/Arrays/Array.h>
00035 #include <casa/Arrays/Vector.h>
00036 
00037 //# Forward Declarations
00038 #include <casa/iosfwd.h>
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 template <class T> class Block;
00042 template <class T> class Lattice;
00043 
00044 // <summary> a class for caching image access via tiles</summary>
00045 //
00046 // <use visibility=export>
00047 //
00048 // <reviewed reviewer="" date="" tests="" demos="">
00049 // </reviewed>
00050 //
00051 // <prerequisite>
00052 //   <li> <linkto class=Lattice>Lattice</linkto>
00053 // </prerequisite>
00054 //
00055 // <etymology>
00056 // This class divides an image into Tiles that are stored in
00057 // a Cache.
00058 // </etymology>
00059 //
00060 // <synopsis> 
00061 // An image is divided into tiles of a specified shape. Access to the
00062 // image pixels is via these tiles. A cache of active tiles is kept
00063 // in memory up to a specified limit in memory allocation. Tiles
00064 // are flushed to disk using a Least-Recently-Used Criterion.
00065 //
00066 // The tile size specified is the maximum dimension. Near the edge,
00067 // smaller tiles are returned if necessary.
00068 //
00069 // The offset needed to get back to true pixels is also available.
00070 //
00071 // The cache hit rate for a sufficient number of random accesses
00072 // goes as the ratio of cache size to image size.
00073 //
00074 // Tiles may be overlapped. If there is any overlap then the
00075 // caller is responsible for dealing with the overlap. Normally
00076 // one will only want overlapping windows for additive operations
00077 // in which case the additive flag to the constructor should be 
00078 // used.
00079 // </synopsis>
00080 //
00081 // <example>
00082 // <srcblock>
00083 // </srcblock>
00084 //
00085 // </example>
00086 //
00087 // <motivation> 
00088 // To aid in gridding
00089 // </motivation>
00090 //
00091 // <todo asof="1997/02/27">
00092 // </todo>
00093 
00094 template <class T> class LatticeCache 
00095 {
00096 public:
00097 
00098   // Constructor: cachesize in units of T. tileOverlap is the fractional
00099   // overlap between neighbouring tile. 
00100   LatticeCache(Lattice<T> &image, Int cacheSize, IPosition tileShape,
00101                Vector<Float>& tileOverlap, Bool additive);
00102 
00103   LatticeCache(const LatticeCache<T> & other);
00104 
00105   LatticeCache<T> &operator=(const LatticeCache<T> & other);
00106 
00107   virtual ~LatticeCache();
00108 
00109   // Return the tile for a given location
00110   // <group>
00111   Array<T>& tile(IPosition& cacheLoc, const IPosition& tileLoc, Bool discard=True);
00112   Array<T>& tile(const IPosition& tileLoc, Bool discard=True);
00113   // </group>
00114 
00115   // const version is needed
00116   const Array<T>& tile(const IPosition& tileLoc);
00117 
00118   // Return the IPosition for the start of this tile
00119   IPosition& cacheLocation(IPosition& cacheLoc, const IPosition& tileLoc);
00120 
00121   // Show the statistics of cache access
00122   virtual void showCacheStatistics(ostream& os);
00123 
00124   // Clear the statistics of cache access
00125   virtual void clearCacheStatistics();
00126 
00127   // Flush contents
00128   virtual void flush();
00129 
00130 protected:
00131 
00132   LatticeCache() {};
00133 
00134   Int numberTiles;
00135   IPosition tileShape;
00136   Vector<Int> tileShapeVec, tileOffsetVec;
00137   Vector<Float> tileOverlap;
00138   Bool additive;
00139 
00140   Int cacheSize;
00141   Int cacheAccesses;
00142   Int cacheHits;
00143   Int cacheMisses;
00144   Int cacheReads;
00145   Int cacheWrites;
00146 
00147   Int getFreeTile(Bool readonly);
00148 
00149   Block<IPosition> tileLocs;
00150   Block<Int> tileSequence;
00151   Block<Array<T> > tileContents;
00152 
00153   void writeTile(Int tile);
00154   void readTile(Int tile, Bool readonly);
00155 
00156   Lattice<T>* image_p;
00157 };
00158 
00159 
00160 } //# NAMESPACE CASA - END
00161 
00162 #ifndef CASACORE_NO_AUTO_TEMPLATES
00163 #include <lattices/Lattices/LatticeCache.tcc>
00164 #endif //# CASACORE_NO_AUTO_TEMPLATES
00165 #endif