Encapsulation of Cube I/O with Change Notifications. More...

#include <CubeDataThread.h>

Inheritance diagram for Isis::CubeDataThread:

Collaboration diagram for Isis::CubeDataThread:

Public Slots
void	ReadCube (int cubeId, int startSample, int startLine, int endSample, int endLine, int band, void *caller)
	This slot should be connected to and upon receiving a signal it will begin the necessary cube I/O to get this data.

void	ReadWriteCube (int cubeId, int startSample, int startLine, int endSample, int endLine, int band, void *caller)
	This slot should be connected to and upon receiving a signal it will begin the necessary cube I/O to get this data.

void	DoneWithData (int, const Isis::Brick *)
	When done processing with a brick (reading or writing) this slot needs to be signalled to free locks and memory.

Signals
void	ReadReady (void requester, int cubeId, const Isis::Brick data)
	This signal will be emitted when ReadCube has finished processing.

void	ReadWriteReady (void requester, int cubeId, Isis::Brick data)
	This signal will be emitted when ReadWriteCube has finished processing.

void	BrickChanged (int cubeId, const Isis::Brick *data)
	DO NOT CONNECT TO THIS SIGNAL WITHOUT CALLING AddChangeListener().

Public Member Functions
	CubeDataThread ()
	This constructs a CubeDataThread().

virtual	~CubeDataThread ()
	This class is a self-contained thread, so normally it would be bad to simply delete it.

int	AddCube (const FileName &fileName, bool mustOpenReadWrite=false)
	This method is designed to be callable from any thread before data is requested, though no known side effects exist if this is called during other I/O operations (though I don't recommend it).

int	AddCube (Cube *cube)
	This method is designed to be callable from any thread before data is requested, though no known side effects exist if this is called during other I/O operations (though I don't recommend it).

void	RemoveCube (int cubeId)
	Removes a cube from this lock manager.

void	AddChangeListener ()
	You must call this method after connecting to the BrickChanged signal, otherwise you are not guaranteed a good Brick pointer.

void	RemoveChangeListener ()
	You must call this method after disconnecting from the BrickChanged signal, otherwise bricks cannot be freed from memory.

int	BricksInMemory ()
	This is a helper method for both testing/debugging and general information that provides the current number of bricks in memory.

UniversalGroundMap *	GetUniversalGroundMap (int cubeId) const
	This returns a new Universal Ground Map given a Cube ID.

const Cube *	GetCube (int cubeId) const
	This returns a constant pointer to a Cube at the given Cube ID.

int	FindCubeId (const Cube *) const
	Given a Cube pointer, return the cube ID associated with it.

Detailed Description

Encapsulation of Cube I/O with Change Notifications.

The main purpose of this class is to create cube change notifications, ideal for GUI's with changing cubes. This class is designed to encapsulate Cube I/O into a separate thread and serializes each cube I/O. This class also speeds up I/O by reusing bricks instead of always reading from the disk.

This is not a full concurrency control/transaction handler. Consistent states are not guaranteed, though a consistent state for any given brick is, and results from reads do not guaranteed serial equivalence. Deadlocks are possible, if two processes want to R/W to the same sections of data, and it is up to the users of this class to avoid such conditions.

Author: 2010-01-15 Steven Lambright

Constructor & Destructor Documentation

◆ CubeDataThread()

Isis::CubeDataThread::CubeDataThread ( )

This constructs a CubeDataThread().

This will spawn a new thread and move the ownership of this instance to itself (so slots are called in this self-contained thread).

◆ ~CubeDataThread()

Isis::CubeDataThread::~CubeDataThread ( )

virtual

This class is a self-contained thread, so normally it would be bad to simply delete it.

However, this destructor will synchronize the shutdown of the thread so you can safely delete an instance of this class without using the deleteLater() method.

Member Function Documentation

◆ AddChangeListener()

void Isis::CubeDataThread::AddChangeListener ( )

You must call this method after connecting to the BrickChanged signal, otherwise you are not guaranteed a good Brick pointer.

Referenced by Isis::CubeViewport::CubeViewport(), and Isis::CubeDataThreadTester::NotifyChangeTest().

◆ AddCube() [1/2]

int Isis::CubeDataThread::AddCube	(	const FileName &	fileName,
		bool	mustOpenReadWrite = false )

This method is designed to be callable from any thread before data is requested, though no known side effects exist if this is called during other I/O operations (though I don't recommend it).

If possible, the cube will be opened with R/W permissions, otherwise it will be opened with read-only access

Parameters

fileName	The cube to open
mustOpenReadWrite	If true and cube has read-only access then an exception will be thrown

Returns: int The cube ID necessary for retrieving information about this cube in the future.

References Isis::FileName::expanded().

Referenced by Isis::CubeViewport::CubeViewport().

◆ AddCube() [2/2]

int Isis::CubeDataThread::AddCube ( Cube * cube )

This method is designed to be callable from any thread before data is requested, though no known side effects exist if this is called during other I/O operations (though I don't recommend it).

Ownership is not taken of this cube

Parameters

cube	The cube to encapsulate

Returns: int The cube ID necessary for retrieving information about this cube in the future.

◆ BrickChanged

void Isis::CubeDataThread::BrickChanged	(	int	cubeId,
		const Isis::Brick *	data )

signal

DO NOT CONNECT TO THIS SIGNAL WITHOUT CALLING AddChangeListener().

When a write occurs, and change listeners exist, this signal is emitted with the new data.

When done with the data, given you are the requester, you call the DoneWithData slot (via a signal).

Parameters

cubeId	Cube ID of the change
data	Area written to the cube

Referenced by DoneWithData().

◆ BricksInMemory()

int Isis::CubeDataThread::BricksInMemory ( )

This is a helper method for both testing/debugging and general information that provides the current number of bricks in memory.

Returns: int Count of how many bricks reside in memory.

◆ DoneWithData

void Isis::CubeDataThread::DoneWithData	(	int	cubeId,
		const Isis::Brick *	brickDone )

slot

When done processing with a brick (reading or writing) this slot needs to be signalled to free locks and memory.

Parameters

cubeId	Cube associated with the brick
brickDone	Brick pointer given by ReadReady, ReadWriteReady or BrickChanged. An equivalent brick is also acceptable (exact same range, but not same pointer).

References _FILEINFO_, BrickChanged(), and Isis::IException::Programmer.

◆ FindCubeId()

int Isis::CubeDataThread::FindCubeId ( const Cube * cubeToFind ) const

Given a Cube pointer, return the cube ID associated with it.

Parameters

cubeToFind Cube to look up the ID for

Returns: the cube ID associated the given Cube pointer

References _FILEINFO_, and Isis::IException::Programmer.

Referenced by Isis::CubeViewport::CubeViewport().

◆ GetCube()

const Cube * Isis::CubeDataThread::GetCube ( int cubeId ) const

This returns a constant pointer to a Cube at the given Cube ID.

Parameters

cubeId The Cube ID of the Cube that needs its pointer returned

Returns: A thread-safe pointer to the requested Cube.

References _FILEINFO_, and Isis::IException::Programmer.

◆ GetUniversalGroundMap()

UniversalGroundMap * Isis::CubeDataThread::GetUniversalGroundMap ( int cubeId ) const

This returns a new Universal Ground Map given a Cube ID.

Ownership is given to the caller.

Parameters

cubeId The Cube ID of the Cube that needs its ground map returned.

Returns: UniversalGroundMap * Ground Map associated with the cube.

References _FILEINFO_, and Isis::IException::Programmer.

◆ ReadCube

void Isis::CubeDataThread::ReadCube	(	int	cubeId,
		int	startSample,
		int	startLine,
		int	endSample,
		int	endLine,
		int	band,
		void *	caller )

slot

This slot should be connected to and upon receiving a signal it will begin the necessary cube I/O to get this data.

When the data is available, a ReadReady signal will be emitted with the parameter caller being equal to the requester pointer in the signal. You should pass "this" for caller, and you must ignore all ReadReady signals which do not have "requester == this" -> otherwise your pointer is not guaranteed.

Parameters

cubeId	Cube to read from
startSample	Starting Sample Position
startLine	Starting Line Position
endSample	Ending Sample Position
endLine	Ending Line Position
band	Band Number To Read From (multi-band bricks not supported at this time)
caller	A pointer to the calling class, used to identify who requested the data when they receive the ReadReady signal

References _FILEINFO_, and Isis::IException::Programmer.

◆ ReadReady

void Isis::CubeDataThread::ReadReady	(	void *	requester,
		int	cubeId,
		const Isis::Brick *	data )

signal

This signal will be emitted when ReadCube has finished processing.

When done with the data, given you are the requester, you call the DoneWithData slot (via a signal).

Parameters

requester	Pointer to the calling class (must ignore all ReadReady signals where this != requester)
cubeId	Cube ID of the cube the data is from
data	The data in the cube

◆ ReadWriteCube

void Isis::CubeDataThread::ReadWriteCube	(	int	cubeId,
		int	startSample,
		int	startLine,
		int	endSample,
		int	endLine,
		int	band,
		void *	caller )

slot

This slot should be connected to and upon receiving a signal it will begin the necessary cube I/O to get this data.

When the data is available, a ReadWriteReady signal will be emitted with the parameter caller being equal to the requester pointer in the signal. You should pass "this" for caller, and you must ignore all ReadReady signals which do not have "requester == this" -> otherwise your pointer is not guaranteed and you are corrupting the process of the real requester.

Parameters

cubeId	Cube to read from
startSample	Starting Sample Position
startLine	Starting Line Position
endSample	Ending Sample Position
endLine	Ending Line Position
band	Band Number To Read From (multi-band bricks not supported at this time)
caller	A pointer to the calling class, used to identify who requested the data when they receive the ReadWriteReady signal

References _FILEINFO_, and Isis::IException::Programmer.

◆ ReadWriteReady

void Isis::CubeDataThread::ReadWriteReady	(	void *	requester,
		int	cubeId,
		Isis::Brick *	data )

signal

This signal will be emitted when ReadWriteCube has finished processing.

When done with the data, given you are the requester, you call the DoneWithData slot (via a signal).

Parameters

requester	Pointer to the calling class (must ignore all ReadReady signals where this != requester)
cubeId	Cube ID of the cube the data is from
data	The data in the cube, also where you should write changes

◆ RemoveChangeListener()

void Isis::CubeDataThread::RemoveChangeListener ( )

You must call this method after disconnecting from the BrickChanged signal, otherwise bricks cannot be freed from memory.

Referenced by Isis::CubeViewport::~CubeViewport().

◆ RemoveCube()

void Isis::CubeDataThread::RemoveCube ( int cubeId )

Removes a cube from this lock manager.

Parameters

cubeId The cube to be deleted's ID

References _FILEINFO_, and Isis::IException::Programmer.

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

/Users/astamile/ISIS3/isis/src/base/objs/CubeDataThread/CubeDataThread.h
/Users/astamile/ISIS3/isis/src/base/objs/CubeDataThread/CubeDataThread.cpp

Public Slots

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CubeDataThread()

◆ ~CubeDataThread()

Member Function Documentation

◆ AddChangeListener()

◆ AddCube() [1/2]

◆ AddCube() [2/2]

◆ BrickChanged

◆ BricksInMemory()

◆ DoneWithData

◆ FindCubeId()

◆ GetCube()

◆ GetUniversalGroundMap()

◆ ReadCube

◆ ReadReady

◆ ReadWriteCube

◆ ReadWriteReady

◆ RemoveChangeListener()

◆ RemoveCube()