Tiled hypercube in a table. More...

#include <TSMCube.h>

Inheritance diagram for casa::TSMCube:

Public Types
enum	AccessType { NoAccess, CellAccess, SliceAccess, ColumnAccess, ColumnSliceAccess }
	Define the possible access types for TSMDataColumn. More...
Public Member Functions
	TSMCube (TiledStMan stman, TSMFile file, const IPosition &cubeShape, const IPosition &tileShape, const Record &values, Int64 fileOffset, Bool useDerived=False)
	Construct the hypercube using the given file with the given shape.
	TSMCube (TiledStMan *stman, AipsIO &ios, Bool useDerived=False)
	Reconstruct the hypercube by reading its data from the AipsIO stream.
virtual	~TSMCube ()
virtual void	flushCache ()
	Flush the data in the cache.
void	clearCache (Bool doFlush=True)
	Clear the cache, so data will be reread.
void	emptyCache ()
	Empty the cache.
virtual void	showCacheStatistics (ostream &os) const
	Show the cache statistics.
void	putObject (AipsIO &ios)
	Put the data of the object into the AipsIO stream.
Int	getObject (AipsIO &ios)
	Get the data of the object from the AipsIO stream.
virtual void	resync (AipsIO &ios)
	Resync the object with the data file.
Bool	isExtensible () const
	Is the hypercube extensible?
uInt	bucketSize () const
	Get the bucket size (which is the length of a tile in external format).
uInt	localTileLength () const
	Get the lenghth of a tile in local format.
virtual void	setShape (const IPosition &cubeShape, const IPosition &tileShape)
	Set the hypercube shape.
const IPosition &	cubeShape () const
	Get the shape of the hypercube.
const IPosition &	tileShape () const
	Get the shape of the tiles.
IPosition	cellShape () const
	Get the shape of the data cells in the cube.
uInt	coordinateSize (const String &coordinateName) const
	Get the size of a coordinate (i.e.
const Record &	valueRecord () const
	Get the record containing the id and coordinate values.
Record &	rwValueRecord ()
Bool	matches (const PtrBlock< TSMColumn * > &idColSet, const Record &idValues)
	Test if the id values match.
virtual void	extend (uInt nr, const Record &coordValues, const TSMColumn *lastCoordColumn)
	Extend the last dimension of the cube with the given number.
void	extendCoordinates (const Record &coordValues, const String &coordName, uInt length)
	Extend the coordinates vector for the given coordinate to the given length with the given coordValues.
virtual void	accessSection (const IPosition &start, const IPosition &end, char *section, uInt colnr, uInt localPixelSize, uInt externalPixelSize, Bool writeFlag)
	Read or write a section in the cube.
virtual void	accessStrided (const IPosition &start, const IPosition &end, const IPosition &stride, char *section, uInt colnr, uInt localPixelSize, uInt externalPixelSize, Bool writeFlag)
	Read or write a section in a strided way.
uInt	cacheSize () const
	Get the current cache size (in buckets).
uInt	calcCacheSize (const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath) const
	Calculate the cache size (in buckets) for the given slice and access path.
virtual void	setCacheSize (const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller, Bool userSet)
	Set the cache size for the given slice and access path.
virtual void	setCacheSize (uInt cacheSize, Bool forceSmaller, Bool userSet)
	Resize the cache object.
uInt	validateCacheSize (uInt cacheSize) const
	Validate the cache size (in buckets).
Bool	userSetCache () const
	Determine if the user set the cache size (using setCacheSize).
AccessType	getLastColAccess () const
	Functions for TSMDataColumn to keep track of the last type of access to a hypercube.
const IPosition &	getLastColSlice () const
void	setLastColAccess (AccessType type)
void	setLastColSlice (const IPosition &slice)
Static Public Member Functions
static uInt	calcCacheSize (const IPosition &cubeShape, const IPosition &tileShape, Bool extensible, const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, uInt maxCacheSize, uInt bucketSize)
static uInt	validateCacheSize (uInt cacheSize, uInt maxSize, uInt bucketSize)
Protected Member Functions
void	setup ()

void	setupNrTiles ()
IPosition	adjustTileShape (const IPosition &cubeShape, const IPosition &tileShape) const
	Adjust the tile shape to the hypercube shape.
void	resizeTileSections ()
	Resize the IPosition member variables used in accessSection() if nrdim_p changes value.
Protected Attributes
TiledStMan *	stmanPtr_p

Bool	useDerived_p
	Is the class used directly or only by a derived class only?
Record	values_p
	The values of the possible id and coordinate columns.
Bool	extensible_p
	Is the hypercube extensible?
uInt	nrdim_p
	Dimensionality of the hypercube.
uInt	nrTiles_p
	Number of tiles in the hypercube.
IPosition	cubeShape_p
	The shape of the hypercube.
IPosition	tileShape_p
	The shape of the tiles in the hypercube.
IPosition	tilesPerDim_p
	The number of tiles in each hypercube dimension.
TSMShape	expandedTileShape_p
	Precomputed tileShape information.
TSMShape	expandedTilesPerDim_p
	Precomputed tilesPerDim information.
uInt	nrTilesSubCube_p
	Number of tiles in all but last dimension (used when extending).
uInt	tileSize_p
	The tilesize in pixels.
TSMFile *	filePtr_p
	Pointer to the TSMFile object holding the data.
Int64	fileOffset_p
	Offset in the TSMFile object where the data of this hypercube starts.
Block< uInt >	externalOffset_p
	Offset for each data column in a tile (in external format).
Block< uInt >	localOffset_p
	Offset for each data column in a tile (in local format).
uInt	bucketSize_p
	The bucket size in bytes (is equal to tile size in bytes).
uInt	localTileLength_p
	The tile size in bytes in local format.
BucketCache *	cache_p
	The bucket cache.
Bool	userSetCache_p
	Did the user set the cache size?
AccessType	lastColAccess_p
	Was the last column access to a cell, slice, or column?
IPosition	lastColSlice_p
	The slice shape of the last column access to a slice.
IPosition	nrTileSection_p
	IPosition variables used in accessSection(); declared here as member variables to avoid significant construction and desctruction overhead if they are local to accessSection() #tiles needed for the section.
IPosition	startTile_p
	First tile needed.
IPosition	endTile_p
	Last tile needed.
IPosition	startPixelInFirstTile_p
	First pixel in first tile.
IPosition	endPixelInFirstTile_p
	Last pixel in first tile.
IPosition	endPixelInLastTile_p
	Last pixel in last tile.
Private Member Functions
	TSMCube (const TSMCube &)
	Forbid copy constructor.
TSMCube &	operator= (const TSMCube &)
	Forbid assignment.
BucketCache *	getCache ()
	Get the cache object.
virtual void	makeCache ()
	Construct the cache object (if not constructed yet).
virtual void	resyncCache ()
	Resync the cache object.
virtual void	deleteCache ()
	Delete the cache object.
void	accessLine (char section, uInt pixelOffset, uInt localPixelSize, Bool writeFlag, BucketCache cachePtr, const IPosition &startTile, uInt endTile, const IPosition &startPixelInFirstTile, uInt endPixelInLastTile, uInt lineIndex)
	Access a line in a more optimized way.
char *	readTile (const char *external)
	Define the functions doing the actual read and write of the data in the tile and converting it to/from local format.
void	writeTile (char external, const char local)
Static Private Member Functions
static char *	readCallBack (void owner, const char external)
	Define the callback functions for the BucketCache.
static void	writeCallBack (void owner, char external, const char *local)
static char *	initCallBack (void *owner)
static void	deleteCallBack (void owner, char buffer)

Detailed Description

Tiled hypercube in a table.

Intended use:

Internal

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

Prerequisite

TiledStMan
ROTiledStManAccessor for a discussion of the maximum cache size
TSMFile
BucketCache

Etymology

TSMCube represents a hypercube in the Tiled Storage Manager.

Synopsis

TSMCube defines a tiled hypercube. The data is stored in a TSMFile object and accessed using a BucketCache object. The hypercube can be extensible in its last dimension to support tables with a size which is not known in advance.
Normally hypercubes share the same TSMFile object, but extensible hypercubes have their own TSMFile object (to be extensible). If the hypercolumn has multiple data columns, their cells share the same tiles. Per tile data column A appears first, thereafter B, etc..
The data in the cache is held in external format and is converted when accessed. The alternative would be to hold it in the cache in local format and convert it when read/written from the file. It was felt that the latter approach would generate more needless conversions.

The possible id and coordinate values are stored in a Record object. They are written in the main hypercube AipsIO file.

TSMCube uses the maximum cache size set for a Tiled Storage manager. The description of class ROTiledStManAccessor contains a discussion about the effect of setting the maximum cache size.

Motivation

TSMCube encapsulates all operations on a hypercube.

Definition at line 105 of file TSMCube.h.

Member Enumeration Documentation

enum casa::TSMCube::AccessType

Define the possible access types for TSMDataColumn.

Enumerator:

NoAccess
CellAccess
SliceAccess
ColumnAccess
ColumnSliceAccess

Definition at line 109 of file TSMCube.h.

Constructor & Destructor Documentation

casa::TSMCube::TSMCube	(	TiledStMan *	stman,
		TSMFile *	file,
		const IPosition &	cubeShape,
		const IPosition &	tileShape,
		const Record &	values,
		Int64	fileOffset,
		Bool	useDerived = `False`
	)

Construct the hypercube using the given file with the given shape.

The record contains the id and possible coordinate values.
If the cubeshape is empty, the hypercube is still undefined and can be added later with setShape. That is only used by TiledCellStMan.
The fileOffset argument is meant for class TiledFileAccess.

casa::TSMCube::TSMCube	(	TiledStMan *	stman,
		AipsIO &	ios,
		Bool	useDerived = `False`
	)

Reconstruct the hypercube by reading its data from the AipsIO stream.

It will link itself to the correct TSMFile. The TSMFile objects must have been reconstructed in advance.

virtual casa::TSMCube::~TSMCube ( ) [virtual]

casa::TSMCube::TSMCube ( const TSMCube & ) [private]

Forbid copy constructor.

Member Function Documentation

void casa::TSMCube::accessLine	(	char *	section,
		uInt	pixelOffset,
		uInt	localPixelSize,
		Bool	writeFlag,
		BucketCache *	cachePtr,
		const IPosition &	startTile,
		uInt	endTile,
		const IPosition &	startPixelInFirstTile,
		uInt	endPixelInLastTile,
		uInt	lineIndex
	)		`[private]`

Access a line in a more optimized way.

virtual void casa::TSMCube::accessSection	(	const IPosition &	start,
		const IPosition &	end,
		char *	section,
		uInt	colnr,
		uInt	localPixelSize,
		uInt	externalPixelSize,
		Bool	writeFlag
	)		`[virtual]`

Read or write a section in the cube.

It is assumed that the section buffer is long enough.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

virtual void casa::TSMCube::accessStrided	(	const IPosition &	start,
		const IPosition &	end,
		const IPosition &	stride,
		char *	section,
		uInt	colnr,
		uInt	localPixelSize,
		uInt	externalPixelSize,
		Bool	writeFlag
	)		`[virtual]`

Read or write a section in a strided way.

It is assumed that the section buffer is long enough.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

IPosition casa::TSMCube::adjustTileShape	(	const IPosition &	cubeShape,
		const IPosition &	tileShape
	)		const `[protected]`

Adjust the tile shape to the hypercube shape.

A size of 0 gets set to 1. A tile size > cube size gets set to the cube size.

uInt casa::TSMCube::bucketSize ( ) const [inline]

Get the bucket size (which is the length of a tile in external format).

Definition at line 425 of file TSMCube.h.

References bucketSize_p.

uInt casa::TSMCube::cacheSize ( ) const

Get the current cache size (in buckets).

Referenced by casa::TiledFileAccess::cacheSize().

uInt casa::TSMCube::calcCacheSize	(	const IPosition &	sliceShape,
		const IPosition &	windowStart,
		const IPosition &	windowLength,
		const IPosition &	axisPath
	)		const

Calculate the cache size (in buckets) for the given slice and access path.

static uInt casa::TSMCube::calcCacheSize	(	const IPosition &	cubeShape,
		const IPosition &	tileShape,
		Bool	extensible,
		const IPosition &	sliceShape,
		const IPosition &	windowStart,
		const IPosition &	windowLength,
		const IPosition &	axisPath,
		uInt	maxCacheSize,
		uInt	bucketSize
	)		`[static]`

IPosition casa::TSMCube::cellShape ( ) const

Get the shape of the data cells in the cube.

void casa::TSMCube::clearCache ( Bool doFlush = True )

Clear the cache, so data will be reread.

If wanted, the data is flushed before the cache is cleared.

uInt casa::TSMCube::coordinateSize ( const String & coordinateName ) const

Get the size of a coordinate (i.e.

the number of values in it). If not defined, it returns zero.

const IPosition & casa::TSMCube::cubeShape ( ) const [inline]

Get the shape of the hypercube.

Definition at line 433 of file TSMCube.h.

References cubeShape_p.

Referenced by casa::TiledFileAccess::shape().

virtual void casa::TSMCube::deleteCache ( ) [private, virtual]

Delete the cache object.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

static void casa::TSMCube::deleteCallBack	(	void *	owner,
		char *	buffer
	)		`[static, private]`

void casa::TSMCube::emptyCache ( )

Empty the cache.

It will flush the cache as needed and remove all buckets from it resulting in a possibly large drop in memory used. It'll also clear the userSetCache_p flag.

Referenced by casa::TiledFileAccess::clearCache().

virtual void casa::TSMCube::extend	(	uInt	nr,
		const Record &	coordValues,
		const TSMColumn *	lastCoordColumn
	)		`[virtual]`

Extend the last dimension of the cube with the given number.

The record can contain the coordinates of the elements added.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

void casa::TSMCube::extendCoordinates	(	const Record &	coordValues,
		const String &	coordName,
		uInt	length
	)

Extend the coordinates vector for the given coordinate to the given length with the given coordValues.

It will be initialized to zero if no coordValues are given. If the coordinate vector does not exist yet, it will be created.

virtual void casa::TSMCube::flushCache ( ) [virtual]

Flush the data in the cache.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Referenced by casa::TiledFileAccess::flush().

BucketCache * casa::TSMCube::getCache ( ) [inline, private]

Get the cache object.

This will construct the cache object if not present yet.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Definition at line 418 of file TSMCube.h.

References cache_p, and makeCache().

TSMCube::AccessType casa::TSMCube::getLastColAccess ( ) const [inline]

Functions for TSMDataColumn to keep track of the last type of access to a hypercube.

It uses it to determine if the cache has to be reset.

Definition at line 453 of file TSMCube.h.

References lastColAccess_p.

const IPosition & casa::TSMCube::getLastColSlice ( ) const [inline]

Definition at line 457 of file TSMCube.h.

References lastColSlice_p.

Int casa::TSMCube::getObject ( AipsIO & ios )

Get the data of the object from the AipsIO stream.

It returns the data manager sequence number, which is -1 if no file is attached to the cube (for cells without a value).

static char* casa::TSMCube::initCallBack ( void * owner ) [static, private]

Bool casa::TSMCube::isExtensible ( ) const

Is the hypercube extensible?

uInt casa::TSMCube::localTileLength ( ) const [inline]

Get the lenghth of a tile in local format.

Definition at line 429 of file TSMCube.h.

References localTileLength_p.

virtual void casa::TSMCube::makeCache ( ) [private, virtual]

Construct the cache object (if not constructed yet).

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Referenced by getCache().

Bool casa::TSMCube::matches	(	const PtrBlock< TSMColumn * > &	idColSet,
		const Record &	idValues
	)

Test if the id values match.

TSMCube& casa::TSMCube::operator= ( const TSMCube & ) [private]

Forbid assignment.

void casa::TSMCube::putObject ( AipsIO & ios )

Put the data of the object into the AipsIO stream.

static char* casa::TSMCube::readCallBack	(	void *	owner,
		const char *	external
	)		`[static, private]`

Define the callback functions for the BucketCache.

char* casa::TSMCube::readTile ( const char * external ) [private]

Define the functions doing the actual read and write of the data in the tile and converting it to/from local format.

void casa::TSMCube::resizeTileSections ( ) [protected]

Resize the IPosition member variables used in accessSection() if nrdim_p changes value.

virtual void casa::TSMCube::resync ( AipsIO & ios ) [virtual]

Resync the object with the data file.

It reads the object, and adjusts the cache.

virtual void casa::TSMCube::resyncCache ( ) [private, virtual]

Resync the cache object.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Record & casa::TSMCube::rwValueRecord ( ) [inline]

Definition at line 445 of file TSMCube.h.

References values_p.

virtual void casa::TSMCube::setCacheSize	(	const IPosition &	sliceShape,
		const IPosition &	windowStart,
		const IPosition &	windowLength,
		const IPosition &	axisPath,
		Bool	forceSmaller,
		Bool	userSet
	)		`[virtual]`

Set the cache size for the given slice and access path.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Referenced by casa::TiledFileAccess::setCacheSize().

virtual void casa::TSMCube::setCacheSize	(	uInt	cacheSize,
		Bool	forceSmaller,
		Bool	userSet
	)		`[virtual]`

Resize the cache object.

If forceSmaller is False, the cache will only be resized when it grows. If the given size exceeds the maximum size with more than 10%, the maximum size will be used. The cacheSize has to be given in buckets.
The flag userSet inidicates if the cache size is set by the user (by an Accessor object) or automatically (by TSMDataColumn).

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

void casa::TSMCube::setLastColAccess ( TSMCube::AccessType type ) [inline]

Definition at line 461 of file TSMCube.h.

References lastColAccess_p, and type().

void casa::TSMCube::setLastColSlice ( const IPosition & slice ) [inline]

Definition at line 465 of file TSMCube.h.

References lastColSlice_p, casa::IPosition::nelements(), and casa::IPosition::resize().

virtual void casa::TSMCube::setShape	(	const IPosition &	cubeShape,
		const IPosition &	tileShape
	)		`[virtual]`

Set the hypercube shape.

This is only possible if the shape was not defined yet.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

void casa::TSMCube::setup ( ) [protected]

Initialize the various variables.

void casa::TSMCube::setupNrTiles ( ) [protected]

virtual void casa::TSMCube::showCacheStatistics ( ostream & os ) const [virtual]

Show the cache statistics.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Referenced by casa::TiledFileAccess::showCacheStatistics().

const IPosition & casa::TSMCube::tileShape ( ) const [inline]

Get the shape of the tiles.

Definition at line 437 of file TSMCube.h.

References tileShape_p.

Referenced by casa::TiledFileAccess::tileShape().

Bool casa::TSMCube::userSetCache ( ) const [inline]

Determine if the user set the cache size (using setCacheSize).

Definition at line 449 of file TSMCube.h.

References userSetCache_p.

uInt casa::TSMCube::validateCacheSize ( uInt cacheSize ) const

Validate the cache size (in buckets).

This means it will return the given cache size if smaller than the maximum cache size. Otherwise the maximum is returned.

static uInt casa::TSMCube::validateCacheSize	(	uInt	cacheSize,
		uInt	maxSize,
		uInt	bucketSize
	)		`[static]`

const Record & casa::TSMCube::valueRecord ( ) const [inline]

Get the record containing the id and coordinate values.

It is used by TSMIdColumn and TSMCoordColumn.

Definition at line 441 of file TSMCube.h.

References values_p.

static void casa::TSMCube::writeCallBack	(	void *	owner,
		char *	external,
		const char *	local
	)		`[static, private]`

void casa::TSMCube::writeTile	(	char *	external,
		const char *	local
	)		`[private]`

Member Data Documentation

uInt casa::TSMCube::bucketSize_p [protected]

The bucket size in bytes (is equal to tile size in bytes).

Definition at line 387 of file TSMCube.h.

Referenced by bucketSize().

BucketCache* casa::TSMCube::cache_p [protected]

The bucket cache.

Reimplemented in casa::TSMCubeMMap, and casa::TSMCubeBuff.

Definition at line 391 of file TSMCube.h.

Referenced by getCache().

IPosition casa::TSMCube::cubeShape_p [protected]

The shape of the hypercube.

Definition at line 365 of file TSMCube.h.

Referenced by cubeShape().

IPosition casa::TSMCube::endPixelInFirstTile_p [protected]

Last pixel in first tile.

Definition at line 411 of file TSMCube.h.

IPosition casa::TSMCube::endPixelInLastTile_p [protected]

Last pixel in last tile.

Definition at line 413 of file TSMCube.h.

IPosition casa::TSMCube::endTile_p [protected]

Last tile needed.

Definition at line 407 of file TSMCube.h.

TSMShape casa::TSMCube::expandedTileShape_p [protected]

Precomputed tileShape information.

Definition at line 371 of file TSMCube.h.

TSMShape casa::TSMCube::expandedTilesPerDim_p [protected]

Precomputed tilesPerDim information.

Definition at line 373 of file TSMCube.h.

Bool casa::TSMCube::extensible_p [protected]

Is the hypercube extensible?

Definition at line 359 of file TSMCube.h.

Block<uInt> casa::TSMCube::externalOffset_p [protected]

Offset for each data column in a tile (in external format).

Definition at line 383 of file TSMCube.h.

Int64 casa::TSMCube::fileOffset_p [protected]

Offset in the TSMFile object where the data of this hypercube starts.

Definition at line 381 of file TSMCube.h.

TSMFile* casa::TSMCube::filePtr_p [protected]

Pointer to the TSMFile object holding the data.

Definition at line 379 of file TSMCube.h.

AccessType casa::TSMCube::lastColAccess_p [protected]

Was the last column access to a cell, slice, or column?

Definition at line 395 of file TSMCube.h.

Referenced by getLastColAccess(), and setLastColAccess().

IPosition casa::TSMCube::lastColSlice_p [protected]

The slice shape of the last column access to a slice.

Definition at line 397 of file TSMCube.h.

Referenced by getLastColSlice(), and setLastColSlice().

Block<uInt> casa::TSMCube::localOffset_p [protected]

Offset for each data column in a tile (in local format).

Definition at line 385 of file TSMCube.h.

uInt casa::TSMCube::localTileLength_p [protected]

The tile size in bytes in local format.

Definition at line 389 of file TSMCube.h.

Referenced by localTileLength().

uInt casa::TSMCube::nrdim_p [protected]

Dimensionality of the hypercube.

Definition at line 361 of file TSMCube.h.

uInt casa::TSMCube::nrTiles_p [protected]

Number of tiles in the hypercube.

Definition at line 363 of file TSMCube.h.

IPosition casa::TSMCube::nrTileSection_p [protected]

IPosition variables used in accessSection(); declared here as member variables to avoid significant construction and desctruction overhead if they are local to accessSection() #tiles needed for the section.

Definition at line 403 of file TSMCube.h.

uInt casa::TSMCube::nrTilesSubCube_p [protected]

Number of tiles in all but last dimension (used when extending).

Definition at line 375 of file TSMCube.h.

IPosition casa::TSMCube::startPixelInFirstTile_p [protected]

First pixel in first tile.

Definition at line 409 of file TSMCube.h.

IPosition casa::TSMCube::startTile_p [protected]

First tile needed.

Definition at line 405 of file TSMCube.h.

TiledStMan* casa::TSMCube::stmanPtr_p [protected]

Pointer to the parent storage manager.