Isis 3 Programmer Reference
Isis::CubeIoHandler Class Referenceabstract


Handles converting buffers to and from disk. More...

#include <CubeIoHandler.h>

Inheritance diagram for Isis::CubeIoHandler:
Inheritance graph
Collaboration diagram for Isis::CubeIoHandler:
Collaboration graph

Classes

class  BufferToChunkWriter
 This class is designed to handle write() asynchronously. More...
 

Public Member Functions

 CubeIoHandler (QFile *dataFile, const QList< int > *virtualBandList, const Pvl &label, bool alreadyOnDisk)
 Creates a new CubeIoHandler using a RegionalCachingAlgorithm. More...
 
virtual ~CubeIoHandler ()
 Cleans up all allocated memory. More...
 
void read (Buffer &bufferToFill) const
 Read cube data from disk into the buffer. More...
 
void write (const Buffer &bufferToWrite)
 Write buffer data into the cube data on disk. More...
 
void addCachingAlgorithm (CubeCachingAlgorithm *algorithm)
 This will add the given caching algorithm to the list of attempted caching algorithms. More...
 
void clearCache (bool blockForWriteCache=true) const
 Free all cube chunks (cached cube data) from memory and write them to disk. More...
 
BigInt getDataSize () const
 
void setVirtualBands (const QList< int > *virtualBandList)
 This changes the virtual band list. More...
 
virtual void updateLabels (Pvl &labels)=0
 Function to update the labels with a Pvl object. More...
 
QMutex * dataFileMutex ()
 Get the mutex that this IO handler is using around I/Os on the given data file. More...
 

Protected Member Functions

int bandCount () const
 
int getBandCountInChunk () const
 
BigInt getBytesPerChunk () const
 
int getChunkCountInBandDimension () const
 
int getChunkCountInLineDimension () const
 
int getChunkCountInSampleDimension () const
 
int getChunkIndex (const RawCubeChunk &) const
 Given a chunk, what's its index in the file. More...
 
BigInt getDataStartByte () const
 
QFile * getDataFile ()
 
int lineCount () const
 
int getLineCountInChunk () const
 
PixelType pixelType () const
 
int sampleCount () const
 
int getSampleCountInChunk () const
 
void setChunkSizes (int numSamples, int numLines, int numBands)
 This should be called once from the child constructor. More...
 
virtual void readRaw (RawCubeChunk &chunkToFill)=0
 This needs to populate the chunkToFill with unswapped raw bytes from the disk. More...
 
virtual void writeRaw (const RawCubeChunk &chunkToWrite)=0
 This needs to write the chunkToWrite directly to disk with no modifications to the data itself. More...
 

Private Member Functions

 CubeIoHandler (const CubeIoHandler &other)
 Disallow copying of this object. More...
 
CubeIoHandleroperator= (const CubeIoHandler &other)
 Disallow assignments of this object. More...
 
void blockUntilThreadPoolEmpty () const
 This blocks (doesn't return) until the number of active runnables in the thread pool goes to 0. More...
 
QPair< QList< RawCubeChunk * >, QList< int > > findCubeChunks (int startSample, int numSamples, int startLine, int numLines, int startBand, int numBands) const
 Get the cube chunks that correspond to the given cube area. More...
 
void findIntersection (const RawCubeChunk &cube1, const Buffer &cube2, int &startX, int &startY, int &startZ, int &endX, int &endY, int &endZ) const
 Find the intersection between the buffer area and the cube chunk. More...
 
void flushWriteCache (bool force=false) const
 This attempts to write the so-far-unwritten buffers from m_writeCache into the cube's RawCubeChunk cache. More...
 
void freeChunk (RawCubeChunk *chunkToFree) const
 If the chunk is dirty, then we write it to disk. More...
 
RawCubeChunkgetChunk (int chunkIndex, bool allocateIfNecessary) const
 Retrieve the cached chunk at the given chunk index, if there is one. More...
 
int getChunkCount () const
 
void getChunkPlacement (int chunkIndex, int &startSample, int &startLine, int &startBand, int &endSample, int &endLine, int &endBand) const
 Get the X/Y/Z (Sample,Line,Band) range of the chunk at the given index. More...
 
RawCubeChunkgetNullChunk (int chunkIndex) const
 This creates a chunk filled with NULLs whose placement is at chunkIndex's position. More...
 
void minimizeCache (const QList< RawCubeChunk *> &justUsed, const Buffer &justRequested) const
 Apply the caching algorithms and get rid of excess cube data in memory. More...
 
void synchronousWrite (const Buffer &bufferToWrite)
 This method takes the given buffer and synchronously puts it into the Cube's cache. More...
 
void writeIntoDouble (const RawCubeChunk &chunk, Buffer &output, int startIndex) const
 Write the intersecting area of the chunk into the buffer. More...
 
void writeIntoRaw (const Buffer &buffer, RawCubeChunk &output, int index) const
 Write the intersecting area of the buffer into the chunk. More...
 
void writeNullDataToDisk () const
 Write all NULL cube chunks that have not yet been accessed to disk. More...
 

Static Private Member Functions

static bool bufferLessThan (Buffer *const &lhs, Buffer *const &rhs)
 This is used for sorting buffers into the most efficient write order. More...
 

Private Attributes

QFile * m_dataFile
 The file containing cube data. More...
 
BigInt m_startByte
 The start byte of the cube data. More...
 
PixelType m_pixelType
 The format of each DN in the cube. More...
 
double m_base
 The additive offset of the data on disk. More...
 
double m_multiplier
 The multiplicative factor of the data on disk. More...
 
ByteOrder m_byteOrder
 The byte order (endianness) of the data on disk. More...
 
EndianSwapperm_byteSwapper
 A helper that swaps byte order to and from file order. More...
 
int m_numSamples
 The number of samples in the cube. More...
 
int m_numLines
 The number of lines in the cube. More...
 
int m_numBands
 The number of physical bands in the cube. More...
 
QList< CubeCachingAlgorithm * > * m_cachingAlgorithms
 The caching algorithms to use, in order of priority. More...
 
QMap< int, RawCubeChunk * > * m_rawData
 The map from chunk index to chunk for cached data. More...
 
QMap< int, bool > * m_dataIsOnDiskMap
 The map from chunk index to on-disk status, all true if not allocated. More...
 
QList< int > * m_virtualBands
 Converts from virtual band to physical band. More...
 
int m_samplesInChunk
 The number of samples in a cube chunk. More...
 
int m_linesInChunk
 The number of lines in a cube chunk. More...
 
int m_bandsInChunk
 The number of physical bands in a cube chunk. More...
 
QList< RawCubeChunk * > * m_lastProcessByLineChunks
 This is an optimization for process by line. More...
 
QByteArray * m_nullChunkData
 A raw cube chunk's data when it was all NULL's. Used for speed. More...
 
QPair< QMutex *, QList< Buffer * > > * m_writeCache
 These are the buffers we need to write to raw cube chunks. More...
 
QThreadPool * m_ioThreadPool
 This contains threads for doing cube writes (and later maybe cube reads). More...
 
bool m_lastOperationWasWrite
 If the last operation was a write then we need to flush the cache when reading. More...
 
bool m_useOptimizedCubeWrite
 This is true if the Isis preference for the cube write thread is optimized. More...
 
QMutex * m_writeThreadMutex
 This enables us to block while the write thread is working. More...
 
volatile int m_idealFlushSize
 Ideal write cache flush size. More...
 
int m_consecutiveOverflowCount
 How many times the write cache has overflown in a row. More...
 

Detailed Description


Handles converting buffers to and from disk.

This class handles converting buffers to and from disk. This class holds the cube chunks in memory and is capable of reading and writing them. It asks the caching algorithms to recommend cube chunks to not keep in memory. Children need to call setChunkSizes() in their constructor.

This class handles all of the virtual band conversions. This class also guarantees that unwritten cube data ends up read and written as NULLs. The default caching algorithm is a RegionalCachingAlgorithm.

Author
2011-??-?? Jai Rideout and Steven Lambright
History:

2011-06-27 Steven Lambright - Added addCachingAlgorithm()

2011-07-18 Jai Rideout and Steven Lambright - Added unimplemented copy constructor and assignment operator.

2011-07-18 Jai Rideout and Steven Lambright - getDataFile() is no longer const, along with readRaw() and writeRaw().

2011-11-23 Jai Rideout - Added fix to findCubeChunks() and findIntersection() so that requested areas that are outside of the virtual bands of the cube will no longer fail, but instead will fill the buffer with nulls.

2012-02-17 Steven Lambright - The read() method is now const - the caching should be transparent to the API. It is still important to note that you cannot call read() and write() simultaneously - Cube is guaranteeing this. Backgrounded writes are now implemented and fully supported. Timing tests show results like this: Before: User: 358.71 Kernel: 38.29 Total Elapsed: 6:49.83 After: User: 380.01 Kernel: 44.97 Total Elapsed: 6:19.96 User- user-space CPU time consumed. Kernel- kernel-space CPU time consumed. The CPU consumption and kernel time consumption goes up, but the overall run time is lower. This makes the option perfectly viable for typical multi-core desktop solutions. Turning off the cube write optimization results in equivalent run times as before implementation. These time tests were run before the adaptive cache flush size was added, which improved performance further. References #727.

2012-06-06 Jeff Anderson - The read() method was modified to improve the speed for small buffer sizes as seen in ProcessByBoxcar and ProcessRubbersheet. The internal cache was always checked to be minimized which is slow for every read. Now the cache is only mimimized if it changed in size. Reference #894.

2014-04-07 Kimberly Oyama and Stuart Sides - Modified the findCubeChunks, writeIntoDouble, and writeIntoRaw methods to handle repeating virtual bands. Fixes #1927.

2014-09-30 Ian Humphrey - Modified read method to correctly access virtual bands when cube dimensions and buffer shape are same size. Fixes #1689.

2015-01-30 Ian Humphrey - Modified destructor to free m_writThreadMutex to prevent memory leaks upon destruction. Fixes #2082.

2016-04-21 Makayla Shepherd - Added UnsignedWord pixel type handling.

2016-06-21 Kris Becker - Properly forward declare QPair as struct not class

2016-08-28 Kelvin Rodriguez - updateLabels now a pure virtual, it had no implementation causing warnings in clang. Part of OS X 10.11 porting. QPair forward declaration now properly claims it as a struct.

2017-09-22 Cole Neubauer - Fixed documentation. References #4807

2018-07-20 Tyler Wilson - Added support for unsigned integer special pixel values. in functions writeIntoRaw(...) and writeIntoDouble(...) References #971.

2018-08-13 Summer Stapleton - Fixed incoming buffer comparison values for unsigned int type in writeIntoRaw(...).

Definition at line 125 of file CubeIoHandler.h.

Constructor & Destructor Documentation

◆ CubeIoHandler() [1/2]

Isis::CubeIoHandler::CubeIoHandler ( QFile *  dataFile,
const QList< int > *  virtualBandList,
const Pvl label,
bool  alreadyOnDisk 
)

Creates a new CubeIoHandler using a RegionalCachingAlgorithm.

The chunk sizes must be set by a child in its constructor.

Parameters
dataFileThe file that contains cube data. This should be a valid, opened QFile and may not be NULL. The file should have at least read permissions.
virtualBandListA list where the indices are the vbands and the values are the physical bands. The values are 1-based. This can be specified as NULL, in which case the vbands are the physical bands. The virtual band list is copied (the pointer provided isn't remembered).
labelThe label which contains the "Pixels" and "Core" groups.
alreadyOnDiskTrue if the cube exists; false ensures all NULLs are initialized into the file before this object is destructed.

Definition at line 79 of file CubeIoHandler.cpp.

References _FILEINFO_, Isis::IString::DownCase(), Isis::PvlObject::findGroup(), Isis::PvlContainer::findKeyword(), Isis::PvlObject::findKeyword(), Isis::PvlObject::findObject(), and Isis::PixelTypeEnumeration().

◆ ~CubeIoHandler()

Isis::CubeIoHandler::~CubeIoHandler ( )
virtual

Cleans up all allocated memory.

Child destructors must call clearCache() because we can no longer do IO by the time this destructor is called.

Definition at line 173 of file CubeIoHandler.cpp.

◆ CubeIoHandler() [2/2]

Isis::CubeIoHandler::CubeIoHandler ( const CubeIoHandler other)
private

Disallow copying of this object.

Parameters
otherThe object to copy.

Member Function Documentation

◆ addCachingAlgorithm()

void Isis::CubeIoHandler::addCachingAlgorithm ( CubeCachingAlgorithm algorithm)

This will add the given caching algorithm to the list of attempted caching algorithms.

The algorithms are tried in the opposite order that they were added - the first algorithm added is the last algorithm tried.

This method takes ownership of algorithm.

Parameters
algorithmThe caching algorithm to add to the Cube for I/O

Definition at line 384 of file CubeIoHandler.cpp.

◆ bandCount()

int Isis::CubeIoHandler::bandCount ( ) const
protected
Returns
the number of physical bands in the cube.

Definition at line 482 of file CubeIoHandler.cpp.

◆ blockUntilThreadPoolEmpty()

void Isis::CubeIoHandler::blockUntilThreadPoolEmpty ( ) const
private

This blocks (doesn't return) until the number of active runnables in the thread pool goes to 0.

This uses the m_writeThreadMutex, because the thread pool doesn't delete threads immediately, so runnables might actually still exist but are inconsequential/being deleted already.

Definition at line 690 of file CubeIoHandler.cpp.

◆ bufferLessThan()

bool Isis::CubeIoHandler::bufferLessThan ( Buffer *const &  lhs,
Buffer *const &  rhs 
)
staticprivate

This is used for sorting buffers into the most efficient write order.

Parameters
lhsThe left hand side of the '<' operator
rhsThe right hand side of the '<' operator
Returns
True if lhs is obviously earlier in a cube than rhs.

Definition at line 704 of file CubeIoHandler.cpp.

References Isis::Buffer::Band(), Isis::Buffer::BandDimension(), Isis::Area3D::intersect(), Isis::Area3D::isValid(), Isis::Buffer::Line(), Isis::Buffer::LineDimension(), Isis::Buffer::Sample(), and Isis::Buffer::SampleDimension().

◆ clearCache()

void Isis::CubeIoHandler::clearCache ( bool  blockForWriteCache = true) const

Free all cube chunks (cached cube data) from memory and write them to disk.

Child destructors need to call this method.

This method should only be called otherwise when lots of cubes are in memory and the many caches cause problems with system RAM limitations.

Parameters
blockForWriteCacheThis should be true unless this method is called from the write thread.

Definition at line 399 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::~CubeBsqHandler(), and Isis::CubeTileHandler::~CubeTileHandler().

◆ dataFileMutex()

QMutex * Isis::CubeIoHandler::dataFileMutex ( )

Get the mutex that this IO handler is using around I/Os on the given data file.

A lock should be acquired before doing any reads/writes on the data file externally.

Returns
A mutex that can guarantee exclusive access to the data file

Definition at line 475 of file CubeIoHandler.cpp.

◆ findCubeChunks()

QPair< QList< RawCubeChunk * >, QList< int > > Isis::CubeIoHandler::findCubeChunks ( int  startSample,
int  numSamples,
int  startLine,
int  numLines,
int  startBand,
int  numBands 
) const
private

Get the cube chunks that correspond to the given cube area.

This will create and initialize the chunks if they are not already in memory.

Parameters
startSampleThe starting sample of the cube data
numSamplesThe number of samples of cube data
startLineThe starting line of the cube data
numLinesThe number of lines of cube data
startBandThe starting band of the cube data
numBandsThe number of bands of cube data
Returns
The cube chunks that correspond to the given cube area

The user has requested a slice of a cube (a rectangle):

Cube
-----—

| | | <---------— Requested Area | | | | | -----— |

| |

But our cube is split into "chunks" which may not line up to what was requested:


| | | || |------------------—|| | -----— | || |—|---—|-------—|| (User requested area intersected with | | | | | || cube chunks) |------------------—||

| | | ||


| 1 | 2 | 3 || |------------------—|| | 4 | 5 | 6 || |------------------—|| (User requested area intersected with | 7 | 8 | 9 || cube chunks) |------------------—||

| 10 | 11 | 12 ||

(In this case we want chunks 4, 5, 7, and 8)

So we want to find which cube chunks line up to the requested area. To do this, we find which chunk intersects the top left of the requested cube area. That chunk is a given that we need it. Then we search in the positive X direction for more chunks that intersect the user-requested area until we no longer do. Then we know all of the chunks that intersect a whole y-range of the requested area. We shrink the requested area (remove the found y-range) and repeat.

Definition at line 753 of file CubeIoHandler.cpp.

◆ findIntersection()

void Isis::CubeIoHandler::findIntersection ( const RawCubeChunk cube1,
const Buffer cube2,
int &  startX,
int &  startY,
int &  startZ,
int &  endX,
int &  endY,
int &  endZ 
) const
private

Find the intersection between the buffer area and the cube chunk.

This accounts for virtual bands when considering the buffer and may return an area where all of the bands don't actually intersect due to virtual bands. This is implemented the way it is for performance reasons - so much as returning an Area3D or a QList<int> caused undesirable slowdowns.

Parameters
cube1The cube chunk to intersect
cube2The buffer (in virtual band space) to intersect
startX(output) The leftmost sample position (inclusive)
startY(output) The topmost line position (inclusive)
startZ(output) The frontmost band position (inclusive)
endX(output) The rightmost sample position (inclusive)
endY(output) The bottommost line position (inclusive)
endZ(output) The backmost band position (inclusive)

Definition at line 898 of file CubeIoHandler.cpp.

References Isis::Buffer::Band(), Isis::RawCubeChunk::bandCount(), Isis::Buffer::BandDimension(), Isis::RawCubeChunk::getStartBand(), Isis::RawCubeChunk::getStartLine(), Isis::RawCubeChunk::getStartSample(), Isis::Buffer::Line(), Isis::RawCubeChunk::lineCount(), Isis::Buffer::LineDimension(), Isis::Buffer::Sample(), Isis::RawCubeChunk::sampleCount(), and Isis::Buffer::SampleDimension().

◆ flushWriteCache()

void Isis::CubeIoHandler::flushWriteCache ( bool  force = false) const
private

This attempts to write the so-far-unwritten buffers from m_writeCache into the cube's RawCubeChunk cache.

This will not do anything if there is a runnable and will block if the write cache grows to be too large.

Parameters
forceSet to true to force start a flush

Definition at line 963 of file CubeIoHandler.cpp.

◆ freeChunk()

void Isis::CubeIoHandler::freeChunk ( RawCubeChunk chunkToFree) const
private

If the chunk is dirty, then we write it to disk.

Regardless, we then free it from memory.

Parameters
chunkToFreeThe chunk we're removing from memory

Definition at line 1040 of file CubeIoHandler.cpp.

References Isis::RawCubeChunk::isDirty().

◆ getBandCountInChunk()

int Isis::CubeIoHandler::getBandCountInChunk ( ) const
protected
Returns
the number of bands per chunk for this cube.

Definition at line 490 of file CubeIoHandler.cpp.

◆ getBytesPerChunk()

BigInt Isis::CubeIoHandler::getBytesPerChunk ( ) const
protected
Returns
the byte size of each chunk in the cube. Currently they must be constant size, but this is planned to be changed at some point in time.
Number of bytes in a cube chunk

Definition at line 502 of file CubeIoHandler.cpp.

References Isis::SizeOf().

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and Isis::CubeTileHandler::getTileStartByte().

◆ getChunk()

RawCubeChunk * Isis::CubeIoHandler::getChunk ( int  chunkIndex,
bool  allocateIfNecessary 
) const
private

Retrieve the cached chunk at the given chunk index, if there is one.

Parameters
chunkIndexThe position of the chunk in the cube
allocateIfNecessaryIf true, the chunk will be read into cache when necessary and this method will not return NULL.
Returns
NULL if data is not cached, otherwise the cube file data

Definition at line 1068 of file CubeIoHandler.cpp.

References Isis::RawCubeChunk::setDirty().

◆ getChunkCount()

int Isis::CubeIoHandler::getChunkCount ( ) const
private
Returns
The number of chunks that are required to encapsulate all of the cube data

Definition at line 1109 of file CubeIoHandler.cpp.

◆ getChunkCountInBandDimension()

int Isis::CubeIoHandler::getChunkCountInBandDimension ( ) const
protected
Returns
the total number of chunks in the band (Z) dimension. This is always enough to contain every band in the cube.

Definition at line 512 of file CubeIoHandler.cpp.

◆ getChunkCountInLineDimension()

int Isis::CubeIoHandler::getChunkCountInLineDimension ( ) const
protected
Returns
the total number of chunks in the line (Y) dimension. This is always enough to contain every line in the cube.

Definition at line 521 of file CubeIoHandler.cpp.

◆ getChunkCountInSampleDimension()

int Isis::CubeIoHandler::getChunkCountInSampleDimension ( ) const
protected
Returns
the total number of chunks in the sample (X) dimension. This is always enough to contain every sample in the cube.

Definition at line 530 of file CubeIoHandler.cpp.

◆ getChunkIndex()

int Isis::CubeIoHandler::getChunkIndex ( const RawCubeChunk chunk) const
protected

Given a chunk, what's its index in the file.

Chunks are ordered from left to right, then top to bottom, then front to back (BSQ). The first chunk is at the top left of band 1 and is index 0, for example. In other words, this is going from the value of m_rawData to the key.

Chunks which sit outside of the cube entirely must not be passed into this method; the results will be wrong.

Returns
The chunk's index into the file

Definition at line 546 of file CubeIoHandler.cpp.

References Isis::RawCubeChunk::getStartBand(), Isis::RawCubeChunk::getStartLine(), and Isis::RawCubeChunk::getStartSample().

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and Isis::CubeTileHandler::getTileStartByte().

◆ getChunkPlacement()

void Isis::CubeIoHandler::getChunkPlacement ( int  chunkIndex,
int &  startSample,
int &  startLine,
int &  startBand,
int &  endSample,
int &  endLine,
int &  endBand 
) const
private

Get the X/Y/Z (Sample,Line,Band) range of the chunk at the given index.

Parameters
chunkIndexThe chunk number in the cube file
startSample(output) The leftmost sample position (inclusive)
startLine(output) The topmost line position (inclusive)
startBand(output) The frontmost band position (inclusive)
endSample(output) The rightmost sample position (inclusive)
endLine(output) The bottommost line position (inclusive)
endBand(output) The backmost band position (inclusive)

Definition at line 1127 of file CubeIoHandler.cpp.

◆ getDataFile()

QFile * Isis::CubeIoHandler::getDataFile ( )
protected
Returns
the QFile containing cube data. This is what should be read from and written to.
The data file for I/O

Definition at line 578 of file CubeIoHandler.cpp.

Referenced by Isis::CubeTileHandler::readRaw(), Isis::CubeBsqHandler::readRaw(), Isis::CubeTileHandler::writeRaw(), and Isis::CubeBsqHandler::writeRaw().

◆ getDataSize()

BigInt Isis::CubeIoHandler::getDataSize ( ) const
Returns
the number of bytes that the cube DNs will take up. This includes padding caused by the cube chunks not aligning with the cube dimensions.

Definition at line 441 of file CubeIoHandler.cpp.

◆ getDataStartByte()

BigInt Isis::CubeIoHandler::getDataStartByte ( ) const
protected
Returns
the byte offset to the beginning of the cube data.

Definition at line 567 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::getChunkStartByte(), and Isis::CubeTileHandler::getTileStartByte().

◆ getLineCountInChunk()

int Isis::CubeIoHandler::getLineCountInChunk ( ) const
protected
Returns
the number of lines in each chunk of the cube.

Definition at line 595 of file CubeIoHandler.cpp.

Referenced by Isis::CubeTileHandler::updateLabels().

◆ getNullChunk()

RawCubeChunk * Isis::CubeIoHandler::getNullChunk ( int  chunkIndex) const
private

This creates a chunk filled with NULLs whose placement is at chunkIndex's position.

This is used for getting NULL-filled chunks the first time the chunk is requested.

Ownership of the return value is given to the caller.

Parameters
chunkIndexThe chunk's index which provides it's positioning.
Returns
A chunk filled with nulls at the chunkIndex position

Definition at line 1159 of file CubeIoHandler.cpp.

References Isis::RawCubeChunk::bandCount(), Isis::RawCubeChunk::lineCount(), and Isis::RawCubeChunk::sampleCount().

◆ getSampleCountInChunk()

int Isis::CubeIoHandler::getSampleCountInChunk ( ) const
protected
Returns
the number of samples in each chunk of the cube.

Definition at line 620 of file CubeIoHandler.cpp.

Referenced by Isis::CubeTileHandler::updateLabels().

◆ lineCount()

int Isis::CubeIoHandler::lineCount ( ) const
protected
Returns
the number of lines in the cube. This does not include lines created by the chunk overflowing the line dimension.

Definition at line 587 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler(), and Isis::CubeTileHandler::CubeTileHandler().

◆ minimizeCache()

void Isis::CubeIoHandler::minimizeCache ( const QList< RawCubeChunk *> &  justUsed,
const Buffer justRequested 
) const
private

Apply the caching algorithms and get rid of excess cube data in memory.

This is intended to be called after every IO operation.

Parameters
justUsedThe cube chunks that were used in the IO operation that is calling this method.
justRequestedThe buffer that was used in the IO operation that is calling this method.

Definition at line 1212 of file CubeIoHandler.cpp.

References Isis::CubeCachingAlgorithm::CacheResult::algorithmUnderstoodData(), Isis::CubeCachingAlgorithm::CacheResult::getChunksToFree(), and Isis::CubeCachingAlgorithm::recommendChunksToFree().

◆ operator=()

CubeIoHandler& Isis::CubeIoHandler::operator= ( const CubeIoHandler other)
private

Disallow assignments of this object.

Parameters
otherThe CubeIoHandler on the right-hand side of the assignment that we are copying into *this.
Returns
A reference to *this.

◆ pixelType()

PixelType Isis::CubeIoHandler::pixelType ( ) const
protected
Returns
the physical cube DN format.

Definition at line 603 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler(), and Isis::CubeTileHandler::CubeTileHandler().

◆ read()

void Isis::CubeIoHandler::read ( Buffer bufferToFill) const

Read cube data from disk into the buffer.

This is not const because it caches the read cube chunks from the disk.

Parameters
bufferToFillThe buffer to populate with cube data.

Definition at line 246 of file CubeIoHandler.cpp.

References Isis::Buffer::Band(), Isis::Buffer::BandDimension(), Isis::Buffer::Line(), Isis::Buffer::LineDimension(), Isis::Null, Isis::Buffer::Sample(), Isis::Buffer::SampleDimension(), and Isis::Buffer::size().

◆ readRaw()

virtual void Isis::CubeIoHandler::readRaw ( RawCubeChunk chunkToFill)
protectedpure virtual

This needs to populate the chunkToFill with unswapped raw bytes from the disk.

See also
CubeTileHandler::readRaw()
Parameters
chunkToFillThe container that needs to be filled with cube data.

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

◆ sampleCount()

int Isis::CubeIoHandler::sampleCount ( ) const
protected
Returns
the number of samples in the cube. This does not include samples created by the chunk overflowing the sample dimension.

Definition at line 612 of file CubeIoHandler.cpp.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler(), and Isis::CubeTileHandler::CubeTileHandler().

◆ setChunkSizes()

void Isis::CubeIoHandler::setChunkSizes ( int  numSamples,
int  numLines,
int  numBands 
)
protected

This should be called once from the child constructor.

This determines the chunk sizes used for the cube and often should remain constant for a particular cube (BSQ, for example, doesn't need it to be constant but Tile does). These being large can cause excessive use of disk space that stores no cube data. These being large can also drastically increase the amount of RAM consumed.

Parameters
numSamplesThe chunk size in the sample dimension
numLinesThe chunk size in the line dimension
numBandsThe chunk size in the band dimension

Definition at line 637 of file CubeIoHandler.cpp.

References _FILEINFO_.

Referenced by Isis::CubeBsqHandler::CubeBsqHandler(), and Isis::CubeTileHandler::CubeTileHandler().

◆ setVirtualBands()

void Isis::CubeIoHandler::setVirtualBands ( const QList< int > *  virtualBandList)

This changes the virtual band list.

Parameters
virtualBandListA list where the indices are the vbands and the values are the physical bands. The values are 1-based. This can be specified as NULL, in which case the vbands are the physical bands. The virtual band list is copied (the pointer provided isn't remembered).

Definition at line 458 of file CubeIoHandler.cpp.

◆ synchronousWrite()

void Isis::CubeIoHandler::synchronousWrite ( const Buffer bufferToWrite)
private

This method takes the given buffer and synchronously puts it into the Cube's cache.

This includes reading missing cache areas and freeing extra cache areas. This is what the non-threaded CubeIoHandler::write used to do.

Parameters
bufferToWriteThe buffer we're writing into this cube, synchronously

Definition at line 1261 of file CubeIoHandler.cpp.

References Isis::Buffer::Band(), Isis::Buffer::BandDimension(), Isis::Buffer::Line(), Isis::Buffer::LineDimension(), Isis::Buffer::Sample(), and Isis::Buffer::SampleDimension().

◆ updateLabels()

virtual void Isis::CubeIoHandler::updateLabels ( Pvl labels)
pure virtual

Function to update the labels with a Pvl object.

Parameters
labelsPvl object to update with

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

◆ write()

void Isis::CubeIoHandler::write ( const Buffer bufferToWrite)

Write buffer data into the cube data on disk.

This could do no IO if the cube chunks required are already in memory and our caching algorithms say to not free any of the cube chunks afterwards.

Parameters
bufferToWriteThe buffer to get cube data from.

Definition at line 354 of file CubeIoHandler.cpp.

◆ writeIntoDouble()

void Isis::CubeIoHandler::writeIntoDouble ( const RawCubeChunk chunk,
Buffer output,
int  index 
) const
private

◆ writeIntoRaw()

void Isis::CubeIoHandler::writeIntoRaw ( const Buffer buffer,
RawCubeChunk output,
int  index 
) const
private

◆ writeNullDataToDisk()

void Isis::CubeIoHandler::writeNullDataToDisk ( ) const
private

Write all NULL cube chunks that have not yet been accessed to disk.

Definition at line 1855 of file CubeIoHandler.cpp.

References _FILEINFO_.

◆ writeRaw()

virtual void Isis::CubeIoHandler::writeRaw ( const RawCubeChunk chunkToWrite)
protectedpure virtual

This needs to write the chunkToWrite directly to disk with no modifications to the data itself.

See also
CubeTileHandler::writeRaw()
Parameters
chunkToWriteThe container that needs to be put on disk.

Implemented in Isis::CubeBsqHandler, and Isis::CubeTileHandler.

Member Data Documentation

◆ m_bandsInChunk

int Isis::CubeIoHandler::m_bandsInChunk
private

The number of physical bands in a cube chunk.

Definition at line 339 of file CubeIoHandler.h.

◆ m_base

double Isis::CubeIoHandler::m_base
private

The additive offset of the data on disk.

Definition at line 300 of file CubeIoHandler.h.

◆ m_byteOrder

ByteOrder Isis::CubeIoHandler::m_byteOrder
private

The byte order (endianness) of the data on disk.

Definition at line 306 of file CubeIoHandler.h.

◆ m_byteSwapper

EndianSwapper* Isis::CubeIoHandler::m_byteSwapper
private

A helper that swaps byte order to and from file order.

Definition at line 309 of file CubeIoHandler.h.

◆ m_cachingAlgorithms

QList<CubeCachingAlgorithm *>* Isis::CubeIoHandler::m_cachingAlgorithms
private

The caching algorithms to use, in order of priority.

Definition at line 321 of file CubeIoHandler.h.

◆ m_consecutiveOverflowCount

int Isis::CubeIoHandler::m_consecutiveOverflowCount
mutableprivate

How many times the write cache has overflown in a row.

Definition at line 378 of file CubeIoHandler.h.

◆ m_dataFile

QFile* Isis::CubeIoHandler::m_dataFile
private

The file containing cube data.

Definition at line 287 of file CubeIoHandler.h.

◆ m_dataIsOnDiskMap

QMap<int, bool>* Isis::CubeIoHandler::m_dataIsOnDiskMap
mutableprivate

The map from chunk index to on-disk status, all true if not allocated.

Definition at line 327 of file CubeIoHandler.h.

◆ m_idealFlushSize

volatile int Isis::CubeIoHandler::m_idealFlushSize
mutableprivate

Ideal write cache flush size.

Definition at line 375 of file CubeIoHandler.h.

◆ m_ioThreadPool

QThreadPool* Isis::CubeIoHandler::m_ioThreadPool
mutableprivate

This contains threads for doing cube writes (and later maybe cube reads).

We're using a thread pool so that the same QThread is reused for performance reasons.

Definition at line 358 of file CubeIoHandler.h.

◆ m_lastOperationWasWrite

bool Isis::CubeIoHandler::m_lastOperationWasWrite
mutableprivate

If the last operation was a write then we need to flush the cache when reading.

Keep track of this.

Definition at line 364 of file CubeIoHandler.h.

◆ m_lastProcessByLineChunks

QList<RawCubeChunk *>* Isis::CubeIoHandler::m_lastProcessByLineChunks
mutableprivate

This is an optimization for process by line.

It relies on chunks found often being the exact same between multiple reads or multiple writes.

Definition at line 345 of file CubeIoHandler.h.

◆ m_linesInChunk

int Isis::CubeIoHandler::m_linesInChunk
private

The number of lines in a cube chunk.

Definition at line 336 of file CubeIoHandler.h.

◆ m_multiplier

double Isis::CubeIoHandler::m_multiplier
private

The multiplicative factor of the data on disk.

Definition at line 303 of file CubeIoHandler.h.

◆ m_nullChunkData

QByteArray* Isis::CubeIoHandler::m_nullChunkData
mutableprivate

A raw cube chunk's data when it was all NULL's. Used for speed.

Definition at line 348 of file CubeIoHandler.h.

◆ m_numBands

int Isis::CubeIoHandler::m_numBands
private

The number of physical bands in the cube.

Definition at line 318 of file CubeIoHandler.h.

◆ m_numLines

int Isis::CubeIoHandler::m_numLines
private

The number of lines in the cube.

Definition at line 315 of file CubeIoHandler.h.

◆ m_numSamples

int Isis::CubeIoHandler::m_numSamples
private

The number of samples in the cube.

Definition at line 312 of file CubeIoHandler.h.

◆ m_pixelType

PixelType Isis::CubeIoHandler::m_pixelType
private

The format of each DN in the cube.

Definition at line 297 of file CubeIoHandler.h.

◆ m_rawData

QMap<int, RawCubeChunk *>* Isis::CubeIoHandler::m_rawData
mutableprivate

The map from chunk index to chunk for cached data.

Definition at line 324 of file CubeIoHandler.h.

◆ m_samplesInChunk

int Isis::CubeIoHandler::m_samplesInChunk
private

The number of samples in a cube chunk.

Definition at line 333 of file CubeIoHandler.h.

◆ m_startByte

BigInt Isis::CubeIoHandler::m_startByte
private

The start byte of the cube data.

This is 0-based (i.e. a value of 0 means write data into the first byte of the file). Usually the label is between 0 and m_startByte.

Definition at line 294 of file CubeIoHandler.h.

◆ m_useOptimizedCubeWrite

bool Isis::CubeIoHandler::m_useOptimizedCubeWrite
private

This is true if the Isis preference for the cube write thread is optimized.

Definition at line 369 of file CubeIoHandler.h.

◆ m_virtualBands

QList<int>* Isis::CubeIoHandler::m_virtualBands
private

Converts from virtual band to physical band.

Definition at line 330 of file CubeIoHandler.h.

◆ m_writeCache

QPair< QMutex *, QList<Buffer *> >* Isis::CubeIoHandler::m_writeCache
private

These are the buffers we need to write to raw cube chunks.

Definition at line 351 of file CubeIoHandler.h.

◆ m_writeThreadMutex

QMutex* Isis::CubeIoHandler::m_writeThreadMutex
private

This enables us to block while the write thread is working.

Definition at line 372 of file CubeIoHandler.h.


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