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
void	init (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`.

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	isBlockedByMemoryImage ()
	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.

void	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!)

void	setInternalTileRequestFinishedCB (TileRequestFinishedCB cb, void data)
	Sets the internal tile request finished cb (NOTE: this should only be used by the request processor)

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.

int	getProcessingScope () const
	Get the assigned processing scope.

void	setProcessingScope (int scope)
	Get the assigned processing scope.

const SubImageBox &	getBox () const
	Get the box that this tile request covers.

bool	intersectsPagedImage () const
	Returns if the request has an intersection with the paged image.

void	updateSourceImageExtent ()
	Update the source image extent according to the image.

Static Public Member Functions
static TileRequest *	allocate ()
	Tile requests are allocated via the allocate method, they can not be created with new.

static void	deallocate (TileRequest *request)
	Tile requests are deallocated with the deallocate method, they can not be deleted directly.

static void	clearFreeList ()
	Clear the internal free list of deallocated TileRequests.

static void	enableAllocationFailure (int count=1)
	Enables failing on every `count` allocation.

static void	disableAllocationFailure ()
	Disables allocation failure (default!)

Protected Member Functions
PageRequest *	createPageRequest (MLint pageId, PageRequestQueueInterface &queue)
	Creates a new page request (if necessary, otherwise returns NULL) and queue it if it has not dependencies.

bool	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.

void	emitFinishedCallback ()
	Calls the finished callbacks.

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)

Mutex	_inputPagesNeededMutex
	TODO: replace above with atomic counter and remove the mutex.

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.

int	_processingScope
	the processing scope

TileRequestFinishedCB *	_finishedCB
	Callback to signal that the TileRequest has finished.

void *	_finishedCBData
	Callback data to signal that the TileRequest has finished.

TileRequestFinishedCB *	_internalFinishedCB
	Callback to signal that the TileRequest has finished.

void *	_internalFinishedCBData
	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 49 of file mlTileRequest.h.

Member Enumeration Documentation

◆ AllocationPolicy

enum ml::TileRequest::AllocationPolicy

Defines how the TileRequest will allocate its memory.

Enumerator
UseMemoryManager
UseMLAlloc
NoAllocation
ExternalBuffer

Definition at line 86 of file mlTileRequest.h.

Member Function Documentation

◆ allocate()

static TileRequest * ml::TileRequest::allocate ( )

static

Tile requests are allocated via the allocate method, they can not be created with new.

◆ allocateData()

void ml::TileRequest::allocateData ( )

Allocates the data using the internal AllocationPolicy.

◆ clearFreeList()

static void ml::TileRequest::clearFreeList ( )

static

Clear the internal free list of deallocated TileRequests.

◆ collectPageRequestsWithErrors()

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.

◆ copyDataFromSubImg()

bool 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).

Returns true if the data was not copied but shared instead.

◆ createInputPageIds()

void ml::TileRequest::createInputPageIds ( )

Creates the pageids for all required input pages.

◆ createPageRequest()

PageRequest * ml::TileRequest::createPageRequest	(	MLint	pageId,
		PageRequestQueueInterface &	queue )

protected

Creates a new page request (if necessary, 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. A PageRequest is only returned if it first needs cursor work, this method never returns a PageRequest that was added to the queue.)

◆ deallocate()

static void ml::TileRequest::deallocate ( TileRequest * request )

static

Tile requests are deallocated with the deallocate method, they can not be deleted directly.

◆ disableAllocationFailure()

static void ml::TileRequest::disableAllocationFailure ( )

inlinestatic

Disables allocation failure (default!)

Definition at line 314 of file mlTileRequest.h.

◆ emitFinishedCallback()

void ml::TileRequest::emitFinishedCallback ( )

protected

Calls the finished callbacks.

◆ enableAllocationFailure()

static void ml::TileRequest::enableAllocationFailure ( int count = 1 )

static

Enables failing on every count allocation.

◆ forgetData()

void ml::TileRequest::forgetData ( )

inline

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

Definition at line 141 of file mlTileRequest.h.

◆ freeData()

void ml::TileRequest::freeData ( )

inline

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

Definition at line 144 of file mlTileRequest.h.

◆ getAllocationPolicy()

AllocationPolicy ml::TileRequest::getAllocationPolicy ( ) const

inline

Returns the allocation policy.

Definition at line 135 of file mlTileRequest.h.

◆ getBox()

const SubImageBox & ml::TileRequest::getBox ( ) const

inline

Get the box that this tile request covers.

Definition at line 229 of file mlTileRequest.h.

◆ getError()

MLErrorCode ml::TileRequest::getError ( ) const

inline

Returns the error that happened (or ML_RESULT_OK).

Definition at line 198 of file mlTileRequest.h.

◆ getProcessingScope()

int ml::TileRequest::getProcessingScope ( ) const

inline

Get the assigned processing scope.

Definition at line 223 of file mlTileRequest.h.

◆ getProgress()

double ml::TileRequest::getProgress ( ) const

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

◆ getSubImage()

const SubImage & ml::TileRequest::getSubImage ( ) const

inline

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

Definition at line 147 of file mlTileRequest.h.

◆ hasError()

bool ml::TileRequest::hasError ( ) const

inline

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

Definition at line 192 of file mlTileRequest.h.

References ML_RESULT_OK.

◆ hasFinished()

bool ml::TileRequest::hasFinished ( ) const

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

◆ init()

void ml::TileRequest::init	(	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.

◆ intersectsPagedImage()

bool ml::TileRequest::intersectsPagedImage ( ) const

Returns if the request has an intersection with the paged image.

◆ isBlockedByMemoryImage()

bool ml::TileRequest::isBlockedByMemoryImage ( )

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

◆ pageRequestFinished()

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.

◆ prepareForCursorVisit()

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.

◆ propagateCancellationDownIfRequestNotNeededAnymore()

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.

◆ propagateErrorUpwards()

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

Propagates an error upwards through the PageRequest it depends on.

It first calls setError(), then emits the finished callbacks and then propates the error upwards.

◆ sendTileRequestFinished()

void ml::TileRequest::sendTileRequestFinished ( PageRequestQueueInterface & queue )

protected

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

◆ setAllocationPolicy()

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 132 of file mlTileRequest.h.

◆ setError()

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

Sets the error that happened.

◆ setExternalDataBuffer()

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 151 of file mlTileRequest.h.

◆ setInternalTileRequestFinishedCB()

void ml::TileRequest::setInternalTileRequestFinishedCB	(	TileRequestFinishedCB *	cb,
		void *	data )

inline

Sets the internal tile request finished cb (NOTE: this should only be used by the request processor)

Definition at line 176 of file mlTileRequest.h.

◆ setNeededBy()

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 109 of file mlTileRequest.h.

References mlrange_cast().

◆ setProcessingScope()

void ml::TileRequest::setProcessingScope ( int scope )

inline

Get the assigned processing scope.

Definition at line 226 of file mlTileRequest.h.

References mlrange_cast().

◆ setTileRequestFinishedCB()

void ml::TileRequest::setTileRequestFinishedCB	(	TileRequestFinishedCB *	cb,
		void *	data )

inline

Sets the tile request finished cb (NOTE: in the current implementation, the TileRequest may NOT be deleted from inside of the TileRequestFinishedCB!)

Definition at line 170 of file mlTileRequest.h.

◆ setUseTileReadOnly()

void ml::TileRequest::setUseTileReadOnly ( bool flag )

inline

This allows to make read-only use of input pages or memory image if box/datatype match and shift/scale are default.

Definition at line 157 of file mlTileRequest.h.

References mlrange_cast().

◆ updateImageProperties()

MLErrorCode ml::TileRequest::updateImageProperties ( )

Updates the image properties of the complete graph stating at this tile request via the host.

◆ updateSourceImageExtent()

void ml::TileRequest::updateSourceImageExtent ( )

Update the source image extent according to the image.

Friends And Related Symbol Documentation

◆ PageRequestCursor

friend class PageRequestCursor

friend

The cursor needs to be our friend, since it has to access the internal traversal state.

Definition at line 241 of file mlTileRequest.h.

Member Data Documentation

◆ _allocationPolicy

AllocationPolicy ml::TileRequest::_allocationPolicy

protected

Defines which allocation method to use.

Definition at line 265 of file mlTileRequest.h.

◆ _error

MLErrorCode ml::TileRequest::_error

protected

The current error state.

Definition at line 295 of file mlTileRequest.h.

◆ _finishedCB

TileRequestFinishedCB* ml::TileRequest::_finishedCB

protected

Callback to signal that the TileRequest has finished.

Definition at line 301 of file mlTileRequest.h.

◆ _finishedCBData

void* ml::TileRequest::_finishedCBData

protected

Callback data to signal that the TileRequest has finished.

Definition at line 303 of file mlTileRequest.h.

◆ _image

PagedImage* ml::TileRequest::_image

protected

The image from which the data should be requested.

Definition at line 276 of file mlTileRequest.h.

◆ _inputPageIds

PageIDIterator ml::TileRequest::_inputPageIds

protected

Since a tile can have a lot of page requests, we use a PageIdIterator to generate the ids on the fly.

Definition at line 286 of file mlTileRequest.h.

◆ _inputPagesNeeded

MLint ml::TileRequest::_inputPagesNeeded

protected

Overall number of pages needed (which is getNumPages() of _inputPageIds at the beginning and will decrement to 0)

Definition at line 279 of file mlTileRequest.h.

◆ _inputPagesNeededMutex

Mutex ml::TileRequest::_inputPagesNeededMutex

protected

TODO: replace above with atomic counter and remove the mutex.

Definition at line 282 of file mlTileRequest.h.

◆ _internalFinishedCB

TileRequestFinishedCB* ml::TileRequest::_internalFinishedCB

protected

Callback to signal that the TileRequest has finished.

Definition at line 306 of file mlTileRequest.h.

◆ _internalFinishedCBData

void* ml::TileRequest::_internalFinishedCBData

protected

Callback data to signal that the TileRequest has finished.

Definition at line 308 of file mlTileRequest.h.

◆ _neededByPageRequest

PageRequest* ml::TileRequest::_neededByPageRequest

protected

The PageRequest that depends on this TileRequest (or NULL if it is a root TileRequest).

Definition at line 292 of file mlTileRequest.h.

◆ _processingScope

int ml::TileRequest::_processingScope

protected

the processing scope

Definition at line 298 of file mlTileRequest.h.

◆ _readOnlyInputTile

bool ml::TileRequest::_readOnlyInputTile

protected

Flag that the TileRequest should try to not copy data, since it will not be written to.

Definition at line 271 of file mlTileRequest.h.

◆ _scaleShiftData

ScaleShiftData ml::TileRequest::_scaleShiftData

protected

The additional scale/shift information.

Definition at line 268 of file mlTileRequest.h.

◆ _subImage

SubImage ml::TileRequest::_subImage

protected

The sub image that represents the TileRequest's box,datatype and data.

Definition at line 262 of file mlTileRequest.h.

◆ _tileWillBecomeMemoryImage

bool ml::TileRequest::_tileWillBecomeMemoryImage

protected

Flag that the TileRequest should become the MemoryImage when it has finished.

Definition at line 273 of file mlTileRequest.h.

◆ _traversalCursorPosition

MLint ml::TileRequest::_traversalCursorPosition

protected

Current _inputPageIds position to indicate the next page request to create.

Definition at line 289 of file mlTileRequest.h.

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

MeVis/Foundation/Sources/ML/include/host/mlTileRequest.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ AllocationPolicy

Member Function Documentation

◆ allocate()

◆ allocateData()

◆ clearFreeList()

◆ collectPageRequestsWithErrors()

◆ copyDataFromSubImg()

◆ createInputPageIds()

◆ createPageRequest()

◆ deallocate()

◆ disableAllocationFailure()

◆ emitFinishedCallback()

◆ enableAllocationFailure()

◆ forgetData()

◆ freeData()

◆ getAllocationPolicy()

◆ getBox()

◆ getError()

◆ getProcessingScope()

◆ getProgress()

◆ getSubImage()

◆ hasError()

◆ hasFinished()

◆ init()

◆ intersectsPagedImage()

◆ isBlockedByMemoryImage()

◆ pageRequestFinished()

◆ prepareForCursorVisit()

◆ propagateCancellationDownIfRequestNotNeededAnymore()

◆ propagateErrorUpwards()

◆ sendTileRequestFinished()

◆ setAllocationPolicy()

◆ setError()

◆ setExternalDataBuffer()

◆ setInternalTileRequestFinishedCB()

◆ setNeededBy()

◆ setProcessingScope()

◆ setTileRequestFinishedCB()

◆ setUseTileReadOnly()

◆ updateImageProperties()

◆ updateSourceImageExtent()

Friends And Related Symbol Documentation

◆ PageRequestCursor

Member Data Documentation

◆ _allocationPolicy

◆ _error

◆ _finishedCB

◆ _finishedCBData

◆ _image

◆ _inputPageIds

◆ _inputPagesNeeded

◆ _inputPagesNeededMutex

◆ _internalFinishedCB

◆ _internalFinishedCBData

◆ _neededByPageRequest

◆ _processingScope

◆ _readOnlyInputTile

◆ _scaleShiftData

◆ _subImage

◆ _tileWillBecomeMemoryImage

◆ _traversalCursorPosition