Loading...
Searching...
No Matches
LatticeBase.h
Go to the documentation of this file.
//# LatticeBase.h: A non-templated, abstract base class for array-like classes
//# Copyright (C) 1999,2000,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef LATTICES_LATTICEBASE_H
#define LATTICES_LATTICEBASE_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/lattices/LEL/LELCoordinates.h>
#include <casacore/casa/Arrays/IPosition.h>
#include <casacore/casa/Utilities/DataType.h>
#include <casacore/casa/IO/FileLocker.h>
#include <casacore/casa/BasicSL/String.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class LogIO;
// <summary>
// A non-templated, abstract base class for array-like objects.
// </summary>
// <use visibility=export>
// <reviewed reviewer="Bob Garwood" date="2000/01/18" tests="tArrayLattice.cc" demos="dLattice.cc">
// </reviewed>
// <synopsis>
// This pure abstract base class defines the operations which may be
// performed on a lattice of any type.
// <br>See class <linkto class=Lattice>Lattice</linkto> for a detailed
// description of a lattice.
// </synopsis>
// <motivation>
// It is very useful to be able to keep a pointer to a
// non-templated base class. Furthermore it gives the opportunity to
// factor out some non-templated code.
// </motivation>
// <note>
// The cache functions (maximumCacheSize, setMaximumCacheSize,
// setCacheSizeInTiles, setCacheSizeFromPath, clearCache, and
// showCacheStatistics) should all be over-ridden together as
// in PagedArray.
// </note>
//
//# <todo asof="1999/02/04">
//# <li>
//# </todo>
class LatticeBase
{
public:
// A virtual destructor is needed so that it will use the actual destructor
// in the derived class.
virtual ~LatticeBase();
// Make a copy of the derived object (reference semantics).
virtual LatticeBase* clone() const = 0;
// Get the image type (returns name of derived class).
// The default implementation returns "Lattice".
// Note it is made pure virtual in ImageInterface.
virtual String imageType() const;
// Get the data type of the lattice.
virtual DataType dataType() const = 0;
// Is the lattice persistent and can it be loaded by other processes as well?
// That is the case for a PagedArray or PagedImage and for an ImageExpr
// which does not use transient lattices or regions.
// <br>The default implementation returns False.
virtual Bool isPersistent() const;
// Is the lattice paged to disk?
// <br>The default implementation returns False.
virtual Bool isPaged() const;
// Can the lattice data be referenced as an array section?
// That is the case for an ArrayLattice or a Temp/SubLattice using it.
// It is used by LatticeIterInterface.
// <br>The default implementation returns False.
virtual Bool canReferenceArray() const;
// Is the lattice writable?
// <br>The default implementation returns True.
virtual Bool isWritable() const;
// Save the image in an AipsIO file with the given name.
// Its purpose is to make ImageConcat and ImageExpr objects
// persistent.
// <br>The default implementation throws an exception.
virtual void save (const String& fileName) const;
// It is strongly recommended to use class
// <linkto class=LatticeLocker>LatticeLocker</linkto> to
// handle lattice locking. It also contains a more detailed
// explanation of the locking process.
// <br>By default the functions do not do anything at all.
// lock() and hasLock return True, which is suitable for all
// non-paged lattices.
// <group>
virtual Bool lock (FileLocker::LockType, uInt nattempts);
virtual void unlock();
virtual Bool hasLock (FileLocker::LockType) const;
// </group>
// Resynchronize the Lattice object with the lattice file.
// This function is only useful if no read-locking is used, ie.
// if the table lock option is UserNoReadLocking or AutoNoReadLocking.
// In that cases the table system does not acquire a read-lock, thus
// does not synchronize itself automatically.
// <br>By default the function does not do anything at all.
virtual void resync();
// Flush the data (but do not unlock).
// <br>By default the function does not do anything at all.
virtual void flush();
// Temporarily close the lattice.
// It will be reopened automatically on the next access.
// <br>By default the function does not do anything at all.
virtual void tempClose();
// Explicitly reopen the temporarily closed lattice.
// <br>By default the function does not do anything at all.
virtual void reopen();
// Return the name of the current Lattice object. This will generally
// be a file name for lattices that have a persistent form. Any path
// before the actual file name can be optionally stripped off.
// <br>The default implementation returns an empty string.
virtual String name (Bool stripPath=False) const;
// Return the shape of the Lattice including all degenerate axes
// (ie. axes with a length of one)
virtual IPosition shape() const = 0;
// Return the number of axes in this Lattice. This includes all
// degenerate axes.
// <br>The default implementation returns shape().nelements().
virtual uInt ndim() const;
// Return the total number of elements in this Lattice.
// <br>The default implementation returns shape().product().
// <group>
virtual size_t nelements() const;
size_t size() const
{ return nelements(); }
// </group>
// Return a value of "True" if this instance of Lattice and 'other' have
// the same shape, otherwise returns a value of "False".
Bool conform (const LatticeBase& other) const
{ return shape().isEqual (other.shape()); }
// Return the coordinates of the lattice.
// <br>The default implementation returns an 'empty' LELLattCoord object.
virtual LELCoordinates lelCoordinates() const;
// This function returns the recommended maximum number of pixels to
// include in the cursor of an iterator. The Lattice class has a default
// implementation which returns a number that is a power of two and
// includes enough pixels to consume between 4 and 8 MBytes of memory.
virtual uInt advisedMaxPixels() const = 0;
// Returns a recommended cursor shape for iterating through all the pixels
// in the Lattice. The default implementation sets up a shape that
// completely fills as many axes as possible, but always at least the
// first axis. For example, given a 10x20x30 Lattice
// <srcblock>
// maxPixels = 1 --> niceCursorShape = [10,1,1]
// 100 --> niceCursorShape = [10,1,1]
// 300 --> niceCursorShape = [10,20,1]
// 10000 --> niceCursorShape = [10,20,30]
// </srcblock>
// The default argument is the result of <src>advisedMaxPixels()</src>.
// <group>
IPosition niceCursorShape (uInt maxPixels) const
{ return doNiceCursorShape (maxPixels); }
IPosition niceCursorShape() const
{ return doNiceCursorShape (advisedMaxPixels()); }
// </group>
// Check class internals - used for debugging. Should always return True
virtual Bool ok() const;
// The function (in the derived classes) doing the actual work.
// This function is public, so it can be used internally in the
// various Lattice classes.
// <br>The default implementation tries to fit as many axes
// as possible given <src>maxPixels</src>.
virtual IPosition doNiceCursorShape (uInt maxPixels) const;
// Maximum cache size - not necessarily all used. In pixels.
// Default returns 0, which means that there is no maximum.
virtual uInt maximumCacheSize() const;
// Set the maximum (allowed) cache size as indicated.
// <br>The default implementation does nothing.
virtual void setMaximumCacheSize (uInt howManyPixels);
// Set the actual cache size for this Array to be big enough for the
// indicated number of tiles. This cache is not shared with PagedArrays
// in other rows and is always clipped to be less than the maximum value
// set using the setMaximumCacheSize member function.
// Tiles are cached using a first in first out algorithm.
// <br>The default implementation does nothing.
virtual void setCacheSizeInTiles (uInt howManyTiles);
// Set the cache size as to "fit" the indicated path.
// <br>The default implementation does nothing.
virtual void setCacheSizeFromPath (const IPosition& sliceShape,
const IPosition& windowStart,
const IPosition& windowLength,
const IPosition& axisPath);
// Clears and frees up the caches, but the maximum allowed cache size is
// unchanged from when setCacheSize was called.
// <br>The default implementation does nothing.
virtual void clearCache();
// Report on cache success.
// <br>The default implementation does nothing.
virtual void showCacheStatistics (ostream& os) const;
protected:
// Define default constructor to be used by derived classes.
LatticeBase() {};
// Copy constructor and assignment can only be used by derived classes.
// <group>
LatticeBase (const LatticeBase&) {};
LatticeBase& operator= (const LatticeBase&)
{ return *this; }
// </group>
// Throw an exception for arithmetic on a Bool Lattice.
void throwBoolMath() const;
};
} //# NAMESPACE CASACORE - END
#endif
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition FileLocker.h:93
casacore::IPosition
Definition IPosition.h:117
casacore::IPosition::isEqual
bool isEqual(const IPosition &other) const
Element-by-element comparison for equality.
casacore::LELCoordinates
Definition LELCoordinates.h:122
casacore::LatticeBase::isPersistent
virtual Bool isPersistent() const
Is the lattice persistent and can it be loaded by other processes as well?
casacore::LatticeBase::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum cache size - not necessarily all used.
casacore::LatticeBase::imageType
virtual String imageType() const
Get the image type (returns name of derived class).
casacore::LatticeBase::conform
Bool conform(const LatticeBase &other) const
Return a value of "True" if this instance of Lattice and 'other' have the same shape,...
Definition LatticeBase.h:181
casacore::LatticeBase::shape
virtual IPosition shape() const =0
Return the shape of the Lattice including all degenerate axes (ie.
casacore::LatticeBase::size
size_t size() const
Definition LatticeBase.h:175
casacore::LatticeBase::isPaged
virtual Bool isPaged() const
Is the lattice paged to disk?
casacore::LatticeBase::niceCursorShape
IPosition niceCursorShape(uInt maxPixels) const
Returns a recommended cursor shape for iterating through all the pixels in the Lattice.
Definition LatticeBase.h:206
casacore::LatticeBase::canReferenceArray
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
casacore::LatticeBase::operator=
LatticeBase & operator=(const LatticeBase &)
Definition LatticeBase.h:262
casacore::LatticeBase::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
It is strongly recommended to use class LatticeLocker to handle lattice locking.
casacore::LatticeBase::resync
virtual void resync()
Resynchronize the Lattice object with the lattice file.
casacore::LatticeBase::advisedMaxPixels
virtual uInt advisedMaxPixels() const =0
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
casacore::LatticeBase::flush
virtual void flush()
Flush the data (but do not unlock).
casacore::LatticeBase::niceCursorShape
IPosition niceCursorShape() const
Definition LatticeBase.h:208
casacore::LatticeBase::setCacheSizeInTiles
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be big enough for the indicated number of tiles.
casacore::LatticeBase::nelements
virtual size_t nelements() const
Return the total number of elements in this Lattice.
casacore::LatticeBase::LatticeBase
LatticeBase()
Define default constructor to be used by derived classes.
Definition LatticeBase.h:257
casacore::LatticeBase::ndim
virtual uInt ndim() const
Return the number of axes in this Lattice.
casacore::LatticeBase::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
casacore::LatticeBase::unlock
virtual void unlock()
casacore::LatticeBase::throwBoolMath
void throwBoolMath() const
Throw an exception for arithmetic on a Bool Lattice.
casacore::LatticeBase::LatticeBase
LatticeBase(const LatticeBase &)
Copy constructor and assignment can only be used by derived classes.
Definition LatticeBase.h:261
casacore::LatticeBase::tempClose
virtual void tempClose()
Temporarily close the lattice.
casacore::LatticeBase::lelCoordinates
virtual LELCoordinates lelCoordinates() const
Return the coordinates of the lattice.
casacore::LatticeBase::reopen
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
casacore::LatticeBase::~LatticeBase
virtual ~LatticeBase()
A virtual destructor is needed so that it will use the actual destructor in the derived class.
casacore::LatticeBase::hasLock
virtual Bool hasLock(FileLocker::LockType) const
casacore::LatticeBase::isWritable
virtual Bool isWritable() const
Is the lattice writable?
casacore::LatticeBase::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
The function (in the derived classes) doing the actual work.
casacore::LatticeBase::clone
virtual LatticeBase * clone() const =0
Make a copy of the derived object (reference semantics).
casacore::LatticeBase::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
casacore::LatticeBase::setCacheSizeFromPath
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
casacore::LatticeBase::ok
virtual Bool ok() const
Check class internals - used for debugging.
casacore::LatticeBase::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::LatticeBase::name
virtual String name(Bool stripPath=False) const
Return the name of the current Lattice object.
casacore::LatticeBase::save
virtual void save(const String &fileName) const
Save the image in an AipsIO file with the given name.
casacore::LatticeBase::dataType
virtual DataType dataType() const =0
Get the data type of the lattice.
casacore::LogIO
Definition LogIO.h:165
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40