casacore
TempLatticeImpl.h
Go to the documentation of this file.
1 //# TempLatticeImpl.h: A Lattice that can be used for temporary storage
2 //# Copyright (C) 1997,1998,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 //#
27 //# $Id: TempLatticeImpl.h 20739 2009-09-29 01:15:15Z Malte.Marquarding $
28 
29 #ifndef LATTICES_TEMPLATTICEIMPL_H
30 #define LATTICES_TEMPLATTICEIMPL_H
31 
32 
33 //# Includes
34 #include <casacore/casa/aips.h>
35 #include <casacore/lattices/Lattices/Lattice.h>
36 #include <casacore/lattices/Lattices/TiledShape.h>
37 #include <casacore/tables/Tables/Table.h>
38 #include <casacore/casa/Utilities/CountedPtr.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class Table;
44 
45 
46 // <summary>
47 // The class implementing TempLattice
48 // </summary>
49 
50 // <use visibility=local>
51 
52 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTempLattice.cc" demos="">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto class="TempLattice">Lattice</linkto>
57 // </prerequisite>
58 
59 // <synopsis>
60 // The class is used as <src>CountedPtr<TempLatticeImpl></src> in class
61 // TempLattice. In that way the making a copy of a TempLattice uses the
62 // same object underneath.
63 // This was needed to have a correct implementation of tempClose. Otherwise
64 // when deleting a copy of a TempLattice, that destructor would delete the
65 // underlying table and the original TempLattice could not reopen it.
66 // </synopsis>
67 
68 
69 template<class T> class TempLatticeImpl
70 {
71 public:
72  // The default constructor creates a TempLatticeImpl containing a
73  // default ArrayLattice object.
75 
76  // Create a TempLatticeImpl of the specified shape. You can specify how much
77  // memory the Lattice can consume before it becomes disk based by giving a
78  // non-negative value to the maxMemoryInMB argument. Otherwise it will assume
79  // it can use up to 25% of the memory on your machine as defined in aipsrc
80  // (this algorithm may change). Setting maxMemoryInMB to zero will force
81  // the lattice to disk.
82  // <group>
83  TempLatticeImpl (const TiledShape& shape, Int maxMemoryInMB);
84  TempLatticeImpl (const TiledShape& shape, Double maxMemoryInMB);
85  // </group>
86 
87  // The destructor removes the Lattice from memory and if necessary disk.
89 
90  // Is the TempLattice paged to disk?
91  Bool isPaged() const
92  { return (! itsTableName.empty()); }
93 
94  // Can the lattice data be referenced as an array section?
96  { return (itsTableName.empty()); }
97 
98  // Is the TempLattice writable? It should be.
99  Bool isWritable() const
100  { return True; }
101 
102  // Flush the data.
103  void flush()
104  { if (itsTablePtr != 0) itsTablePtr->flush(); }
105 
106  // Close the Lattice temporarily (if it is paged to disk).
107  // It'll be reopened automatically when needed or when
108  // <src>reopen</src> is called explicitly.
109  void tempClose();
110 
111  // If needed, reopen a temporarily closed TempLatticeImpl.
112  void reopen();
113 
114  // Return the shape of the Lattice including all degenerate axes.
115  // (ie. axes with a length of one)
116  IPosition shape() const
117  { doReopen(); return itsLatticePtr->shape(); }
118 
119  // Set all of the elements in the Lattice to the given value.
120  void set (const T& value)
121  { doReopen(); itsLatticePtr->set (value); }
122 
123  // Replace every element, x, of the Lattice with the result of f(x). You
124  // must pass in the address of the function -- so the function must be
125  // declared and defined in the scope of your program. All versions of
126  // apply require a function that accepts a single argument of type T (the
127  // Lattice template type) and return a result of the same type. The first
128  // apply expects a function with an argument passed by value; the second
129  // expects the argument to be passed by const reference; the third
130  // requires an instance of the class <src>Functional<T,T></src>. The
131  // first form ought to run faster for the built-in types, which may be an
132  // issue for large Lattices stored in memory, where disk access is not an
133  // issue.
134  // <group>
135  void apply (T (*function)(T))
136  { doReopen(); itsLatticePtr->apply (function); }
137  void apply (T (*function)(const T&))
138  { doReopen(); itsLatticePtr->apply (function); }
139  void apply (const Functional<T,T>& function)
140  { doReopen(); itsLatticePtr->apply (function); }
141  // </group>
142 
143  // This function returns the recommended maximum number of pixels to
144  // include in the cursor of an iterator.
146  { doReopen(); return itsLatticePtr->advisedMaxPixels(); }
147 
148  // Get the best cursor shape.
150  { doReopen(); return itsLatticePtr->niceCursorShape (maxPixels); }
151 
152  // Maximum size - not necessarily all used. In pixels.
154  { return itsLatticePtr->maximumCacheSize(); }
155 
156  // Set the maximum (allowed) cache size as indicated.
157  void setMaximumCacheSize (uInt howManyPixels)
158  { itsLatticePtr->setMaximumCacheSize (howManyPixels); }
159 
160  // Set the cache size as to "fit" the indicated path.
161  void setCacheSizeFromPath (const IPosition& sliceShape,
162  const IPosition& windowStart,
163  const IPosition& windowLength,
164  const IPosition& axisPath)
165  { itsLatticePtr->setCacheSizeFromPath (sliceShape, windowStart, windowLength,
166  axisPath); }
167 
168  // Set the actual cache size for this Array to be be big enough for the
169  // indicated number of tiles. This cache is not shared with PagedArrays
170  // in other rows and is always clipped to be less than the maximum value
171  // set using the setMaximumCacheSize member function.
172  // tiles. Tiles are cached using a first in first out algorithm.
173  void setCacheSizeInTiles (uInt howManyTiles)
174  { itsLatticePtr->setCacheSizeInTiles (howManyTiles); }
175 
176  // Clears and frees up the caches, but the maximum allowed cache size is
177  // unchanged from when setCacheSize was called
178  void clearCache()
179  { itsLatticePtr->clearCache(); }
180 
181  // Report on cache success.
182  void showCacheStatistics (ostream& os) const
183  { itsLatticePtr->showCacheStatistics (os); }
184 
185  // Get or put a single element in the lattice.
186  // Note that Lattice::operator() can also be used to get a single element.
187  // <group>
188  T getAt (const IPosition& where) const
189  { doReopen(); return itsLatticePtr->getAt (where); }
190  void putAt (const T& value, const IPosition& where)
191  { doReopen(); itsLatticePtr->putAt (value, where); }
192  // </group>
193 
194  // Check class internals - used for debugging. Should always return True
195  Bool ok() const
196  { doReopen(); return itsLatticePtr->ok(); }
197 
198  // This function is used by the LatticeIterator class to generate an
199  // iterator of the correct type for this Lattice. Not recommended
200  // for general use.
202  Bool useRef) const
203  { doReopen(); return itsLatticePtr->makeIter (navigator, useRef); }
204 
205  // Do the actual getting of an array of values.
206  Bool doGetSlice (Array<T>& buffer, const Slicer& section)
207  { doReopen(); return itsLatticePtr->doGetSlice (buffer, section); }
208 
209  // Do the actual getting of an array of values.
210  void doPutSlice (const Array<T>& sourceBuffer,
211  const IPosition& where,
212  const IPosition& stride)
213  { doReopen(); itsLatticePtr->putSlice (sourceBuffer, where, stride); }
214 
215  // Do the reopen of the table (if not open already).
216  void doReopen() const
217  { if (itsIsClosed) tempReopen(); }
218 
219 private:
220  // The copy constructor cannot be used.
222 
223  // The assignment operator cannot be used.
225 
226  // Initialize the object.
227  void init (const TiledShape& shape, Double maxMemoryInMB=-1);
228 
229  // Do the actual reopen of the temporarily closed table (if not open already).
230  void tempReopen() const;
231 
232  // Make sure that the temporary table gets deleted.
233  void deleteTable();
234 
235 
236  mutable Table* itsTablePtr;
239  mutable Bool itsIsClosed;
240 };
241 
242 
243 
244 } //# NAMESPACE CASACORE - END
245 
246 #ifndef CASACORE_NO_AUTO_TEMPLATES
247 #include <casacore/lattices/Lattices/TempLatticeImpl.tcc>
248 #endif //# CASACORE_NO_AUTO_TEMPLATES
249 #endif
casacore::TempLatticeImpl::doNiceCursorShape
IPosition doNiceCursorShape(uInt maxPixels)
Get the best cursor shape.
Definition: TempLatticeImpl.h:149
casacore::TempLatticeImpl::apply
void apply(const Functional< T, T > &function)
Definition: TempLatticeImpl.h:139
casacore::TempLatticeImpl::shape
IPosition shape() const
Return the shape of the Lattice including all degenerate axes.
Definition: TempLatticeImpl.h:116
casacore::Slicer
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:290
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:120
casacore::TempLatticeImpl::advisedMaxPixels
uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
Definition: TempLatticeImpl.h:145
casacore::Table::flush
void flush(Bool fsync=False, Bool recursive=False)
Flush the table, i.e.
Definition: Table.h:1131
casacore::String::empty
Bool empty() const
Test for empty.
Definition: String.h:375
casacore::TempLatticeImpl::setMaximumCacheSize
void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
Definition: TempLatticeImpl.h:157
casacore::TempLatticeImpl::TempLatticeImpl
TempLatticeImpl(const TempLatticeImpl< T > &other)
The copy constructor cannot be used.
casacore::TempLatticeImpl::isWritable
Bool isWritable() const
Is the TempLattice writable? It should be.
Definition: TempLatticeImpl.h:99
casacore::TempLatticeImpl::flush
void flush()
Flush the data.
Definition: TempLatticeImpl.h:103
casacore::TempLatticeImpl::itsTablePtr
Table * itsTablePtr
Definition: TempLatticeImpl.h:236
casacore::TempLatticeImpl::itsTableName
String itsTableName
Definition: TempLatticeImpl.h:238
casacore::TempLatticeImpl::reopen
void reopen()
If needed, reopen a temporarily closed TempLatticeImpl.
casacore::CountedPtr
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
casacore::TempLatticeImpl::TempLatticeImpl
TempLatticeImpl()
The default constructor creates a TempLatticeImpl containing a default ArrayLattice object.
casacore::Functional
Map a domain object into a range object via operator().
Definition: Array.h:53
casacore::TempLatticeImpl::isPaged
Bool isPaged() const
Is the TempLattice paged to disk?
Definition: TempLatticeImpl.h:91
casacore::TempLatticeImpl::operator=
TempLatticeImpl< T > & operator=(const TempLatticeImpl< T > &other)
The assignment operator cannot be used.
casacore::TempLatticeImpl::clearCache
void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
Definition: TempLatticeImpl.h:178
casacore::TempLatticeImpl::init
void init(const TiledShape &shape, Double maxMemoryInMB=-1)
Initialize the object.
casacore::TempLatticeImpl::ok
Bool ok() const
Check class internals - used for debugging.
Definition: TempLatticeImpl.h:195
casacore::TempLatticeImpl::doPutSlice
void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
Definition: TempLatticeImpl.h:210
casacore::TempLatticeImpl::~TempLatticeImpl
~TempLatticeImpl()
The destructor removes the Lattice from memory and if necessary disk.
casacore::TempLatticeImpl::canReferenceArray
Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
Definition: TempLatticeImpl.h:95
casacore::TempLatticeImpl::putAt
void putAt(const T &value, const IPosition &where)
Definition: TempLatticeImpl.h:190
casacore::TempLatticeImpl::getAt
T getAt(const IPosition &where) const
Get or put a single element in the lattice.
Definition: TempLatticeImpl.h:188
casacore::Table
Main interface class to a read/write table.
Definition: Table.h:154
casacore::TempLatticeImpl::maximumCacheSize
uInt maximumCacheSize() const
Maximum size - not necessarily all used.
Definition: TempLatticeImpl.h:153
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::Double
double Double
Definition: aipstype.h:55
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::TempLatticeImpl::setCacheSizeFromPath
void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
Definition: TempLatticeImpl.h:161
casacore::TempLatticeImpl::set
void set(const T &value)
Set all of the elements in the Lattice to the given value.
Definition: TempLatticeImpl.h:120
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::TempLatticeImpl
The class implementing TempLattice.
Definition: TempLatticeImpl.h:70
casacore::TempLatticeImpl::setCacheSizeInTiles
void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
Definition: TempLatticeImpl.h:173
casacore::TempLatticeImpl::itsIsClosed
Bool itsIsClosed
Definition: TempLatticeImpl.h:239
casacore::TempLatticeImpl::doGetSlice
Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
Definition: TempLatticeImpl.h:206
casacore::TempLatticeImpl::tempReopen
void tempReopen() const
Do the actual reopen of the temporarily closed table (if not open already).
casacore::Array
template <class T, class U> class vector;
Definition: Array.h:167
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::TempLatticeImpl::TempLatticeImpl
TempLatticeImpl(const TiledShape &shape, Double maxMemoryInMB)
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::TempLatticeImpl::TempLatticeImpl
TempLatticeImpl(const TiledShape &shape, Int maxMemoryInMB)
Create a TempLatticeImpl of the specified shape.
casacore::TempLatticeImpl::doReopen
void doReopen() const
Do the reopen of the table (if not open already).
Definition: TempLatticeImpl.h:216
casacore::TempLatticeImpl::showCacheStatistics
void showCacheStatistics(ostream &os) const
Report on cache success.
Definition: TempLatticeImpl.h:182
casacore::TempLatticeImpl::apply
void apply(T(*function)(const T &))
Definition: TempLatticeImpl.h:137
casacore::TempLatticeImpl::makeIter
LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This function is used by the LatticeIterator class to generate an iterator of the correct type for th...
Definition: TempLatticeImpl.h:201
casacore::TempLatticeImpl::deleteTable
void deleteTable()
Make sure that the temporary table gets deleted.
casacore::TempLatticeImpl::tempClose
void tempClose()
Close the Lattice temporarily (if it is paged to disk).
casacore::TempLatticeImpl::apply
void apply(T(*function)(T))
Replace every element, x, of the Lattice with the result of f(x).
Definition: TempLatticeImpl.h:135
casacore::TiledShape
Define the shape and tile shape.
Definition: TiledShape.h:100
casacore::TempLatticeImpl::itsLatticePtr
CountedPtr< Lattice< T > > itsLatticePtr
Definition: TempLatticeImpl.h:237
casacore::LatticeIterInterface
A base class for Lattice iterators.
Definition: ImageExpr.h:47