LatticeBase.h

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

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1