ModuleBackgroundTask extends the ImagingBackgroundTask with a number of useful methods that allow asynchronous access to the images of a Module. More...

#include <mlModuleBackgroundTask.h>

Inheritance diagram for ml::ModuleBackgroundTask:

Public Member Functions
	ModuleBackgroundTask (Module module, FloatField progressField=nullptr, StringField *statusField=nullptr)

	~ModuleBackgroundTask () override

void	setProgressField (FloatField *field)
	set the progress field (call from GUI thread only!)

void	setStatusField (StringField *field)
	set the status field (call from GUI thread only!)

bool	hasProgressField ()
	get the progress field (call from GUI thread only!)

bool	hasStatusField ()
	get the status field (call from GUI thread only!)

void	setStatusString (const std::string &status) override
	update the status string while processing (from run() method only)

void	setProgress (float progress) override
	update the progress while processing (from run() method only)

AsyncTileRequest	requestTile (int inputImageIndex, const SubImageBox &box, MLDataType type, const ScaleShiftData &shift=ScaleShiftData(), int getTileFlags=ImagingBackgroundTask::UseMemoryManager)
	Asynchronously request the tile (`flags` specifies an "or" combination of the BackgroundTask::TileRequestFlags enum)

AsyncTileRequest	requestTileWithExternalBuffer (int inputImageIndex, const SubImageBox &box, MLDataType type, const ScaleShiftData &shift, ManagedSubImage *externalBuffer, int getTileFlags=ImagingBackgroundTask::ExternalBuffer)
	Asynchronously request the tile (`flags` specifies an "or" combination of the BackgroundTask::TileRequestFlags enum) Note that the ownership of `externalBuffer` is passed to the method, so you are not allowed to delete it before you get it back via TileRequest::getTile().

ProcessAllPagesRequest	requestProcessAllPages (ProcessAllPagesHandler *handler, const SubImageBox &box=SubImageBox())
	Asynchronously request a processing of pages using the given handler.

ProcessAllPagesRequest	requestProcessAllPages (const SubImageBox &box=SubImageBox())
	Asynchronously request a processing of pages, running Module::processAllPages(-1).

virtual bool	shouldCancelOnInputImageChange (int) const
	Returns if the task should be canceled when the given input image has changed.

ImageVector	getInputImageExtent (int index=0) const
	get the extent of the input image at `index`

ImageVector	getInputImagePageExtent (int index=0) const
	get the page extent of the input image at `index`

MLDataType	getInputImageDataType (int index=0) const
	get the data type of the input image at `index`

double	getInputImageMinVoxelValue (int index=0) const
	get the min voxel value of the input image at `index`

double	getInputImageMaxVoxelValue (int index=0) const
	get the max voxel value of the input image at `index`

const MedicalImageProperties &	getInputImageProperties (int index=0) const
	get the image properties of the input image at `index`

bool	hasValidInputImage (int index=0) const
	returns if the input image at `index` is valid (and thus it's properties can be requested)

int	getNumInputImages () const
	get the number of input images

Public Member Functions inherited from ml::ImagingBackgroundTask
	ImagingBackgroundTask (void *owner)

	~ImagingBackgroundTask () override

Public Member Functions inherited from ml::MessagingBackgroundTask
	MessagingBackgroundTask (void *ownerArg)

template<typename Object , typename Method >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method)

template<typename Object , typename Method , typename Arg1 >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method, const Arg1 &arg1)

template<typename Object , typename Method , typename Arg1 , typename Arg2 >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method, const Arg1 &arg1, const Arg2 &arg2)

template<typename Object , typename Method , typename Arg1 , typename Arg2 , typename Arg3 >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method, const Arg1 &arg1, const Arg2 &arg2, const Arg3 &arg3)

template<typename Object , typename Method , typename Arg1 , typename Arg2 , typename Arg3 , typename Arg4 >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method, const Arg1 &arg1, const Arg2 &arg2, const Arg3 &arg3, const Arg4 &arg4)

template<typename Object , typename Method , typename Arg1 , typename Arg2 , typename Arg3 , typename Arg4 , typename Arg5 >
void	callMethodOnGUI (const DistantObject< Object > &target, Method method, const Arg1 &arg1, const Arg2 &arg2, const Arg3 &arg3, const Arg4 &arg4, const Arg5 &arg5)

Public Member Functions inherited from ml::BackgroundTask
	BackgroundTask (void *owner)
	Create a new task with given `owner` (the owner can be used to associate the task with a given class instance, e.g.

virtual	~BackgroundTask ()

virtual void	run ()=0
	run method that needs to be reimplemented (called from worker thread)

bool	isSynchronous () const
	check if task is synchronous (which means it is NOT run in an extra thread)

void	setSynchronous (bool flag)
	set if task is handled synchronous (call this ONLY on setup of the task, not while it is already running)

void	setSynchronousCancelField (NotifyField *field)
	set a cancel field that is used in synchronous mode to check if cancel was pressed

Status	status () const
	returns the status of the task (threadsafe)

void	cancel ()
	cancel the task (sets status to canceled) (threadsafe, typically called from GUI)

bool	isCanceled () const
	check if the task was canceled (threadsafe, typically called from GUI)

bool	shouldStop ()
	returns if the task should stop its work because it has been canceled.

void	resume ()
	resume task after it was suspended (will only do something if current status() is Suspended) (threadsafe)

void	suspend ()
	suspend task, so that it will wait until resume() is called (threadsafe).

std::string	statusString () const
	get current status string (threadsafe)

float	progress () const
	get current progress (threadsafe)

void	setOwnerWasDeleted ()
	tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task

bool	hasOwner () const
	check if owner was deleted (only call from GUI thread!)

void *	owner () const
	get the owner of the task (only call from GUI thread!)

void	waitAndExecuteNextMessage ()
	execute the next message (waits if no messages are available and processes the first message that is received) NOTE: only call from within run()

bool	executeNextMessage ()
	execute the next message (does not block if no message is available) It returns true if there was a message to process.

void	sendMessageToGUI (BackgroundTaskMessage *message)
	send the message to the GUI (ownership of message is passed to the method) and it sets the sender of the message to this BackgroundTask.

void	logMessage (const std::string &message)
	log a message (only logged if verbose logging is turned on) (threadsafe)

bool	isVerbose () const
	check if task uses verbose logging

void	setVerbose (bool flag)
	set if task uses verbose logging (call this ONLY on setup of the task, not while it is already running)

double	runningTime () const
	returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread)

double	idleTime () const
	returns the idle time (in seconds) of the task (which it e.g. waited for getTile to complete), (after it has finished or canceled, only call from GUI thread)

void	getStatusInformation (BackgroundTaskStatusInformation &info)
	get the complete status information (threadsafe)

MLuint32	taskId () const
	get the unique id of this task, the id of a task never changes

void	setTaskFinishedCB (BackgroundTaskFinishedCB callback, void userdata)
	set this directly after initialization of the task (from the GUI thread) this callback will be called whenever a task is either finished or canceled

void	addObserver (Observer *observer)
	add the given observer (threadsafe) (ownership stays with caller)

void	removeObserver (Observer *observer)
	remove the given observer (threadsafe) (ownership stays with caller)

Additional Inherited Members
Public Types inherited from ml::ImagingBackgroundTask
enum	TileRequestFlags { UseMemoryManager = TileRequest::UseMemoryManager , UseMLAlloc = TileRequest::UseMLAlloc , NoAllocation = TileRequest::NoAllocation , ExternalBuffer = TileRequest::ExternalBuffer , AllocationPolicyMask = 0xf , RequestReadOnlyPage = 16 , ReceiveProgressMessages = 32 }
	Defines flags that can be passed with requestTile(). NOTE: Only one of the allocation schemes can be used at a time. More...

Public Types inherited from ml::BackgroundTask
enum	Status { NotInTaskManager , Queued , Running , Finished , Canceled , Suspended }
	Defines current status of the task. More...

Protected Member Functions inherited from ml::ImagingBackgroundTask
BackgroundRequestId	generateBackgroundRequestId ()
	generate next generateBackgroundRequestId()

Protected Member Functions inherited from ml::BackgroundTask
void	sendStatusChangedToObservers ()
	send the status change to all observers

void	sendStatusStringChangedToObservers ()
	send the status string change to all observers

void	sendLogMessageToObservers (const std::string &msg)
	send the status string change to all observers

void	addIdleTime (double timeInSecs)
	add given `timeInSecs` as spent idle time

Detailed Description

ModuleBackgroundTask extends the ImagingBackgroundTask with a number of useful methods that allow asynchronous access to the images of a Module.

It allows passing a progressField and statusField so that setStatusString() and setProgress() will update the fields as well.

Definition at line 50 of file mlModuleBackgroundTask.h.

Constructor & Destructor Documentation

◆ ModuleBackgroundTask()

ml::ModuleBackgroundTask::ModuleBackgroundTask	(	Module *	module,
		FloatField *	progressField = nullptr,
		StringField *	statusField = nullptr )

◆ ~ModuleBackgroundTask()

ml::ModuleBackgroundTask::~ModuleBackgroundTask ( )

override

Member Function Documentation

◆ getInputImageDataType()

MLDataType ml::ModuleBackgroundTask::getInputImageDataType ( int index = 0 ) const

get the data type of the input image at index

◆ getInputImageExtent()

ImageVector ml::ModuleBackgroundTask::getInputImageExtent ( int index = 0 ) const

get the extent of the input image at index

◆ getInputImageMaxVoxelValue()

double ml::ModuleBackgroundTask::getInputImageMaxVoxelValue ( int index = 0 ) const

get the max voxel value of the input image at index

◆ getInputImageMinVoxelValue()

double ml::ModuleBackgroundTask::getInputImageMinVoxelValue ( int index = 0 ) const

get the min voxel value of the input image at index

◆ getInputImagePageExtent()

ImageVector ml::ModuleBackgroundTask::getInputImagePageExtent ( int index = 0 ) const

get the page extent of the input image at index

◆ getInputImageProperties()

const MedicalImageProperties & ml::ModuleBackgroundTask::getInputImageProperties ( int index = 0 ) const

get the image properties of the input image at index

Most members are available directly via getInputImage*, but for e.g. the voxel size or the world matrix, access to the MedicalImageProperties is useful.

◆ getNumInputImages()

int ml::ModuleBackgroundTask::getNumInputImages ( ) const

inline

get the number of input images

Definition at line 149 of file mlModuleBackgroundTask.h.

◆ hasProgressField()

bool ml::ModuleBackgroundTask::hasProgressField ( )

inline

get the progress field (call from GUI thread only!)

Definition at line 64 of file mlModuleBackgroundTask.h.

◆ hasStatusField()

bool ml::ModuleBackgroundTask::hasStatusField ( )

inline

get the status field (call from GUI thread only!)

Definition at line 67 of file mlModuleBackgroundTask.h.

◆ hasValidInputImage()

bool ml::ModuleBackgroundTask::hasValidInputImage ( int index = 0 ) const

returns if the input image at index is valid (and thus it's properties can be requested)

◆ requestProcessAllPages() [1/2]

ProcessAllPagesRequest ml::ModuleBackgroundTask::requestProcessAllPages ( const SubImageBox & box = SubImageBox() )

Asynchronously request a processing of pages, running Module::processAllPages(-1).

NOTE: It is preferable to use the version above using a ProcessAllPagesHandler, since this avoids side effects with the Module! We strongly encourage you to use a ProcessAllPagesHandler instead, since it will be much clearer what happens and it will not interfere with a processAllPages(-1) call that the Module might issue while the background task is running.

◆ requestProcessAllPages() [2/2]

ProcessAllPagesRequest ml::ModuleBackgroundTask::requestProcessAllPages	(	ProcessAllPagesHandler *	handler,
		const SubImageBox &	box = SubImageBox() )

Asynchronously request a processing of pages using the given handler.

NOTE: The ownership of the handler is passed to the method, so it MAY NOT be accessed or deleted until ProcessAllPagesRequest::waitUntilFinished() returns true.

A common use of this method is the following:

MyProcessAllPagesHandler* handler = new MyProcessAllPagesHandler;
 
// setup the handler
//handler->setSomeParameters();
 
bool result = requestProcessAllPages(handler).waitUntilFinished();
if (result) {
  // get result values of handler
  // handler->getSomeResult();
 
  // only delete handler if we received result==true
  delete handler;
}

◆ requestTile()

AsyncTileRequest ml::ModuleBackgroundTask::requestTile	(	int	inputImageIndex,
		const SubImageBox &	box,
		MLDataType	type,
		const ScaleShiftData &	shift = ScaleShiftData(),
		int	getTileFlags = ImagingBackgroundTask::UseMemoryManager )

Asynchronously request the tile (flags specifies an "or" combination of the BackgroundTask::TileRequestFlags enum)

◆ requestTileWithExternalBuffer()

AsyncTileRequest ml::ModuleBackgroundTask::requestTileWithExternalBuffer	(	int	inputImageIndex,
		const SubImageBox &	box,
		MLDataType	type,
		const ScaleShiftData &	shift,
		ManagedSubImage *	externalBuffer,
		int	getTileFlags = ImagingBackgroundTask::ExternalBuffer )

Asynchronously request the tile (flags specifies an "or" combination of the BackgroundTask::TileRequestFlags enum) Note that the ownership of externalBuffer is passed to the method, so you are not allowed to delete it before you get it back via TileRequest::getTile().

If getTile() returns NULL, the externalBuffer is already deleted internally. To support own destruction of the memory, you may derive from ManagedSubImage and reimplement the destructor.

◆ setProgress()

void ml::ModuleBackgroundTask::setProgress ( float progress )

overridevirtual

update the progress while processing (from run() method only)

Reimplemented from ml::BackgroundTask.

◆ setProgressField()

void ml::ModuleBackgroundTask::setProgressField ( FloatField * field )

inline

set the progress field (call from GUI thread only!)

Definition at line 58 of file mlModuleBackgroundTask.h.

References mlrange_cast().

◆ setStatusField()

void ml::ModuleBackgroundTask::setStatusField ( StringField * field )

inline

set the status field (call from GUI thread only!)

Definition at line 61 of file mlModuleBackgroundTask.h.

References mlrange_cast().

◆ setStatusString()

void ml::ModuleBackgroundTask::setStatusString ( const std::string & status )

overridevirtual

update the status string while processing (from run() method only)

Reimplemented from ml::BackgroundTask.

◆ shouldCancelOnInputImageChange()

virtual bool ml::ModuleBackgroundTask::shouldCancelOnInputImageChange ( int ) const

inlinevirtual

Returns if the task should be canceled when the given input image has changed.

The default implementation returns true, so that any input image change will cancel the task (NOTE: this flag needs to be used from handleNotification(), this is typically be done in BackgroundTaskBaseModule). If your reimplement this method, make sure that it can safely be called from the GUI thread.

Definition at line 121 of file mlModuleBackgroundTask.h.

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

MeVis/Foundation/Sources/MLBackgroundTasks/mlModuleBackgroundTask.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ModuleBackgroundTask()

◆ ~ModuleBackgroundTask()

Member Function Documentation

◆ getInputImageDataType()

◆ getInputImageExtent()

◆ getInputImageMaxVoxelValue()

◆ getInputImageMinVoxelValue()

◆ getInputImagePageExtent()

◆ getInputImageProperties()

◆ getNumInputImages()

◆ hasProgressField()

◆ hasStatusField()

◆ hasValidInputImage()

◆ requestProcessAllPages() [1/2]

◆ requestProcessAllPages() [2/2]

◆ requestTile()

◆ requestTileWithExternalBuffer()

◆ setProgress()

◆ setProgressField()

◆ setStatusField()

◆ setStatusString()

◆ shouldCancelOnInputImageChange()