MeVisLabToolboxReference
ml::ModuleBackgroundTask Class Reference

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:
ml::ImagingBackgroundTask ml::MessagingBackgroundTask ml::BackgroundTask ml::ProcessAllPagesBackgroundTask ml::RTObjectSaveBackgroundTask

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!) More...
 
void setStatusField (StringField *field)
 set the status field (call from GUI thread only!) More...
 
bool hasProgressField ()
 get the progress field (call from GUI thread only!) More...
 
bool hasStatusField ()
 get the status field (call from GUI thread only!) More...
 
void setStatusString (const std::string &status) override
 update the status string while processing (from run() method only) More...
 
void setProgress (float progress) override
 update the progress while processing (from run() method only) More...
 
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) More...
 
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(). More...
 
ProcessAllPagesRequest requestProcessAllPages (ProcessAllPagesHandler *handler, const SubImageBox &box=SubImageBox())
 Asynchronously request a processing of pages using the given handler. More...
 
ProcessAllPagesRequest requestProcessAllPages (const SubImageBox &box=SubImageBox())
 Asynchronously request a processing of pages, running Module::processAllPages(-1). More...
 
virtual bool shouldCancelOnInputImageChange (int) const
 Returns if the task should be canceled when the given input image has changed. More...
 
ImageVector getInputImageExtent (int index=0) const
 get the extent of the input image at index More...
 
ImageVector getInputImagePageExtent (int index=0) const
 get the page extent of the input image at index More...
 
MLDataType getInputImageDataType (int index=0) const
 get the data type of the input image at index More...
 
double getInputImageMinVoxelValue (int index=0) const
 get the min voxel value of the input image at index More...
 
double getInputImageMaxVoxelValue (int index=0) const
 get the max voxel value of the input image at index More...
 
const MedicalImagePropertiesgetInputImageProperties (int index=0) const
 get the image properties of the input image at index More...
 
bool hasValidInputImage (int index=0) const
 returns if the input image at index is valid (and thus it's properties can be requested) More...
 
int getNumInputImages () const
 get the number of input images More...
 
- 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. More...
 
virtual ~BackgroundTask ()
 
virtual void run ()=0
 run method that needs to be reimplemented (called from worker thread) More...
 
bool isSynchronous () const
 check if task is synchronous (which means it is NOT run in an extra thread) More...
 
void setSynchronous (bool flag)
 set if task is handled synchronous (call this ONLY on setup of the task, not while it is already running) More...
 
void setSynchronousCancelField (NotifyField *field)
 set a cancel field that is used in synchronous mode to check if cancel was pressed More...
 
Status status () const
 returns the status of the task (threadsafe) More...
 
void cancel ()
 cancel the task (sets status to canceled) (threadsafe, typically called from GUI) More...
 
bool isCanceled () const
 check if the task was canceled (threadsafe, typically called from GUI) More...
 
bool shouldStop ()
 returns if the task should stop its work because it has been canceled. More...
 
void resume ()
 resume task after it was suspended (will only do something if current status() is Suspended) (threadsafe) More...
 
void suspend ()
 suspend task, so that it will wait until resume() is called (threadsafe). More...
 
std::string statusString () const
 get current status string (threadsafe) More...
 
float progress () const
 get current progress (threadsafe) More...
 
void setOwnerWasDeleted ()
 tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task More...
 
bool hasOwner () const
 check if owner was deleted (only call from GUI thread!) More...
 
void * owner () const
 get the owner of the task (only call from GUI thread!) More...
 
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() More...
 
bool executeNextMessage ()
 execute the next message (does not block if no message is available) It returns true if there was a message to process. More...
 
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. More...
 
void logMessage (const std::string &message)
 log a message (only logged if verbose logging is turned on) (threadsafe) More...
 
bool isVerbose () const
 check if task uses verbose logging More...
 
void setVerbose (bool flag)
 set if task uses verbose logging (call this ONLY on setup of the task, not while it is already running) More...
 
double runningTime () const
 returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread) More...
 
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) More...
 
void getStatusInformation (BackgroundTaskStatusInformation &info)
 get the complete status information (threadsafe) More...
 
MLuint32 taskId () const
 get the unique id of this task, the id of a task never changes More...
 
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 More...
 
void addObserver (Observer *observer)
 add the given observer (threadsafe) (ownership stays with caller) More...
 
void removeObserver (Observer *observer)
 remove the given observer (threadsafe) (ownership stays with caller) More...
 

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() More...
 
- Protected Member Functions inherited from ml::BackgroundTask
void sendStatusChangedToObservers ()
 send the status change to all observers More...
 
void sendStatusStringChangedToObservers ()
 send the status string change to all observers More...
 
void sendLogMessageToObservers (const std::string &msg)
 send the status string change to all observers More...
 
void addIdleTime (double timeInSecs)
 add given timeInSecs as spent idle time More...
 

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

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

Member Function Documentation

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

get the data type of the input image at index

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

get the extent of the input image at index

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

get the max voxel value of the input image at index

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

get the min voxel value of the input image at index

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

get the page extent of the input image at index

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.

int ml::ModuleBackgroundTask::getNumInputImages ( ) const
inline

get the number of input images

Definition at line 149 of file mlModuleBackgroundTask.h.

bool ml::ModuleBackgroundTask::hasProgressField ( )
inline

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

Definition at line 64 of file mlModuleBackgroundTask.h.

bool ml::ModuleBackgroundTask::hasStatusField ( )
inline

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

Definition at line 67 of file mlModuleBackgroundTask.h.

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)

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;
}
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.

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)

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.

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

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

Reimplemented from ml::BackgroundTask.

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

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

Definition at line 58 of file mlModuleBackgroundTask.h.

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

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

Definition at line 61 of file mlModuleBackgroundTask.h.

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

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

Reimplemented from ml::BackgroundTask.

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: