CYITaskBase Class Reference

Detailed Description

Abstract base class for CYITask.

See also

CYITask<ResultType>

#include <thread/YiTask.h>

Inheritance diagram for CYITaskBase:

Public Types
enum	TASK_STATE {   TASK_NEW,   TASK_PENDING_EXECUTION,   TASK_EXECUTING,   TASK_COMPLETED,   TASK_CANCELLED }

Public Member Functions
virtual	~CYITaskBase ()
virtual bool	TakeOwnershipOfFuture (std::unique_ptr< CYIAbstractFuture > pFuture)
TASK_STATE	GetState () const
bool	IsFutureOwner () const
bool	MarkPendingExecution ()
void	RequestCancellation ()
bool	Execute ()

Protected Member Functions
virtual void	RunAndAssignResult ()=0
	Executes this task and assigns its result to the associated future object, if it exists. More...
bool	IsCancellationRequested () const
void	SetCancellationRequestSucceeded ()
virtual void	CleanUpAfterCancellation ()

Protected Attributes
CYIMutex	m_mutex

Friends
class	CYIAbstractFuture
template<typename T >
class	CYITask

Member Enumeration Documentation

enum CYITaskBase::TASK_STATE

An enum listing the various states that a task can be in.

Enumerator
TASK_NEW
TASK_PENDING_EXECUTION
TASK_EXECUTING
TASK_COMPLETED
TASK_CANCELLED

Constructor & Destructor Documentation

virtual CYITaskBase::~CYITaskBase ( )

virtual

Member Function Documentation

virtual void CYITaskBase::CleanUpAfterCancellation ( )

inlineprotectedvirtual

A function that can be used to 'clean-up' after a task has been cancelled. Normally, clean-up is performed in the destructor, but in some cases it may be advantageous to clean-up earlier.

For example, if a task allocates a lot of memory upon creation, that memory would be cleared upon destruction of the task. However, when a task is cancelled it is not necessarily destroyed immediately afterwards. Overriding this function would allow the task to clear its allocated memory earlier than when the task is destroyed.

bool CYITaskBase::Execute

(

)

Executes this task. The task's state will change to TASK_COMPLETED upon successful execution.

Note

Has no effect if this task is not in the TASK_NEW or TASK_PENDING_EXECUTION state.

If this task has an associated future object, the ExecutionStarted signal is called and the result of the task's execution is assigned to the future object upon completion (the Completed signal is also triggered).

If execution is terminated prematurely (e.g. through the cancellation of an associated future object), this function may return early and will still report success (e.g. true). In case of premature termination, the task's state will be change to TASK_CANCELLED instead of TASK_COMPLETED.

Returns

Returns true if the task was successfully executed.

TASK_STATE CYITaskBase::GetState

(

)

const

Warning

This function should only be used for debugging purposes.

Returns

Returns the state that the task is in.

bool CYITaskBase::IsCancellationRequested ( ) const

protected

A function used to check if a cancellation has been requested for an already-executing task. Subclasses of this class can use this function to check if they should abort execution of the task.

Returns

Returns true if a cancellation has been requested for this task.

bool CYITaskBase::IsFutureOwner

(

)

const

Warning

This function should only be used for debugging purposes.

Returns

Returns true if this task owns its associated future.

bool CYITaskBase::MarkPendingExecution

(

)

Marks this task as pending execution.

Note

Has no effect if the task is not in the TASK_NEW state.

This is typically only called by classes that execute tasks.

Returns

Returns true if the task was successfully marked as pending execution.

void CYITaskBase::RequestCancellation

(

)

Requests the cancellation of this task.

Note

This is typically only called by classes that execute tasks.

virtual void CYITaskBase::RunAndAssignResult ( )

protectedpure virtual

Executes this task and assigns its result to the associated future object, if it exists.

void CYITaskBase::SetCancellationRequestSucceeded ( )

protected

This function can be used to signal that the cancellation of an already-executing task was successful. Subclasses of this class can use this function to indicate that the execution of the task was aborted and that the returned value is invalid. After this function has been called and after the call to Run() has completed, the state of the task will change to TASK_CANCELLED intead of TASK_COMPLETED.

Note

Should only be called from the Run() function of a subclass.

virtual bool CYITaskBase::TakeOwnershipOfFuture ( std::unique_ptr< CYIAbstractFuture >  pFuture )

virtual

Instructs this task to take ownership of its associated future. When a task has ownership of its associated future, the associated future will be deleted when the task is deleted (typically when the task's execution has completed). To reduce the risk of ownership problems, the associated future's unique pointer must be passed to this function. If the provided future object is not the same object as the currently-associated future object, the provided future object is deleted and the task does not take ownership of its associated future.

A use case for transferring ownership of a future object to a task would be when a user only wants to receive signals when the task has completed and has no need to cancel queued tasks.

Note

Has no effect if this task does not have an associated future object, or if this task is not in the TASK_NEW state. Therefore, this function has no effect once a task has been enqueued.

Returns

Returns true if ownership was successfully taken.

Friends And Related Function Documentation

friend class CYIAbstractFuture

friend

template<typename T >

friend class CYITask

friend

Member Data Documentation

CYIMutex CYITaskBase::m_mutex

mutableprotected

---

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

• thread/YiTask.h