00001 //# LatticeBase.h: A non-templated, abstract base class for array-like classes 00002 //# Copyright (C) 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 //# $Id$ 00027 00028 #ifndef LATTICES_LATTICEBASE_H 00029 #define LATTICES_LATTICEBASE_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/lattices/LEL/LELCoordinates.h> 00035 #include <casacore/casa/Arrays/IPosition.h> 00036 #include <casacore/casa/Utilities/DataType.h> 00037 #include <casacore/casa/IO/FileLocker.h> 00038 #include <casacore/casa/BasicSL/String.h> 00039 00040 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00041 00042 //# Forward Declarations 00043 class LogIO; 00044 00045 00046 // <summary> 00047 // A non-templated, abstract base class for array-like objects. 00048 // </summary> 00049 00050 // <use visibility=export> 00051 00052 // <reviewed reviewer="Bob Garwood" date="2000/01/18" tests="tArrayLattice.cc" demos="dLattice.cc"> 00053 // </reviewed> 00054 00055 // <synopsis> 00056 // This pure abstract base class defines the operations which may be 00057 // performed on a lattice of any type. 00058 // <br>See class <linkto class=Lattice>Lattice</linkto> for a detailed 00059 // description of a lattice. 00060 // </synopsis> 00061 00062 // <motivation> 00063 // It is very useful to be able to keep a pointer to a 00064 // non-templated base class. Furthermore it gives the opportunity to 00065 // factor out some non-templated code. 00066 // </motivation> 00067 00068 // <note> 00069 // The cache functions (maximumCacheSize, setMaximumCacheSize, 00070 // setCacheSizeInTiles, setCacheSizeFromPath, clearCache, and 00071 // showCacheStatistics) should all be over-ridden together as 00072 // in PagedArray. 00073 // </note> 00074 // 00075 //# <todo asof="1999/02/04"> 00076 //# <li> 00077 //# </todo> 00078 00079 00080 class LatticeBase 00081 { 00082 public: 00083 // A virtual destructor is needed so that it will use the actual destructor 00084 // in the derived class. 00085 virtual ~LatticeBase(); 00086 00087 // Make a copy of the derived object (reference semantics). 00088 virtual LatticeBase* clone() const = 0; 00089 00090 // Get the image type (returns name of derived class). 00091 // The default implementation returns "Lattice". 00092 // Note it is made pure virtual in ImageInterface. 00093 virtual String imageType() const; 00094 00095 // Get the data type of the lattice. 00096 virtual DataType dataType() const = 0; 00097 00098 // Is the lattice persistent and can it be loaded by other processes as well? 00099 // That is the case for a PagedArray or PagedImage and for an ImageExpr 00100 // which does not use transient lattices or regions. 00101 // <br>The default implementation returns False. 00102 virtual Bool isPersistent() const; 00103 00104 // Is the lattice paged to disk? 00105 // <br>The default implementation returns False. 00106 virtual Bool isPaged() const; 00107 00108 // Can the lattice data be referenced as an array section? 00109 // That is the case for an ArrayLattice or a Temp/SubLattice using it. 00110 // It is used by LatticeIterInterface. 00111 // <br>The default implementation returns False. 00112 virtual Bool canReferenceArray() const; 00113 00114 // Is the lattice writable? 00115 // <br>The default implementation returns True. 00116 virtual Bool isWritable() const; 00117 00118 // Save the image in an AipsIO file with the given name. 00119 // Its purpose is to make ImageConcat and ImageExpr objects 00120 // persistent. 00121 // <br>The default implementation throws an exception. 00122 virtual void save (const String& fileName) const; 00123 00124 // It is strongly recommended to use class 00125 // <linkto class=LatticeLocker>LatticeLocker</linkto> to 00126 // handle lattice locking. It also contains a more detailed 00127 // explanation of the locking process. 00128 // <br>By default the functions do not do anything at all. 00129 // lock() and hasLock return True, which is suitable for all 00130 // non-paged lattices. 00131 // <group> 00132 virtual Bool lock (FileLocker::LockType, uInt nattempts); 00133 virtual void unlock(); 00134 virtual Bool hasLock (FileLocker::LockType) const; 00135 // </group> 00136 00137 // Resynchronize the Lattice object with the lattice file. 00138 // This function is only useful if no read-locking is used, ie. 00139 // if the table lock option is UserNoReadLocking or AutoNoReadLocking. 00140 // In that cases the table system does not acquire a read-lock, thus 00141 // does not synchronize itself automatically. 00142 // <br>By default the function does not do anything at all. 00143 virtual void resync(); 00144 00145 // Flush the data (but do not unlock). 00146 // <br>By default the function does not do anything at all. 00147 virtual void flush(); 00148 00149 // Temporarily close the lattice. 00150 // It will be reopened automatically on the next access. 00151 // <br>By default the function does not do anything at all. 00152 virtual void tempClose(); 00153 00154 // Explicitly reopen the temporarily closed lattice. 00155 // <br>By default the function does not do anything at all. 00156 virtual void reopen(); 00157 00158 // Return the name of the current Lattice object. This will generally 00159 // be a file name for lattices that have a persistent form. Any path 00160 // before the actual file name can be optionally stripped off. 00161 // <br>The default implementation returns an empty string. 00162 virtual String name (Bool stripPath=False) const; 00163 00164 // Return the shape of the Lattice including all degenerate axes 00165 // (ie. axes with a length of one) 00166 virtual IPosition shape() const = 0; 00167 00168 // Return the number of axes in this Lattice. This includes all 00169 // degenerate axes. 00170 // <br>The default implementation returns shape().nelements(). 00171 virtual uInt ndim() const; 00172 00173 // Return the total number of elements in this Lattice. 00174 // <br>The default implementation returns shape().product(). 00175 // <group> 00176 virtual size_t nelements() const; 00177 size_t size() const 00178 { return nelements(); } 00179 // </group> 00180 00181 // Return a value of "True" if this instance of Lattice and 'other' have 00182 // the same shape, otherwise returns a value of "False". 00183 Bool conform (const LatticeBase& other) const 00184 { return shape().isEqual (other.shape()); } 00185 00186 // Return the coordinates of the lattice. 00187 // <br>The default implementation returns an 'empty' LELLattCoord object. 00188 virtual LELCoordinates lelCoordinates() const; 00189 00190 // This function returns the recommended maximum number of pixels to 00191 // include in the cursor of an iterator. The Lattice class has a default 00192 // implementation which returns a number that is a power of two and 00193 // includes enough pixels to consume between 4 and 8 MBytes of memory. 00194 virtual uInt advisedMaxPixels() const = 0; 00195 00196 // Returns a recommended cursor shape for iterating through all the pixels 00197 // in the Lattice. The default implementation sets up a shape that 00198 // completely fills as many axes as possible, but always at least the 00199 // first axis. For example, given a 10x20x30 Lattice 00200 // <srcblock> 00201 // maxPixels = 1 --> niceCursorShape = [10,1,1] 00202 // 100 --> niceCursorShape = [10,1,1] 00203 // 300 --> niceCursorShape = [10,20,1] 00204 // 10000 --> niceCursorShape = [10,20,30] 00205 // </srcblock> 00206 // The default argument is the result of <src>advisedMaxPixels()</src>. 00207 // <group> 00208 IPosition niceCursorShape (uInt maxPixels) const 00209 { return doNiceCursorShape (maxPixels); } 00210 IPosition niceCursorShape() const 00211 { return doNiceCursorShape (advisedMaxPixels()); } 00212 // </group> 00213 00214 // Check class internals - used for debugging. Should always return True 00215 virtual Bool ok() const; 00216 00217 // The function (in the derived classes) doing the actual work. 00218 // This function is public, so it can be used internally in the 00219 // various Lattice classes. 00220 // <br>The default implementation tries to fit as many axes 00221 // as possible given <src>maxPixels</src>. 00222 virtual IPosition doNiceCursorShape (uInt maxPixels) const; 00223 00224 // Maximum cache size - not necessarily all used. In pixels. 00225 // Default returns 0, which means that there is no maximum. 00226 virtual uInt maximumCacheSize() const; 00227 00228 // Set the maximum (allowed) cache size as indicated. 00229 // <br>The default implementation does nothing. 00230 virtual void setMaximumCacheSize (uInt howManyPixels); 00231 00232 // Set the actual cache size for this Array to be big enough for the 00233 // indicated number of tiles. This cache is not shared with PagedArrays 00234 // in other rows and is always clipped to be less than the maximum value 00235 // set using the setMaximumCacheSize member function. 00236 // Tiles are cached using a first in first out algorithm. 00237 // <br>The default implementation does nothing. 00238 virtual void setCacheSizeInTiles (uInt howManyTiles); 00239 00240 // Set the cache size as to "fit" the indicated path. 00241 // <br>The default implementation does nothing. 00242 virtual void setCacheSizeFromPath (const IPosition& sliceShape, 00243 const IPosition& windowStart, 00244 const IPosition& windowLength, 00245 const IPosition& axisPath); 00246 00247 // Clears and frees up the caches, but the maximum allowed cache size is 00248 // unchanged from when setCacheSize was called. 00249 // <br>The default implementation does nothing. 00250 virtual void clearCache(); 00251 00252 // Report on cache success. 00253 // <br>The default implementation does nothing. 00254 virtual void showCacheStatistics (ostream& os) const; 00255 00256 00257 protected: 00258 // Define default constructor to be used by derived classes. 00259 LatticeBase() {}; 00260 00261 // Copy constructor and assignment can only be used by derived classes. 00262 // <group> 00263 LatticeBase (const LatticeBase&) {}; 00264 LatticeBase& operator= (const LatticeBase&) 00265 { return *this; } 00266 // </group> 00267 00268 // Throw an exception for arithmetic on a Bool Lattice. 00269 void throwBoolMath() const; 00270 }; 00271 00272 00273 00274 } //# NAMESPACE CASACORE - END 00275 00276 #endif