Base class for a task that is started in an extra thread. More...

#include <mlBackgroundTask.h>

Inheritance diagram for ml::BackgroundTask:

Classes
class	Observer
	Abstract interface to observe the BackgroundTask. More...

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

Public Member Functions
	BackgroundTask (void *owner)
	Creates a new task with given `owner`. More...

virtual	~BackgroundTask ()

Methods to reimplement
virtual void	run ()=0
	Method that needs to be reimplemented. This is called from the worker thread. More...

Setup of task properties
bool	isSynchronous () const
	Checks whether the task is synchronous, which means it is not executed in a different thread. More...

void	setSynchronous (bool flag)
	Sets whether the task is handled synchronously. Call this only in the setup of the task, not while it is already running. More...

void	setSynchronousCancelField (NotifyField *field)
	Sets a cancel field that is used in synchronous mode to check whether cancel was pressed. More...

Status handling / canceling
Status	status () const
	Returns the status of the task. More...

void	cancel ()
	Cancels the task (i.e., it sets status to canceled). More...

bool	isCanceled () const
	Checks whether the task was canceled. More...

bool	shouldStop ()
	Returns whether the task should stop its work because it has been canceled. More...

void	resume ()
	Resumes the task after it was suspended. More...

void	suspend ()
	Suspends the task. More...

std::string	statusString () const
	Returns current status string. More...

virtual void	setStatusString (const std::string &status)
	Updates the status string while processing. More...

float	progress () const
	Returns current progress This is thread-safe. More...

virtual void	setProgress (float progress)
	Updates the progress while processing. More...

Owner related methods
void	setOwnerWasDeleted ()
	Tells the task that its owner was deleted and cancels the thread. More...

bool	hasOwner () const
	Returns whether the owner was deleted. More...

void *	owner () const
	Returns the owner of the task Call this from GUI thread only! More...

Message handling
void	waitAndExecuteNextMessage ()
	Executes the next message. More...

bool	executeNextMessage ()
	Executes the next message. More...

void	sendMessageToGUI (BackgroundTaskMessage *message)
	Sends the message to the GUI. More...

Logging
void	logMessage (const std::string &message)
	Logs a message. More...

bool	isVerbose () const
	Checks whether task uses verbose logging. More...

void	setVerbose (bool flag)
	Sets whether task uses verbose logging. More...

Misc
double	runningTime () const
	Returns the running time in seconds of the task. More...

double	idleTime () const
	Returns the idle time in seconds of the task (e.g., the time it waited for getTile to complete). More...

void	getStatusInformation (BackgroundTaskStatusInformation &info)
	Returns the complete status information. More...

MLuint32	taskId () const
	Returns the unique id of this task. The id of a task never changes. More...

Observing a task
void	setTaskFinishedCB (BackgroundTaskFinishedCB callback, void userdata)
	Set this directly after the initialization of the task from the GUI thread. More...

void	addObserver (Observer *observer)
	Adds the given observer. More...

void	removeObserver (Observer *observer)
	Removes the given observer. More...

Protected Member Functions
void	sendStatusChangedToObservers ()
	Sends the status change to all observers. More...

void	sendStatusStringChangedToObservers ()
	Sends the status string change to all observers. More...

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

void	addIdleTime (double timeInSecs)
	Adds given `timeInSecs` as spent idle time. More...

Friends
class	BackgroundTaskManager

struct	BackgroundTaskManagerWorkerFunc

Detailed Description

Base class for a task that is started in an extra thread.

Reimplement the virtual run() method to implement processing that is done in the task. A task can be scheduled using BackgroundTaskManager::self()->runTask(task).

Definition at line 41 of file mlBackgroundTask.h.

Member Enumeration Documentation

◆ Status

enum ml::BackgroundTask::Status

Defines current status of the task.

Enumerator
NotInTaskManager
Queued
Running
Finished
Canceled
Suspended

Definition at line 47 of file mlBackgroundTask.h.

Constructor & Destructor Documentation

◆ BackgroundTask()

ml::BackgroundTask::BackgroundTask ( void * owner )

Creates a new task with given owner.

The owner can be used to associate the task with a given class instance, e.g., an ml::Module. The task never accesses the owner itself.

◆ ~BackgroundTask()

virtual ml::BackgroundTask::~BackgroundTask ( )

virtual

Member Function Documentation

◆ addIdleTime()

void ml::BackgroundTask::addIdleTime ( double timeInSecs )

inlineprotected

Adds given timeInSecs as spent idle time.

Definition at line 271 of file mlBackgroundTask.h.

◆ addObserver()

void ml::BackgroundTask::addObserver ( Observer * observer )

Adds the given observer.

This is thread-safe and the ownership stays with caller.

◆ cancel()

void ml::BackgroundTask::cancel ( )

Cancels the task (i.e., it sets status to canceled).

This is thread-safe and typically called from the GUI.

◆ executeNextMessage()

bool ml::BackgroundTask::executeNextMessage ( )

Executes the next message.

It does not block if no message is available. It returns true if there was a message to process. Note: only call this from within run().

◆ getStatusInformation()

void ml::BackgroundTask::getStatusInformation ( BackgroundTaskStatusInformation & info )

Returns the complete status information.

This is thread-safe.

◆ hasOwner()

bool ml::BackgroundTask::hasOwner ( ) const

Returns whether the owner was deleted.

Call this from GUI thread only!

◆ idleTime()

double ml::BackgroundTask::idleTime ( ) const

inline

Returns the idle time in seconds of the task (e.g., the time it waited for getTile to complete).

After it has finished or been canceled, only call this from the GUI thread.

Definition at line 210 of file mlBackgroundTask.h.

◆ isCanceled()

bool ml::BackgroundTask::isCanceled ( ) const

Checks whether the task was canceled.

This is thread-safe and typically called from the GUI.

◆ isSynchronous()

bool ml::BackgroundTask::isSynchronous ( ) const

inline

Checks whether the task is synchronous, which means it is not executed in a different thread.

Definition at line 77 of file mlBackgroundTask.h.

◆ isVerbose()

bool ml::BackgroundTask::isVerbose ( ) const

inline

Checks whether task uses verbose logging.

Definition at line 191 of file mlBackgroundTask.h.

◆ logMessage()

void ml::BackgroundTask::logMessage ( const std::string & message )

Logs a message.

It is only logged if verbose logging is turned on. This is thread-safe.

◆ owner()

void* ml::BackgroundTask::owner ( ) const

Returns the owner of the task Call this from GUI thread only!

◆ progress()

float ml::BackgroundTask::progress ( ) const

Returns current progress This is thread-safe.

◆ removeObserver()

void ml::BackgroundTask::removeObserver ( Observer * observer )

Removes the given observer.

This is thread-safe and the ownership stays with caller.

◆ resume()

void ml::BackgroundTask::resume ( )

Resumes the task after it was suspended.

It will only do something if the current status() returns 'Suspended'. This is thread-safe.

◆ run()

virtual void ml::BackgroundTask::run ( )

pure virtual

Method that needs to be reimplemented. This is called from the worker thread.

Implemented in ml::ProcessAllPagesBackgroundTask.

◆ runningTime()

double ml::BackgroundTask::runningTime ( ) const

inline

Returns the running time in seconds of the task.

After it has finished or been canceled, only call this from the GUI thread.

Definition at line 206 of file mlBackgroundTask.h.

◆ sendLogMessageToObservers()

void ml::BackgroundTask::sendLogMessageToObservers ( const std::string & msg )

protected

Sends the status string change to all observers.

◆ sendMessageToGUI()

void ml::BackgroundTask::sendMessageToGUI ( BackgroundTaskMessage * message )

Sends the message to the GUI.

The ownership of the message is passed to the method. It sets the sender of the message to this BackgroundTask. Note: only call this from within run().

Referenced by ml::MessagingBackgroundTask::callMethodOnGUI().

◆ sendStatusChangedToObservers()

void ml::BackgroundTask::sendStatusChangedToObservers ( )

protected

Sends the status change to all observers.

◆ sendStatusStringChangedToObservers()

void ml::BackgroundTask::sendStatusStringChangedToObservers ( )

protected

Sends the status string change to all observers.

◆ setOwnerWasDeleted()

void ml::BackgroundTask::setOwnerWasDeleted ( )

Tells the task that its owner was deleted and cancels the thread.

Call this from GUI thread only!

◆ setProgress()

virtual void ml::BackgroundTask::setProgress ( float progress )

virtual

Updates the progress while processing.

Call this from run() method only.

Reimplemented in ml::ModuleBackgroundTask.

◆ setStatusString()

virtual void ml::BackgroundTask::setStatusString ( const std::string & status )

virtual

Updates the status string while processing.

Call this from the run() method only.

Reimplemented in ml::ModuleBackgroundTask.

◆ setSynchronous()

void ml::BackgroundTask::setSynchronous ( bool flag )

inline

Sets whether the task is handled synchronously. Call this only in the setup of the task, not while it is already running.

Definition at line 79 of file mlBackgroundTask.h.

◆ setSynchronousCancelField()

void ml::BackgroundTask::setSynchronousCancelField ( NotifyField * field )

inline

Sets a cancel field that is used in synchronous mode to check whether cancel was pressed.

Definition at line 84 of file mlBackgroundTask.h.

◆ setTaskFinishedCB()

void ml::BackgroundTask::setTaskFinishedCB	(	BackgroundTaskFinishedCB *	callback,
		void *	userdata
	)

Set this directly after the initialization of the task from the GUI thread.

This callback will be called whenever a task is either finished or canceled.

◆ setVerbose()

void ml::BackgroundTask::setVerbose ( bool flag )

inline

Sets whether task uses verbose logging.

Call this only in the setup of the task, not while it is already running.

Definition at line 194 of file mlBackgroundTask.h.

◆ shouldStop()

bool ml::BackgroundTask::shouldStop ( )

Returns whether the task should stop its work because it has been canceled.

Note: This method should be called regularly from the implementation of run() to allow that a task stops/is suspended when the user presses/suspend cancel. If it returns true, the task should clean up and return from run() ASAP. This method may only be called from the run() method and only from that thread, as it will block when the task is suspended.

◆ status()

Status ml::BackgroundTask::status ( ) const

Returns the status of the task.

This is thread-safe.

◆ statusString()

std::string ml::BackgroundTask::statusString ( ) const

Returns current status string.

This is thread-safe.

◆ suspend()

void ml::BackgroundTask::suspend ( )

Suspends the task.

This way, it will wait until resume() is called. This is thread-safe. To make this feature work, the task's run() implementation needs to call shouldStop() regularly.

◆ taskId()

MLuint32 ml::BackgroundTask::taskId ( ) const

inline

Returns the unique id of this task. The id of a task never changes.

Definition at line 217 of file mlBackgroundTask.h.

◆ waitAndExecuteNextMessage()

void ml::BackgroundTask::waitAndExecuteNextMessage ( )

Executes the next message.

It waits if no messages are available and processes the first message that is received. Note: only call this from within run().

Friends And Related Function Documentation

◆ BackgroundTaskManager

friend class BackgroundTaskManager

friend

Definition at line 274 of file mlBackgroundTask.h.

◆ BackgroundTaskManagerWorkerFunc

friend struct BackgroundTaskManagerWorkerFunc

friend

Definition at line 275 of file mlBackgroundTask.h.

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

MeVis/Foundation/Sources/MLBackgroundTasks/mlBackgroundTask.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ BackgroundTask()

◆ ~BackgroundTask()

Member Function Documentation

◆ addIdleTime()

◆ addObserver()

◆ cancel()

◆ executeNextMessage()

◆ getStatusInformation()

◆ hasOwner()

◆ idleTime()

◆ isCanceled()

◆ isSynchronous()

◆ isVerbose()

◆ logMessage()

◆ owner()

◆ progress()

◆ removeObserver()

◆ resume()

◆ run()

◆ runningTime()

◆ sendLogMessageToObservers()

◆ sendMessageToGUI()

◆ sendStatusChangedToObservers()

◆ sendStatusStringChangedToObservers()

◆ setOwnerWasDeleted()

◆ setProgress()

◆ setStatusString()

◆ setSynchronous()

◆ setSynchronousCancelField()

◆ setTaskFinishedCB()

◆ setVerbose()

◆ shouldStop()

◆ status()

◆ statusString()

◆ suspend()

◆ taskId()

◆ waitAndExecuteNextMessage()

Friends And Related Function Documentation

◆ BackgroundTaskManager

◆ BackgroundTaskManagerWorkerFunc