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

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

Setup of task properties
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 handling / canceling
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)

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

float	progress () const
	get current progress (threadsafe)

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

Owner related methods
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!)

Message handling
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.

Logging
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)

Misc
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

Observing a task
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)

Protected Member Functions
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

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 )

Create a new task with given owner (the owner can be used to associate the task with a given class instance, e.g.

a 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

add given timeInSecs as spent idle time

Definition at line 251 of file mlBackgroundTask.h.

References mlrange_cast().

◆ addObserver()

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

add the given observer (threadsafe) (ownership stays with caller)

◆ cancel()

void ml::BackgroundTask::cancel ( )

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

◆ executeNextMessage()

bool ml::BackgroundTask::executeNextMessage ( )

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

NOTE: only call from within run()

◆ getStatusInformation()

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

get the complete status information (threadsafe)

◆ hasOwner()

bool ml::BackgroundTask::hasOwner ( ) const

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

◆ idleTime()

double ml::BackgroundTask::idleTime ( ) const

inline

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)

Definition at line 193 of file mlBackgroundTask.h.

◆ isCanceled()

bool ml::BackgroundTask::isCanceled ( ) const

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

◆ isSynchronous()

bool ml::BackgroundTask::isSynchronous ( ) const

inline

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

Definition at line 77 of file mlBackgroundTask.h.

◆ isVerbose()

bool ml::BackgroundTask::isVerbose ( ) const

inline

check if task uses verbose logging

Definition at line 177 of file mlBackgroundTask.h.

◆ logMessage()

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

log a message (only logged if verbose logging is turned on) (threadsafe)

◆ owner()

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

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

◆ progress()

float ml::BackgroundTask::progress ( ) const

get current progress (threadsafe)

◆ removeObserver()

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

remove the given observer (threadsafe) (ownership stays with caller)

◆ resume()

void ml::BackgroundTask::resume ( )

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

◆ run()

virtual void ml::BackgroundTask::run ( )

pure virtual

run method that needs to be reimplemented (called from 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 canceled, only call from GUI thread)

Definition at line 190 of file mlBackgroundTask.h.

◆ sendLogMessageToObservers()

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

protected

send the status string change to all observers

◆ sendMessageToGUI()

void ml::BackgroundTask::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.

NOTE: only call from within run()

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

◆ sendStatusChangedToObservers()

void ml::BackgroundTask::sendStatusChangedToObservers ( )

protected

send the status change to all observers

◆ sendStatusStringChangedToObservers()

void ml::BackgroundTask::sendStatusStringChangedToObservers ( )

protected

send the status string change to all observers

◆ setOwnerWasDeleted()

void ml::BackgroundTask::setOwnerWasDeleted ( )

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

◆ setProgress()

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

virtual

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

Reimplemented in ml::ModuleBackgroundTask.

◆ setStatusString()

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

virtual

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

Reimplemented in ml::ModuleBackgroundTask.

◆ setSynchronous()

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

inline

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

Definition at line 79 of file mlBackgroundTask.h.

References mlrange_cast().

◆ setSynchronousCancelField()

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

inline

set a cancel field that is used in synchronous mode to check if cancel was pressed

Definition at line 84 of file mlBackgroundTask.h.

References mlrange_cast().

◆ setTaskFinishedCB()

void ml::BackgroundTask::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

◆ setVerbose()

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

inline

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

Definition at line 179 of file mlBackgroundTask.h.

References mlrange_cast().

◆ shouldStop()

bool ml::BackgroundTask::shouldStop ( )

returns if 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 cleanup and return from run() asap. This method may only be called from the run() method and only from that thread, since it will block when the task is suspended.

◆ status()

Status ml::BackgroundTask::status ( ) const

returns the status of the task (threadsafe)

◆ statusString()

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

get current status string (threadsafe)

◆ suspend()

void ml::BackgroundTask::suspend ( )

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

To make this feature work, the task's run() implementation needs to call shouldStop() regularly.

◆ taskId()

MLuint32 ml::BackgroundTask::taskId ( ) const

inline

get the unique id of this task, the id of a task never changes

Definition at line 199 of file mlBackgroundTask.h.

◆ waitAndExecuteNextMessage()

void ml::BackgroundTask::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()

Friends And Related Symbol Documentation

◆ BackgroundTaskManager

friend class BackgroundTaskManager

friend

Definition at line 254 of file mlBackgroundTask.h.

◆ BackgroundTaskManagerWorkerFunc

friend struct BackgroundTaskManagerWorkerFunc

friend

Definition at line 255 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 Symbol Documentation

◆ BackgroundTaskManager

◆ BackgroundTaskManagerWorkerFunc