A Lattice that is read from or written to disk. More...

#include <PagedArray.h>

Inheritance diagram for casacore::PagedArray< T >:

Public Member Functions
	PagedArray ()
	The default constructor creates a PagedArray that is useless for just about everything, except that it can be assigned to with the assignment operator. More...

	PagedArray (const TiledShape &shape, const String &filename)
	Construct a new PagedArray with the specified shape. More...

	PagedArray (const TiledShape &shape)
	Construct a new PagedArray with the specified shape. More...

	PagedArray (const TiledShape &shape, Table &file)
	Construct a new PagedArray, with the specified shape, in the default row and column of the supplied Table. More...

	PagedArray (const TiledShape &shape, Table &file, const String &columnName, uInt rowNum)
	Construct a new PagedArray, with the specified shape, in the specified row and column of the supplied Table. More...

	PagedArray (const String &filename)
	Reconstruct from a pre-existing PagedArray in the default row and column of the supplied Table with the supplied filename. More...

	PagedArray (Table &file)
	Reconstruct from a pre-existing PagedArray in the default row and column of the supplied Table. More...

	PagedArray (Table &file, const String &columnName, uInt rowNum)
	Reconstruct from a pre-existing PagedArray in the specified row and column of the supplied Table. More...

	PagedArray (const PagedArray< T > &other)
	The copy constructor which uses reference semantics. More...

	~PagedArray ()
	The destructor flushes the PagedArrays contents to disk. More...

PagedArray< T > &	operator= (const PagedArray< T > &other)
	The assignment operator with reference semantics. More...

virtual Lattice< T > *	clone () const
	Make a copy of the object (reference semantics). More...

virtual Bool	isPersistent () const
	A PagedArray is always persistent. More...

virtual Bool	isPaged () const
	A PagedArray is always paged to disk. More...

virtual Bool	isWritable () const
	Is the PagedArray writable? More...

virtual IPosition	shape () const
	Returns the shape of the PagedArray. More...

virtual String	name (Bool stripPath=False) const
	Return the current Table name. More...

void	resize (const TiledShape &newShape)
	Functions to resize the PagedArray. More...

const String &	tableName () const
	Returns the current table name (ie. More...

Table &	table ()
	Return the current table object. More...

const Table &	table () const

const String &	columnName () const
	Returns the current Table column name of this PagedArray. More...

const ROTiledStManAccessor &	accessor () const
	Returns an accessor to the tiled storage manager. More...

uInt	rowNumber () const
	Returns the current row number of this PagedArray. More...

IPosition	tileShape () const
	Returns the current tile shape for this PagedArray. More...

virtual uInt	advisedMaxPixels () const
	Returns the maximum recommended number of pixels for a cursor. More...

virtual void	setMaximumCacheSize (uInt howManyPixels)
	Set the maximum allowed cache size for all Arrays in this column of the Table. More...

virtual uInt	maximumCacheSize () const
	Return the maximum allowed cache size (in pixels) for all Arrays in this column of the Table. More...

virtual void	setCacheSizeInTiles (uInt howManyTiles)
	Set the actual cache size for this Array to be big enough for the indicated number of tiles. More...

virtual void	setCacheSizeFromPath (const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
	Set the actual cache size for this Array to "fit" the indicated path. More...

virtual void	clearCache ()
	Clears and frees up the tile cache. More...

virtual void	showCacheStatistics (ostream &os) const
	Generate a report on how the cache is doing. More...

virtual T	getAt (const IPosition &where) const
	Return the value of the single element located at the argument IPosition. More...

virtual void	putAt (const T &value, const IPosition &where)
	Put the value of a single element. More...

virtual Bool	ok () const
	A function which checks for internal consistency. More...

virtual 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 a specified Lattice. More...

virtual Bool	doGetSlice (Array< T > &buffer, const Slicer &section)
	Do the actual getting of an array of values. More...

virtual void	doPutSlice (const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
	Do the actual getting of an array of values. More...

virtual IPosition	doNiceCursorShape (uInt maxPixels) const
	Get the best cursor shape. More...

virtual Bool	lock (FileLocker::LockType, uInt nattempts)
	Handle the (un)locking. More...

virtual void	unlock ()

virtual Bool	hasLock (FileLocker::LockType) const

virtual void	resync ()
	Resynchronize the PagedArray object with the lattice file. More...

virtual void	flush ()
	Flush the data (but do not unlock). More...

virtual void	tempClose ()
	Temporarily close the lattice. More...

virtual void	reopen ()
	Explicitly reopen the temporarily closed lattice. More...

Public Member Functions inherited from casacore::Lattice< T >
virtual	~Lattice ()
	a virtual destructor is needed so that it will use the actual destructor in the derived class More...

virtual DataType	dataType () const
	Get the data type of the lattice. More...

T	operator() (const IPosition &where) const
	Return the value of the single element located at the argument IPosition. More...

Bool	get (COWPtr< Array< T > > &buffer, Bool removeDegenerateAxes=False) const
	Functions which extract an Array of values from a Lattice. More...

Bool	getSlice (COWPtr< Array< T > > &buffer, const Slicer &section, Bool removeDegenerateAxes=False) const

Bool	getSlice (COWPtr< Array< T > > &buffer, const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False) const

Bool	getSlice (COWPtr< Array< T > > &buffer, const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False) const

Bool	get (Array< T > &buffer, Bool removeDegenerateAxes=False)

Bool	getSlice (Array< T > &buffer, const Slicer &section, Bool removeDegenerateAxes=False)

Bool	getSlice (Array< T > &buffer, const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False)

Bool	getSlice (Array< T > &buffer, const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False)

Array< T >	get (Bool removeDegenerateAxes=False) const

Array< T >	getSlice (const Slicer &section, Bool removeDegenerateAxes=False) const

Array< T >	getSlice (const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False) const

Array< T >	getSlice (const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False) const

void	putSlice (const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
	A function which places an Array of values within this instance of the Lattice at the location specified by the IPosition "where", incrementing by "stride". More...

void	putSlice (const Array< T > &sourceBuffer, const IPosition &where)

void	put (const Array< T > &sourceBuffer)

virtual void	set (const T &value)
	Set all elements in the Lattice to the given value. More...

virtual void	apply (T(*function)(T))
	Replace every element, x, of the Lattice with the result of f(x). More...

virtual void	apply (T(*function)(const T &))

virtual void	apply (const Functional< T, T > &function)

void	operator+= (const Lattice< T > &other)
	Add, subtract, multiple, or divide by another Lattice. More...

void	operator-= (const Lattice< T > &other)

void	operator*= (const Lattice< T > &other)

void	operator/= (const Lattice< T > &other)

virtual void	copyData (const Lattice< T > &from)
	Copy the data from the given lattice to this one. More...

virtual void	copyDataTo (Lattice< T > &to) const
	Copy the data from this lattice to the given lattice. More...

Public Member Functions inherited from casacore::LatticeBase
virtual	~LatticeBase ()
	A virtual destructor is needed so that it will use the actual destructor in the derived class. More...

virtual String	imageType () const
	Get the image type (returns name of derived class). More...

virtual Bool	canReferenceArray () const
	Can the lattice data be referenced as an array section? That is the case for an ArrayLattice or a Temp/SubLattice using it. More...

virtual void	save (const String &fileName) const
	Save the image in an AipsIO file with the given name. More...

virtual uInt	ndim () const
	Return the number of axes in this Lattice. More...

virtual size_t	nelements () const
	Return the total number of elements in this Lattice. More...

size_t	size () const

Bool	conform (const LatticeBase &other) const
	Return a value of "True" if this instance of Lattice and 'other' have the same shape, otherwise returns a value of "False". More...

virtual LELCoordinates	lelCoordinates () const
	Return the coordinates of the lattice. More...

IPosition	niceCursorShape (uInt maxPixels) const
	Returns a recommended cursor shape for iterating through all the pixels in the Lattice. More...

IPosition	niceCursorShape () const

Static Public Member Functions
static String	defaultColumn ()
	Returns the default TableColumn name for a PagedArray. More...

static uInt	defaultRow ()
	Returns the default row number for a PagedArray. More...

Private Member Functions
void	setTableType ()
	Set the data in the TableInfo file. More...

void	makeArray (const TiledShape &shape)
	make the ArrayColumn More...

void	makeTable (const String &filename, Table::TableOption option)
	Make a Table to hold this PagedArray. More...

ArrayColumn< T > &	getRWArray ()
	Get the writable ArrayColumn object. More...

void	doReopen () const
	Do the reopen of the table (if not open already). More...

void	tempReopen () const

Static Private Member Functions
static String	defaultComment ()
	The default comment for PagedArray Colums. More...

Private Attributes
Table	itsTable

String	itsColumnName

uInt	itsRowNumber

Bool	itsIsClosed

Bool	itsMarkDelete

String	itsTableName

Bool	itsWritable

TableLock	itsLockOpt

ArrayColumn< T >	itsArray

ROTiledStManAccessor	itsAccessor

Additional Inherited Members
Protected Member Functions inherited from casacore::Lattice< T >
	Lattice ()
	Define default constructor to satisfy compiler. More...

virtual void	handleMath (const Lattice< T > &from, int oper)
	Handle the Math operators (+=, -=, *=, /=). More...

virtual void	handleMathTo (Lattice< T > &to, int oper) const

	Lattice (const Lattice< T > &)
	Copy constructor and assignment can only be used by derived classes. More...

Lattice< T > &	operator= (const Lattice< T > &)

template<>
void	handleMathTo (Lattice< Bool > &, int) const

Protected Member Functions inherited from casacore::LatticeBase
	LatticeBase ()
	Define default constructor to be used by derived classes. More...

	LatticeBase (const LatticeBase &)
	Copy constructor and assignment can only be used by derived classes. More...

LatticeBase &	operator= (const LatticeBase &)

void	throwBoolMath () const
	Throw an exception for arithmetic on a Bool Lattice. More...

Detailed Description

template<class T>
class casacore::PagedArray< T >

A Lattice that is read from or written to disk.

Intended use:

Public interface

Review Status

Reviewed By:: Peter Barnes
Date Reviewed:: 1999/10/30
Test programs:: tPagedArray
Demo programs:: dPagedArray

Prerequisite

Etymology

"Demand paging" is a technique used to implement virtual memory in computer operating systems. In this scheme, code or data are read from disk to memory only as needed by a process, and are read in fixed-sized chunks called "pages". PagedArrays are somewhat the same – though without the automatic features found in virtual memory demand paging. However PagedArrays do allow the user to access chunks of the disk in a flexible way, that can match the requirements of many algorithms.

Synopsis

At the time of writing, typical scientific computers provide sufficient memory for storing and manipulating 2-dimensional astronomical images, which have average size of around 8 MBytes. Astronomy is increasingly using three or higher dimensional arrays, which can be larger by one or two orders of magnitude. PagedArrays provide a convenient way of accessing these large arrays without requiring all the data to be read into real or virtual memory.

When you construct a PagedArray you do not read any data into memory. Instead a disk file (ie. a Table) is created, in a place you specify, to hold the data. This means you need to have enough disk space to hold the array. Constructing a PagedArray is equivalent to opening a file.

Because the data is stored on disk it can be saved after the program, function, or task that created the PagedArray has finished. This saved array can then be read again at a later stage.

So there are two reasons for using a PagedArray:

To provide for arrays that are too large for the computer's memory.
To provide a way of saving arrays to disk for later access.

To access the data in a PagedArray you can either:

Use a LatticeIterator
Use the getSlice and putSlice member functions
Use the parenthesis operator or getAt and putAt functions

These access methods are given in order of preference. Some examples of these access methods are in the documentation for the Lattice class as well as below.

In nearly all cases you access the PagedArray by reading a "slice" of the PagedArray into a Casacore Array. Because the slice is stored in memory it is important that the slice you read is not too big compared to the physical memory on your computer. Otherwise your computer will page excessively and performance will be poor.

To overcome this you may be tempted to access the PagedArray a pixel at a time. This will use little memory but the overhead of accessing a large data set by separately reading each pixel from disk will also lead to poor performance.

In general the best way to access the data in PagedArrays is to use a LatticeIterator with a cursor size that "fits" nicely into memory. Not only do the LaticeIterator classes provide a relatively simple way to read/write all the data but they optimally set up the cache that is associated with each PagedArray.

If the LatticeIterator classes do not access the data the way you want you can use the getSlice and putSlice member functions. These functions do not set up the cache for you and improved performance may be obtained by tweaking the cache using the setCacheSizeFromPath member frunction.

More Details

In order to utilise PagedArrays fully and understand many of the member functions and data access methods in this class, you need to be familiar with some of the concepts involved in the implementation of PagedArrays.

Each PagedArray is stored in one cell of a Table as an indirect Array (see the documentation for the Tables module for more information). This means that multiple PagedArrays can be stored in one Table. To specify which PagedArray you are referring to in a given Table you need to specify the cell using its column name and row number during construction. If a cell is not specified the default column name (as given by the defaultColumnName function) and row number (as given by the defaultRowNumber function) are used. This ability to store multiple PagedArrays's is used in the PagedImage class where the image is stored in one cell and a mask is optionally stored in a another column in the same row.

There are currently a number of limitations when storing multiple PagedArrays in the same Table.

All the PagedArrays in the same column MUST have the same number of dimensions. The dimension used for any particular column is set when the first PagedArray in that column is constructed. If you want to put a say two-dimensional PagedArray into another row of a column that already contains a four-dimensional PagedArray you need to add two degenerate axes. In principle you could use the resize function, but see below for why this is not recommended. It is better to just ensure that all the PagedArrays have the same number of dimensions.
All the cells in a column that contains PagedArrays must have their shape defined. This becomes important if you are creating a PagedArray in say row five of a Table that currently only has one row. The PagedArray constructor will add another four rows to the Table, and put your PagedArray (with the shape you specify) in row five. For the three rows for which no shape was specified, the constructor will construct PagedArrays with only one element (and of an appropriate dimensionality). As you cannot resize these single element PagedArrays without difficulty (see below), it is recommended that you add PagedArrays to rows in your Table sequentially. It is necessary to have the constructor define the shape of all cells in the Table as it is an error to write a Table to disk with undefined cell shapes.

Each PagedArray is stored on disk using the tiled cell storage manager (TiledCellStMan). This stores the data in tiles which are regular subsections of the PagedArray. For example a PagedArray of shape [1024,1024,4,128] may have a tile shape of [32,16,4,16]. The data in each tile is stored as a unit on the disk. This means that there is no preferred axis when accessing multi-dimensional data.
The tile shape can be specified when constructing a new PagedArray but not when reading an old one as it is intrinsic to the way the data is stored on disk. It is NOT recommended that you specify the tile shape unless you can control the lifetime of the PagedArray (this includes the time it spends on disk), or can guarantee the access pattern. For example if you know that a PagedArray of shape [512,512,4,32] will always be sliced plane by plane you may prefer to specify a tile shape of [512,64,1,1] rather than the default of [32,16,4,16].
Tiles can be cached by the tile storage manager so that it does not need to read the data from disk every time you are accessing the a pixel in a different tile. In order to cache the correct tiles you should tell the storage manager what section of the PagedArray you will be accessing. This is done using the setCacheSizeFromPath member function. Alternatively you can set the size of the cache using the setCacheSizeInTiles member function.
By default there is no limit on how much memory the tile cache can consume. This can be changed using the setMaximumCacheSize member function. The tiled storage manager always tries to cache enough tiles to ensure that each tile is read from disk only once, so setting the maximum cache size will trade off memory usage for disk I/O. Setting the cache size is illustrated in example 5 below.
The showCacheStatistics member function is provided to allow you to evaluate the performance of the tile cache.

Example

All the examples in this section are available in dPagedArray.cc

Example 1:

Create a PagedArray of Floats of shape [1024,1024,4,256] in a file called "myData_tmp.array" and initialize it to zero. This will create a directory on disk called "myData_tmp.array" that contains files that exceed 1024*1024*4*256*4 (= 4 GBytes) in size.

const IPosition arrayShape(4,1024,1024,4,256);
const String filename("myData_tmp.array");
PagedArray<Float> diskArray(arrayShape, filename);
cout << "Created a PagedArray of shape " << diskArray.shape() 
<< " (" << diskArray.shape().product()/1024/1024*sizeof(Float) 
<< " MBytes)" << endl
<< "in the table called " << diskArray.tableName() << endl;
diskArray.set(0.0f);
// Using the set function is an efficient way to initialize the PagedArray
// as it uses a PagedArrIter internally. Note that the set function is
// defined in the Lattice class that PagedArray is derived from. 

Example 2:

Read the PagedArray produced in Example 1 and put a Gaussian profile into each spectral channel.

PagedArray<Float> diskArray("myData_tmp.array");
IPosition shape = diskArray.shape();
// Construct a Gaussian Profile to be 10 channels wide and centred on
// channel 16. Its height is 1.0.
Gaussian1D<Float> g(1.0f, 16.0f, 10.0f);
// Create a vector to cache a sampled version of this profile.
Vector<Float> profile(shape(3));
indgen(profile);
profile.apply(g);
// Now put this profile into every spectral channel in the paged array. This
// is best done using an iterator.
LatticeIterator<Float> iter(diskArray, 
TiledLineStepper(shape, diskArray.tileShape(), 3));
for (iter.reset(); !iter.atEnd(); iter++) {
iter.woCursor() = profile;
}

Example 3:

Now multiply the I-polarization data by 10.0 in this PagedArray. The I-polarization data occupies 1 GByte of RAM which is too big to read into the memory of most computers. So an iterator is used to get suitable sized chunks.

Table t("myData_tmp.array", Table::Update);
PagedArray<Float> da(t);
const IPosition latticeShape = da.shape();
const nx = latticeShape(0);
const ny = latticeShape(1);
const npol = latticeShape(2);
const nchan = latticeShape(3);
IPosition cursorShape = da.niceCursorShape();
cursorShape(2) = 1;
LatticeStepper step(latticeShape, cursorShape);
step.subSection(IPosition(4,0), IPosition(4,nx-1,ny-1,0,nchan-1));
LatticeIterator<Float> iter(da, step);
for (iter.reset(); !iter.atEnd(); iter++) {
iter.rwCursor() *= 10.0f;
}

Example 4:

Use a direct call to getSlice to access a small central region of the V-polarization in spectral channel 0 only. The region is small enough to not warrant constructing iterators and setting up LatticeNavigators. In this example the call to the getSlice function is unnecessary but is done for illustration purposes anyway.

SetupNewTable maskSetup("mask_tmp.array", TableDesc(), Table::New);
Table maskTable(maskSetup);
PagedArray<Bool> maskArray(IPosition(4,1024,1024,4,256), maskTable);
maskArray.set(False);
COWPtr<Array<Bool> > maskPtr;
maskArray.getSlice(maskPtr, IPosition(4,240,240,3,0),
IPosition(4,32,32,1,1), IPosition(4,1));
maskPtr.rwRef() = True;
maskArray.putSlice(*maskPtr, IPosition(4,240,240,3,1));

Example 5:

In this example the data in the PagedArray will be accessed a row at a time while setting the cache size to different values. The comments illustrate the results when running on an Ultra 1/140 with 64MBytes of memory.

PagedArray<Float> pa(IPosition(4,128,128,4,32));
const IPosition latticeShape = pa.shape();
cout << "The tile shape is:" << pa.tileShape() << endl;
// The tile shape is:[32, 16, 4, 16]
// Setup to access the PagedArray a row at a time
const IPosition sliceShape(4,latticeShape(0), 1, 1, 1);
const IPosition stride(4,1);
Array<Float> row(sliceShape);
IPosition start(4, 0);
// Set the cache size to enough pixels for one tile only. This uses
// 128kBytes of cache memory and takes 125 secs.
pa.setCacheSizeInTiles (1);
Timer clock;
for (start(3) = 0; start(3) < latticeShape(3); start(3)++) {
for (start(2) = 0; start(2) < latticeShape(2); start(2)++) {
for (start(1) = 0; start(1) < latticeShape(1); start(1)++) {
pa.getSlice(row,  start, sliceShape, stride);
}
}
}
clock.show();
pa.showCacheStatistics(cout);
pa.clearCache();
// Set the cache size to enough pixels for one row of tiles (ie. 4).
// This uses 512 kBytes of cache memory and takes 10 secs.
pa.setCacheSizeInTiles (4);
clock.mark();
for (start(3) = 0; start(3) < latticeShape(3); start(3)++) {
for (start(2) = 0; start(2) < latticeShape(2); start(2)++) {
for (start(1) = 0; start(1) < latticeShape(1); start(1)++) {
pa.getSlice(row,  start, sliceShape, stride);
}
}
}
clock.show();
pa.showCacheStatistics(cout);
pa.clearCache();
// Set the cache size to enough pixels for one plane of tiles
// (ie. 4*8). This uses 4 MBytes of cache memory and takes 2 secs.
pa.setCacheSizeInTiles (4*8);
clock.mark();
for (start(3) = 0; start(3) < latticeShape(3); start(3)++) {
for (start(2) = 0; start(2) < latticeShape(2); start(2)++) {
for (start(1) = 0; start(1) < latticeShape(1); start(1)++) {
pa.getSlice(row,  start, sliceShape, stride);
}
}
}
clock.show();
pa.showCacheStatistics(cout);
pa.clearCache();

Motivation

Arrays of data are sometimes much too large to hold in random access memory. PagedArrays, especially in combination with LatticeIterator, provide convenient access to such large data sets.

Template Type Argument Requirements (T)

Due to storage in Tables, the templated type must be able to be stored in a Casacore Table. This restricts the template argument to all the common types Bool, Float, Double, Complex, String etc.) More details can be found in the RetypedArrayEngine class.

To Do

A better way of resizing PagedArrays

Definition at line 373 of file PagedArray.h.

Constructor & Destructor Documentation

template<class T>

casacore::PagedArray< T >::PagedArray ( )

The default constructor creates a PagedArray that is useless for just about everything, except that it can be assigned to with the assignment operator.

template<class T>

casacore::PagedArray< T >::PagedArray	(	const TiledShape &	shape,
		const String &	filename
	)

Construct a new PagedArray with the specified shape.

A new Table with the specified filename is constructed to hold the array. The Table will remain on disk after the PagedArray goes out of scope or is deleted.

template<class T>

casacore::PagedArray< T >::PagedArray ( const TiledShape & shape )

explicit

Construct a new PagedArray with the specified shape.

A scratch Table is created in the current working directory to hold the array. This Table will be deleted automatically when the PagedArray goes out of scope or is deleted.

template<class T>

casacore::PagedArray< T >::PagedArray	(	const TiledShape &	shape,
		Table &	file
	)

Construct a new PagedArray, with the specified shape, in the default row and column of the supplied Table.

template<class T>

casacore::PagedArray< T >::PagedArray	(	const TiledShape &	shape,
		Table &	file,
		const String &	columnName,
		uInt	rowNum
	)

Construct a new PagedArray, with the specified shape, in the specified row and column of the supplied Table.

template<class T>

casacore::PagedArray< T >::PagedArray ( const String & filename )

explicit

Reconstruct from a pre-existing PagedArray in the default row and column of the supplied Table with the supplied filename.

template<class T>

casacore::PagedArray< T >::PagedArray ( Table & file )

explicit

Reconstruct from a pre-existing PagedArray in the default row and column of the supplied Table.

template<class T>

casacore::PagedArray< T >::PagedArray	(	Table &	file,
		const String &	columnName,
		uInt	rowNum
	)

Reconstruct from a pre-existing PagedArray in the specified row and column of the supplied Table.

template<class T>

casacore::PagedArray< T >::PagedArray ( const PagedArray< T > & other )

The copy constructor which uses reference semantics.

Copying by value doesn't make sense, because it would require the creation of a temporary (but possibly huge) file on disk.

template<class T>

casacore::PagedArray< T >::~PagedArray ( )

The destructor flushes the PagedArrays contents to disk.

Member Function Documentation

template<class T >

const ROTiledStManAccessor & casacore::PagedArray< T >::accessor ( ) const

inline

Returns an accessor to the tiled storage manager.

Definition at line 645 of file PagedArray.h.

template<class T>

virtual uInt casacore::PagedArray< T >::advisedMaxPixels ( ) const

virtual

Returns the maximum recommended number of pixels for a cursor.

This is the number of pixels in a tile.

Reimplemented from casacore::Lattice< T >.

template<class T>

virtual void casacore::PagedArray< T >::clearCache ( )

virtual

Clears and frees up the tile cache.

The maximum allowed cache size is unchanged from when setMaximumCacheSize was last called.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Lattice<T>* casacore::PagedArray< T >::clone ( ) const

virtual

Make a copy of the object (reference semantics).

Implements casacore::Lattice< T >.

template<class T >

const String & casacore::PagedArray< T >::columnName ( ) const

inline

Returns the current Table column name of this PagedArray.

Definition at line 633 of file PagedArray.h.

template<class T >

String casacore::PagedArray< T >::defaultColumn ( )

inlinestatic

Returns the default TableColumn name for a PagedArray.

Definition at line 639 of file PagedArray.h.

template<class T>

static String casacore::PagedArray< T >::defaultComment ( )

staticprivate

The default comment for PagedArray Colums.

template<class T >

uInt casacore::PagedArray< T >::defaultRow ( )

inlinestatic

Returns the default row number for a PagedArray.

Definition at line 657 of file PagedArray.h.

template<class T>

virtual Bool casacore::PagedArray< T >::doGetSlice	(	Array< T > &	buffer,
		const Slicer &	section
	)

virtual

Do the actual getting of an array of values.

Implements casacore::Lattice< T >.

template<class T>

virtual IPosition casacore::PagedArray< T >::doNiceCursorShape ( uInt maxPixels ) const

virtual

Get the best cursor shape.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual void casacore::PagedArray< T >::doPutSlice	(	const Array< T > &	sourceBuffer,
		const IPosition &	where,
		const IPosition &	stride
	)

virtual

Do the actual getting of an array of values.

Implements casacore::Lattice< T >.

template<class T >

void casacore::PagedArray< T >::doReopen ( ) const

private

Do the reopen of the table (if not open already).

Definition at line 663 of file PagedArray.h.

template<class T>

virtual void casacore::PagedArray< T >::flush ( )

virtual

Flush the data (but do not unlock).

Reimplemented from casacore::LatticeBase.

template<class T>

virtual T casacore::PagedArray< T >::getAt ( const IPosition & where ) const

virtual

Return the value of the single element located at the argument IPosition.

Note that Lattice::operator() can also be used.

Reimplemented from casacore::Lattice< T >.

template<class T >

ArrayColumn< T > & casacore::PagedArray< T >::getRWArray ( )

inlineprivate

Get the writable ArrayColumn object.

It reopens the table for write if needed.

Definition at line 607 of file PagedArray.h.

References casacore::True.

template<class T>

virtual Bool casacore::PagedArray< T >::hasLock ( FileLocker::LockType ) const

virtual

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Bool casacore::PagedArray< T >::isPaged ( ) const

virtual

A PagedArray is always paged to disk.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Bool casacore::PagedArray< T >::isPersistent ( ) const

virtual

A PagedArray is always persistent.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Bool casacore::PagedArray< T >::isWritable ( ) const

virtual

Is the PagedArray writable?

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Bool casacore::PagedArray< T >::lock	(	FileLocker::LockType	,
		uInt	nattempts
	)

virtual

Handle the (un)locking.

Reimplemented from casacore::LatticeBase.

template<class T>

void casacore::PagedArray< T >::makeArray ( const TiledShape & shape )

private

make the ArrayColumn

template<class T>

virtual LatticeIterInterface<T>* casacore::PagedArray< T >::makeIter	(	const LatticeNavigator &	navigator,
		Bool	useRef
	)		const

virtual

This function is used by the LatticeIterator class to generate an iterator of the correct type for a specified Lattice.

Not recommended for general use.

Reimplemented from casacore::Lattice< T >.

template<class T>

void casacore::PagedArray< T >::makeTable	(	const String &	filename,
		Table::TableOption	option
	)

private

Make a Table to hold this PagedArray.

template<class T>

virtual uInt casacore::PagedArray< T >::maximumCacheSize ( ) const

virtual

Return the maximum allowed cache size (in pixels) for all Arrays in this column of the Table.

The actual cache size may be smaller. A value of zero means that no maximum is currently defined.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual String casacore::PagedArray< T >::name ( Bool stripPath = False ) const

virtual

Return the current Table name.

By default this includes the full path. The path preceeding the file name can be stripped off on request.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual Bool casacore::PagedArray< T >::ok ( ) const

virtual

A function which checks for internal consistency.

Returns False if something nasty has happened to the PagedArray. In that case it also throws an exception.

Reimplemented from casacore::LatticeBase.

template<class T>

PagedArray<T>& casacore::PagedArray< T >::operator= ( const PagedArray< T > & other )

The assignment operator with reference semantics.

As with the copy constructor assigning by value does not make sense.

template<class T>

virtual void casacore::PagedArray< T >::putAt	(	const T &	value,
		const IPosition &	where
	)

virtual

Put the value of a single element.

Reimplemented from casacore::Lattice< T >.

template<class T>

virtual void casacore::PagedArray< T >::reopen ( )

virtual

Explicitly reopen the temporarily closed lattice.

Reimplemented from casacore::LatticeBase.

template<class T>

void casacore::PagedArray< T >::resize ( const TiledShape & newShape )

Functions to resize the PagedArray.

The old contents are lost. Usage of this function is NOT currently recommended (see the More Details section above).

template<class T>

virtual void casacore::PagedArray< T >::resync ( )

virtual

Resynchronize the PagedArray 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.

Reimplemented from casacore::LatticeBase.

template<class T >

uInt casacore::PagedArray< T >::rowNumber ( ) const

inline

Returns the current row number of this PagedArray.

Definition at line 651 of file PagedArray.h.

template<class T>

virtual void casacore::PagedArray< T >::setCacheSizeFromPath	(	const IPosition &	sliceShape,
		const IPosition &	windowStart,
		const IPosition &	windowLength,
		const IPosition &	axisPath
	)

virtual

Set the actual cache size for this Array to "fit" the indicated path.

This cache is not shared with PagedArrays in other rows and is always less than the maximum value. The sliceShape is the cursor or slice that you will be requiring (with each call to {get,put}Slice). The windowStart and windowLength delimit the range of pixels that will ultimatly be accessed. The AxisPath is described in the documentation for the LatticeStepper class.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual void casacore::PagedArray< T >::setCacheSizeInTiles ( uInt howManyTiles )

virtual

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.

Reimplemented from casacore::LatticeBase.

template<class T>

virtual void casacore::PagedArray< T >::setMaximumCacheSize ( uInt howManyPixels )

virtual

Set the maximum allowed cache size for all Arrays in this column of the Table.

The actual value used may be smaller. A value of zero means that there is no maximum.

Reimplemented from casacore::LatticeBase.

template<class T>

void casacore::PagedArray< T >::setTableType ( )

private

Set the data in the TableInfo file.

template<class T>

virtual IPosition casacore::PagedArray< T >::shape ( ) const

virtual

Returns the shape of the PagedArray.

Implements casacore::LatticeBase.

template<class T>

virtual void casacore::PagedArray< T >::showCacheStatistics ( ostream & os ) const

virtual

Generate a report on how the cache is doing.

This is reset every time clearCache is called.

Reimplemented from casacore::LatticeBase.

template<class T >

Table & casacore::PagedArray< T >::table ( )

inline

Return the current table object.

Definition at line 620 of file PagedArray.h.

template<class T >

const Table & casacore::PagedArray< T >::table ( ) const

inline

Definition at line 626 of file PagedArray.h.

template<class T>

const String& casacore::PagedArray< T >::tableName ( ) const

Returns the current table name (ie.

filename) of this PagedArray.

template<class T>

virtual void casacore::PagedArray< T >::tempClose ( )

virtual

Temporarily close the lattice.

It will be reopened automatically on the next access.

Reimplemented from casacore::LatticeBase.

template<class T>

void casacore::PagedArray< T >::tempReopen ( ) const

private

template<class T>

IPosition casacore::PagedArray< T >::tileShape ( ) const

Returns the current tile shape for this PagedArray.

template<class T>

virtual void casacore::PagedArray< T >::unlock ( )

virtual

Reimplemented from casacore::LatticeBase.

Member Data Documentation

template<class T>

ROTiledStManAccessor casacore::PagedArray< T >::itsAccessor

mutableprivate

Definition at line 602 of file PagedArray.h.

template<class T>

ArrayColumn<T> casacore::PagedArray< T >::itsArray

mutableprivate

Definition at line 601 of file PagedArray.h.

template<class T>

String casacore::PagedArray< T >::itsColumnName

private

Definition at line 594 of file PagedArray.h.

template<class T>

Bool casacore::PagedArray< T >::itsIsClosed

mutableprivate

Definition at line 596 of file PagedArray.h.

template<class T>

TableLock casacore::PagedArray< T >::itsLockOpt

private

Definition at line 600 of file PagedArray.h.

template<class T>

Bool casacore::PagedArray< T >::itsMarkDelete

mutableprivate

Definition at line 597 of file PagedArray.h.

template<class T>

uInt casacore::PagedArray< T >::itsRowNumber

private

Definition at line 595 of file PagedArray.h.

template<class T>

Table casacore::PagedArray< T >::itsTable

mutableprivate

Definition at line 593 of file PagedArray.h.

template<class T>

String casacore::PagedArray< T >::itsTableName

private

Definition at line 598 of file PagedArray.h.

template<class T>

Bool casacore::PagedArray< T >::itsWritable

private

Definition at line 599 of file PagedArray.h.

The documentation for this class was generated from the following file:

lattices/Lattices/PagedArray.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

template<class T> class casacore::PagedArray< T >

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

More Details

Example

Example 1:

Example 2:

Example 3:

Example 4:

Example 5:

Motivation

Template Type Argument Requirements (T)

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class T>
class casacore::PagedArray< T >