casacore
LatticeBase.h
Go to the documentation of this file.
1 //# LatticeBase.h: A non-templated, abstract base class for array-like classes
2 //# Copyright (C) 1999,2000,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef LATTICES_LATTICEBASE_H
29 #define LATTICES_LATTICEBASE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/lattices/LEL/LELCoordinates.h>
35 #include <casacore/casa/Arrays/IPosition.h>
36 #include <casacore/casa/Utilities/DataType.h>
37 #include <casacore/casa/IO/FileLocker.h>
38 #include <casacore/casa/BasicSL/String.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class LogIO;
44 
45 
46 // <summary>
47 // A non-templated, abstract base class for array-like objects.
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="Bob Garwood" date="2000/01/18" tests="tArrayLattice.cc" demos="dLattice.cc">
53 // </reviewed>
54 
55 // <synopsis>
56 // This pure abstract base class defines the operations which may be
57 // performed on a lattice of any type.
58 // <br>See class <linkto class=Lattice>Lattice</linkto> for a detailed
59 // description of a lattice.
60 // </synopsis>
61 
62 // <motivation>
63 // It is very useful to be able to keep a pointer to a
64 // non-templated base class. Furthermore it gives the opportunity to
65 // factor out some non-templated code.
66 // </motivation>
67 
68 // <note>
69 // The cache functions (maximumCacheSize, setMaximumCacheSize,
70 // setCacheSizeInTiles, setCacheSizeFromPath, clearCache, and
71 // showCacheStatistics) should all be over-ridden together as
72 // in PagedArray.
73 // </note>
74 //
75 //# <todo asof="1999/02/04">
76 //# <li>
77 //# </todo>
78 
79 
81 {
82 public:
83  // A virtual destructor is needed so that it will use the actual destructor
84  // in the derived class.
85  virtual ~LatticeBase();
86 
87  // Make a copy of the derived object (reference semantics).
88  virtual LatticeBase* clone() const = 0;
89 
90  // Get the image type (returns name of derived class).
91  // The default implementation returns "Lattice".
92  // Note it is made pure virtual in ImageInterface.
93  virtual String imageType() const;
94 
95  // Get the data type of the lattice.
96  virtual DataType dataType() const = 0;
97 
98  // Is the lattice persistent and can it be loaded by other processes as well?
99  // That is the case for a PagedArray or PagedImage and for an ImageExpr
100  // which does not use transient lattices or regions.
101  // <br>The default implementation returns False.
102  virtual Bool isPersistent() const;
103 
104  // Is the lattice paged to disk?
105  // <br>The default implementation returns False.
106  virtual Bool isPaged() const;
107 
108  // Can the lattice data be referenced as an array section?
109  // That is the case for an ArrayLattice or a Temp/SubLattice using it.
110  // It is used by LatticeIterInterface.
111  // <br>The default implementation returns False.
112  virtual Bool canReferenceArray() const;
113 
114  // Is the lattice writable?
115  // <br>The default implementation returns True.
116  virtual Bool isWritable() const;
117 
118  // Save the image in an AipsIO file with the given name.
119  // Its purpose is to make ImageConcat and ImageExpr objects
120  // persistent.
121  // <br>The default implementation throws an exception.
122  virtual void save (const String& fileName) const;
123 
124  // It is strongly recommended to use class
125  // <linkto class=LatticeLocker>LatticeLocker</linkto> to
126  // handle lattice locking. It also contains a more detailed
127  // explanation of the locking process.
128  // <br>By default the functions do not do anything at all.
129  // lock() and hasLock return True, which is suitable for all
130  // non-paged lattices.
131  // <group>
132  virtual Bool lock (FileLocker::LockType, uInt nattempts);
133  virtual void unlock();
135  // </group>
136 
137  // Resynchronize the Lattice object with the lattice file.
138  // This function is only useful if no read-locking is used, ie.
139  // if the table lock option is UserNoReadLocking or AutoNoReadLocking.
140  // In that cases the table system does not acquire a read-lock, thus
141  // does not synchronize itself automatically.
142  // <br>By default the function does not do anything at all.
143  virtual void resync();
144 
145  // Flush the data (but do not unlock).
146  // <br>By default the function does not do anything at all.
147  virtual void flush();
148 
149  // Temporarily close the lattice.
150  // It will be reopened automatically on the next access.
151  // <br>By default the function does not do anything at all.
152  virtual void tempClose();
153 
154  // Explicitly reopen the temporarily closed lattice.
155  // <br>By default the function does not do anything at all.
156  virtual void reopen();
157 
158  // Return the name of the current Lattice object. This will generally
159  // be a file name for lattices that have a persistent form. Any path
160  // before the actual file name can be optionally stripped off.
161  // <br>The default implementation returns an empty string.
162  virtual String name (Bool stripPath=False) const;
163 
164  // Return the shape of the Lattice including all degenerate axes
165  // (ie. axes with a length of one)
166  virtual IPosition shape() const = 0;
167 
168  // Return the number of axes in this Lattice. This includes all
169  // degenerate axes.
170  // <br>The default implementation returns shape().nelements().
171  virtual uInt ndim() const;
172 
173  // Return the total number of elements in this Lattice.
174  // <br>The default implementation returns shape().product().
175  // <group>
176  virtual size_t nelements() const;
177  size_t size() const
178  { return nelements(); }
179  // </group>
180 
181  // Return a value of "True" if this instance of Lattice and 'other' have
182  // the same shape, otherwise returns a value of "False".
183  Bool conform (const LatticeBase& other) const
184  { return shape().isEqual (other.shape()); }
185 
186  // Return the coordinates of the lattice.
187  // <br>The default implementation returns an 'empty' LELLattCoord object.
189 
190  // This function returns the recommended maximum number of pixels to
191  // include in the cursor of an iterator. The Lattice class has a default
192  // implementation which returns a number that is a power of two and
193  // includes enough pixels to consume between 4 and 8 MBytes of memory.
194  virtual uInt advisedMaxPixels() const = 0;
195 
196  // Returns a recommended cursor shape for iterating through all the pixels
197  // in the Lattice. The default implementation sets up a shape that
198  // completely fills as many axes as possible, but always at least the
199  // first axis. For example, given a 10x20x30 Lattice
200  // <srcblock>
201  // maxPixels = 1 --> niceCursorShape = [10,1,1]
202  // 100 --> niceCursorShape = [10,1,1]
203  // 300 --> niceCursorShape = [10,20,1]
204  // 10000 --> niceCursorShape = [10,20,30]
205  // </srcblock>
206  // The default argument is the result of <src>advisedMaxPixels()</src>.
207  // <group>
208  IPosition niceCursorShape (uInt maxPixels) const
209  { return doNiceCursorShape (maxPixels); }
211  { return doNiceCursorShape (advisedMaxPixels()); }
212  // </group>
213 
214  // Check class internals - used for debugging. Should always return True
215  virtual Bool ok() const;
216 
217  // The function (in the derived classes) doing the actual work.
218  // This function is public, so it can be used internally in the
219  // various Lattice classes.
220  // <br>The default implementation tries to fit as many axes
221  // as possible given <src>maxPixels</src>.
222  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
223 
224  // Maximum cache size - not necessarily all used. In pixels.
225  // Default returns 0, which means that there is no maximum.
226  virtual uInt maximumCacheSize() const;
227 
228  // Set the maximum (allowed) cache size as indicated.
229  // <br>The default implementation does nothing.
230  virtual void setMaximumCacheSize (uInt howManyPixels);
231 
232  // Set the actual cache size for this Array to be big enough for the
233  // indicated number of tiles. This cache is not shared with PagedArrays
234  // in other rows and is always clipped to be less than the maximum value
235  // set using the setMaximumCacheSize member function.
236  // Tiles are cached using a first in first out algorithm.
237  // <br>The default implementation does nothing.
238  virtual void setCacheSizeInTiles (uInt howManyTiles);
239 
240  // Set the cache size as to "fit" the indicated path.
241  // <br>The default implementation does nothing.
242  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
243  const IPosition& windowStart,
244  const IPosition& windowLength,
245  const IPosition& axisPath);
246 
247  // Clears and frees up the caches, but the maximum allowed cache size is
248  // unchanged from when setCacheSize was called.
249  // <br>The default implementation does nothing.
250  virtual void clearCache();
251 
252  // Report on cache success.
253  // <br>The default implementation does nothing.
254  virtual void showCacheStatistics (ostream& os) const;
255 
256 
257 protected:
258  // Define default constructor to be used by derived classes.
260 
261  // Copy constructor and assignment can only be used by derived classes.
262  // <group>
265  { return *this; }
266  // </group>
267 
268  // Throw an exception for arithmetic on a Bool Lattice.
269  void throwBoolMath() const;
270 };
271 
272 
273 
274 } //# NAMESPACE CASACORE - END
275 
276 #endif
casacore::LatticeBase::nelements
virtual size_t nelements() const
Return the total number of elements in this Lattice.
casacore::LatticeBase::operator=
LatticeBase & operator=(const LatticeBase &)
Definition: LatticeBase.h:264
casacore::LatticeBase::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::LatticeBase::save
virtual void save(const String &fileName) const
Save the image in an AipsIO file with the given name.
casacore::LatticeBase::isPersistent
virtual Bool isPersistent() const
Is the lattice persistent and can it be loaded by other processes as well? That is the case for a Pag...
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:120
casacore::LatticeBase::canReferenceArray
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section? That is the case for an ArrayLattice or a Tem...
casacore::LatticeBase::reopen
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
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::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
The function (in the derived classes) doing the actual work.
casacore::LatticeBase::niceCursorShape
IPosition niceCursorShape() const
Definition: LatticeBase.h:210
casacore::LatticeBase::ndim
virtual uInt ndim() const
Return the number of axes in this Lattice.
casacore::LatticeBase::lelCoordinates
virtual LELCoordinates lelCoordinates() const
Return the coordinates of the lattice.
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition: FileLocker.h:95
casacore::LatticeBase::name
virtual String name(Bool stripPath=False) const
Return the name of the current Lattice object.
casacore::LatticeBase::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum cache size - not necessarily all used.
casacore::LatticeBase::dataType
virtual DataType dataType() const =0
Get the data type of the lattice.
casacore::LatticeBase::flush
virtual void flush()
Flush the data (but do not unlock).
casacore::LatticeBase::shape
virtual IPosition shape() const =0
Return the shape of the Lattice including all degenerate axes (ie.
casacore::LatticeBase::resync
virtual void resync()
Resynchronize the Lattice object with the lattice file.
casacore::LatticeBase::~LatticeBase
virtual ~LatticeBase()
A virtual destructor is needed so that it will use the actual destructor in the 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:183
casacore::LatticeBase::LatticeBase
LatticeBase(const LatticeBase &)
Copy constructor and assignment can only be used by derived classes.
Definition: LatticeBase.h:263
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::LatticeBase::hasLock
virtual Bool hasLock(FileLocker::LockType) const
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::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
casacore::LatticeBase::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
It is strongly recommended to use class LatticeLocker to handle lattice locking.
casacore::LatticeBase::size
size_t size() const
Definition: LatticeBase.h:177
casacore::LatticeBase
A non-templated, abstract base class for array-like objects.
Definition: LatticeBase.h:81
casacore::LatticeBase::clone
virtual LatticeBase * clone() const =0
Make a copy of the derived object (reference semantics).
casacore::IPosition::isEqual
Bool isEqual(const IPosition &other) const
Element-by-element comparison for equality.
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::LELCoordinates
Envelope class to handle Lattice Coordinates in LEL.
Definition: LELCoordinates.h:124
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:208
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::LatticeBase::isWritable
virtual Bool isWritable() const
Is the lattice writable? The default implementation returns True.
casacore::LatticeBase::throwBoolMath
void throwBoolMath() const
Throw an exception for arithmetic on a Bool Lattice.
casacore::LatticeBase::isPaged
virtual Bool isPaged() const
Is the lattice paged to disk? The default implementation returns False.
casacore::LatticeBase::ok
virtual Bool ok() const
Check class internals - used for debugging.
casacore::LatticeBase::LatticeBase
LatticeBase()
Define default constructor to be used by derived classes.
Definition: LatticeBase.h:259
casacore::LatticeBase::imageType
virtual String imageType() const
Get the image type (returns name of derived class).
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::unlock
virtual void unlock()
casacore::LatticeBase::tempClose
virtual void tempClose()
Temporarily close the lattice.
casacore::LatticeBase::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.