A TileRequest either represents the input sub image that is needed by a PageRequest or if it is a root TileRequest, it represents the request by a user to get that tile. More...

#include <mlTileRequest.h>

Public Types
enum	AllocationPolicy { UseMemoryManager = 0, UseMLAlloc = 1, NoAllocation = 2, ExternalBuffer = 3 }
	Defines how the TileRequest will allocate its memory. More...
Public Member Functions
	TileRequest (PagedImage *inputImage, const SubImageBox &box, MLDataType dataType, const ScaleShiftData &scaleShift, bool readOnlyInputTile=false, bool tryToBecomeMemoryImage=false)
	Creates a TileRequest for `inputImage` with given `box`, `dataType` and `scaleShift`.
	~TileRequest ()
	Destructor.
Setup and dependency to PageRequest
bool	prepareForCursorVisit ()
	This is called before a cursor steps down into the TileRequest and may return false, which means that the Tile needs no visit but instead needs a sendTileRequestFinished() to proceed.
void	createInputPageIds ()
	Creates the pageids for all required input pages.
void	setNeededBy (PageRequest *request)
	Stores the PageRequest which needs this TileRequest.
bool	isBlockedByMemoryImg ()
	Checks whether the tile request is blocked by a pending memory image being calculated by another TileRequest.
void	pageRequestFinished (SubImage &pageImage, PageRequestQueueInterface &queue)
	Called by all finished PageRequests, which may be copied to output buffer.
Data handling
void	setAllocationPolicy (AllocationPolicy policy)
	Sets which allocation policy should be used.
AllocationPolicy	getAllocationPolicy () const
	Returns the allocation policy.
MLErrorCode	allocateData ()
	Allocates the data using the internal AllocationPolicy.
void	forgetData ()
	Tells the tile to forget its data so that it is not freed in freeData()
void	freeData ()
	Frees the allocated data using SubImage::free(), except if the AllocationPolicy is UserAllocation.
const SubImage &	getSubImage () const
	Returns the stored sub image (including the data pointer).
void	setExternalDataBuffer (void *data)
	This allows to set the data buffer from an external buffer.
void	setUseTileReadOnly (bool flag)
	This allows to make read-only use of input pages or memory image if box/datatype match and shift/scale are default.
Progress/Completion
bool	hasFinished () const
	Returns if the request has finished (If an error happened, this returns true as well).
void	setTileRequestFinishedCB (TileRequestFinishedCB cb, void data)
	Sets the tile request finished cb (NOTE: in the current implementation, the TileRequest may NOT be deleted from inside of the TileRequestFinishedCB!)
double	getProgress () const
	Returns the progress of this tile (TODO: not very detailed yet, only the ratio of copied/total pages).
Error handling
bool	hasError () const
	Returns if the request has an error (and the data is thus unusable/invalid).
void	setError (MLErrorCode error)
	Sets the error that happened.
MLErrorCode	getError () const
	Returns the error that happened (or ML_RESULT_OK).
void	propagateErrorUpwards (MLErrorCode error)
	Propagates an error upwards through the PageRequest it depends on.
bool	propagateCancellationDownIfRequestNotNeededAnymore ()
	Recursively walks up to all tree roots and checks wether they are cancelled.
void	collectPageRequestsWithErrors (std::set< PageRequest * > &result)
	Collects all page requests that have error()!=ML_RESULT_OK up to the roots of the tree.
Helper methods
MLErrorCode	updateImageProperties ()
	Updates the image properties of the complete graph stating at this tile request via the host.
Protected Member Functions
PageRequest *	createPageRequest (MLint pageId, PageRequestQueueInterface &queue)
	Creates a new page request (if neccessary, otherwise returns NULL) and queue it if it has not dependencies.
void	copyDataFromSubImg (SubImage &pageImage)
	Copies the data from the given image (if in read-only mode, the data might as well be stored instead of being copied).
void	sendTileRequestFinished (PageRequestQueueInterface &queue)
	Tells the dependend page requests that the tile request has finished.
Protected Attributes
SubImage	_subImage
	The sub image that represents the TileRequest's box,datatype and data.
AllocationPolicy	_allocationPolicy
	Defines which allocation method to use.
ScaleShiftData	_scaleShiftData
	The additional scale/shift information.
bool	_readOnlyInputTile
	Flag that the TileRequest should try to not copy data, since it will not be written to.
bool	_tileWillBecomeMemoryImage
	Flag that the TileRequest should become the MemoryImage when it has finished.
PagedImage *	_image
	The image from which the data should be requested.
MLint	_inputPagesNeeded
	Overall number of pages needed (which is getNumPages() of _inputPageIds at the beginning and will decrement to 0)
PageIDIterator	_inputPageIds
	Since a tile can have a lot of page requests, we use a PageIdIterator to generate the ids on the fly.
MLint	_traversalCursorPosition
	Current _inputPageIds position to indicate the next page request to create.
PageRequest *	_neededByPageRequest
	The PageRequest that depends on this TileRequest (or NULL if it is a root TileRequest).
MLErrorCode	_error
	The current error state.
TileRequestFinishedCB *	_finishedCB
	Callback to signal that the TileRequest has finished.
void *	_finishedCBData
	Callback data to signal that the TileRequest has finished.
Friends
class	PageRequestCursor
	The cursor needs to be our friend, since it has to access the internal traversal state.

Detailed Description

A TileRequest either represents the input sub image that is needed by a PageRequest or if it is a root TileRequest, it represents the request by a user to get that tile.

A TileRequest typically consists of a number of pages that need to be calculated. These pages are requested by the TileRequest using the PageRequests. Alternatively, a page can already be in the cache and just needs to be copied to the tile. Another option is to make use of a MemoryImage, which means that the whole tile can be filled from the MemoryImage without requesting any pages. A TileRequest can be read-only, in which case it tries not to copy the data but instead use the data of a page or MemoryImage directly. This is only possible in the special situation where a TileRequest's datatype and box exactly matches the input page or the MemoryImage.

Definition at line 44 of file mlTileRequest.h.

Member Enumeration Documentation

enum ml::TileRequest::AllocationPolicy

Defines how the TileRequest will allocate its memory.

Enumerator:

UseMemoryManager
UseMLAlloc
NoAllocation
ExternalBuffer

Definition at line 58 of file mlTileRequest.h.

Constructor & Destructor Documentation

ml::TileRequest::TileRequest	(	PagedImage *	inputImage,
		const SubImageBox &	box,
		MLDataType	dataType,
		const ScaleShiftData &	scaleShift,
		bool	readOnlyInputTile = `false`,
		bool	tryToBecomeMemoryImage = `false`
	)

Creates a TileRequest for inputImage with given box, dataType and scaleShift.

readOnlyInputTile can be used to specify that the TileRequest should try not to copy the data. tryToBecomeMemoryImage sets that this TileRequest should try to become the MemoryImage of inputImage when it has finished.

ml::TileRequest::~TileRequest ( )

Destructor.

Member Function Documentation

MLErrorCode ml::TileRequest::allocateData ( )

Allocates the data using the internal AllocationPolicy.

void ml::TileRequest::collectPageRequestsWithErrors ( std::set< PageRequest * > & result )

Collects all page requests that have error()!=ML_RESULT_OK up to the roots of the tree.

void ml::TileRequest::copyDataFromSubImg ( SubImage & pageImage ) [protected]

Copies the data from the given image (if in read-only mode, the data might as well be stored instead of being copied).

void ml::TileRequest::createInputPageIds ( )

Creates the pageids for all required input pages.

PageRequest* ml::TileRequest::createPageRequest	(	MLint	pageId,
		PageRequestQueueInterface &	queue
	)		`[protected]`

Creates a new page request (if neccessary, otherwise returns NULL) and queue it if it has not dependencies.

(a new page request is only returned if the page does not yet exist in the cache and if there is no pending page request registered yet. If the page does exist, it is copied to its tile requests directly. If a pending page request is available, this request is shared and NULL is returned.)

void ml::TileRequest::forgetData ( ) [inline]

Tells the tile to forget its data so that it is not freed in freeData()

Definition at line 113 of file mlTileRequest.h.

void ml::TileRequest::freeData ( ) [inline]

Frees the allocated data using SubImage::free(), except if the AllocationPolicy is UserAllocation.

Definition at line 116 of file mlTileRequest.h.

AllocationPolicy ml::TileRequest::getAllocationPolicy ( ) const [inline]

Returns the allocation policy.

Definition at line 107 of file mlTileRequest.h.

MLErrorCode ml::TileRequest::getError ( ) const [inline]

Returns the error that happened (or ML_RESULT_OK).

Definition at line 164 of file mlTileRequest.h.

double ml::TileRequest::getProgress ( ) const

Returns the progress of this tile (TODO: not very detailed yet, only the ratio of copied/total pages).

const SubImage& ml::TileRequest::getSubImage ( ) const [inline]

Returns the stored sub image (including the data pointer).

Definition at line 119 of file mlTileRequest.h.

bool ml::TileRequest::hasError ( ) const [inline]

Returns if the request has an error (and the data is thus unusable/invalid).

Definition at line 158 of file mlTileRequest.h.

References ML_RESULT_OK.

bool ml::TileRequest::hasFinished ( ) const

Returns if the request has finished (If an error happened, this returns true as well).

bool ml::TileRequest::isBlockedByMemoryImg ( )

Checks whether the tile request is blocked by a pending memory image being calculated by another TileRequest.

void ml::TileRequest::pageRequestFinished	(	SubImage &	pageImage,
		PageRequestQueueInterface &	queue
	)

Called by all finished PageRequests, which may be copied to output buffer.

This can lead to the completion of the TileRequest, which can lead to a new PageRequest being ready for processing, which will the be added to the queue.

bool ml::TileRequest::prepareForCursorVisit ( )

This is called before a cursor steps down into the TileRequest and may return false, which means that the Tile needs no visit but instead needs a sendTileRequestFinished() to proceed.

bool ml::TileRequest::propagateCancellationDownIfRequestNotNeededAnymore ( )

Recursively walks up to all tree roots and checks wether they are cancelled.

returns true if all encountered tree roots have been canceled and sets the error to ML_OPERATION_INTERRUPTED when true is returned.

void ml::TileRequest::propagateErrorUpwards ( MLErrorCode error )

Propagates an error upwards through the PageRequest it depends on.

void ml::TileRequest::sendTileRequestFinished ( PageRequestQueueInterface & queue ) [protected]

Tells the dependend page requests that the tile request has finished.

void ml::TileRequest::setAllocationPolicy ( AllocationPolicy policy ) [inline]

Sets which allocation policy should be used.

NOTE: This can only be changed directly after the constructor of the class, it has no affect when the data is already allocated. The default policy is to use the MLMemoryManager.

Definition at line 104 of file mlTileRequest.h.

void ml::TileRequest::setError ( MLErrorCode error )

Sets the error that happened.

void ml::TileRequest::setExternalDataBuffer ( void * data ) [inline]

This allows to set the data buffer from an external buffer.

The buffer will not be managed by the GetTileJob, the ownership stays with the user. This will switch the AllocationPolicy to TileRequest::ExternalBuffer.

Definition at line 123 of file mlTileRequest.h.

void ml::TileRequest::setNeededBy ( PageRequest * request ) [inline]

Stores the PageRequest which needs this TileRequest.

Except for the MemoryImage, a TileRequest can currently not be shared between different PageRequest, so it has only one dependend PageRequest.

Definition at line 81 of file mlTileRequest.h.