ERC CISST - cisst software

---

mtsTask Class Reference
[Multi Task Support]

#include <mtsTask.h>

Inheritance diagram for mtsTask:

[legend]Collaboration diagram for mtsTask:

[legend]List of all members.

---

Detailed Description

This class provides the base for implementing tasks that have a thread, a state table to store the state at each 'tick' (increment) of the task, and queues to receive messages (commands) from other tasks. It is derived from mtsComponent, so it also contains the provided and required interfaces, with their lists of commands.

Definition at line 59 of file mtsTask.h.

Public Types

• typedef mtsComponent BaseType

Public Member Functions

• mtsTask (const std::string &name, unsigned int sizeStateTable=256)
• virtual ~mtsTask ()
• virtual void Run (void)=0
• virtual void Startup (void)
• virtual void Cleanup (void)
• virtual void Configure (const std::string &CMN_UNUSED(filename)="")
• void SetInitializationDelay (double delay)
• virtual void Create (void *data)=0
• void Create (void)
• virtual void Start (void)=0
• virtual void Suspend (void)=0
• void Kill (void)
• double GetAveragePeriod (void) const
• const std::string GetDefaultStateTableName (void) const
• mtsStateTable * GetStateTable (const std::string &stateTableName)
• mtsStateTable * GetDefaultStateTable (void)
• bool AddStateTable (mtsStateTable *existingStateTable, bool addInterfaceProvided=true)
• mtsInterfaceRequired * AddInterfaceRequired (const std::string &interfaceRequiredName, mtsRequiredType required=MTS_REQUIRED)
• mtsInterfaceProvided * AddInterfaceProvided (const std::string &newInterfaceName, mtsInterfaceQueueingPolicy queueingPolicy=MTS_COMPONENT_POLICY)
• virtual bool WaitToStart (double timeout)
• virtual bool WaitToTerminate (double timeout)
• virtual void WaitForWakeup (void)
• virtual void Wakeup (void)
• virtual bool IsPeriodic (void) const
• virtual bool IsOverranPeriod (void) const
• virtual void ResetOverranPeriod (void)
• void ToStream (std::ostream &outputStream) const

Protected Types

• typedef cmnNamedMap< mtsStateTable > StateTableMapType

Protected Member Functions

• virtual void * RunInternal (void *argument)=0
• void DoRunInternal (void)
• virtual void StartupInternal (void)
• virtual void CleanupInternal (void)
• void Sleep (double timeInSeconds)
• mtsStateIndex::TimeTicksType GetTick (void) const
• virtual void SaveThreadStartData (void *data)
• virtual void SetThreadReturnValue (void *returnValue)
• void ChangeState (mtsComponentState::Enum newState)
• bool WaitForState (mtsComponentState desiredState, double timeout)

Protected Attributes

• osaThread Thread
• double InitializationDelay
• osaMutex StateChange
• osaThreadSignal StateChangeSignal
• mtsStateTable StateTable
• StateTableMapType StateTables
• bool OverranPeriod
• void * ThreadStartData
• void * ReturnValue

Friends

• class mtsManagerLocal

---

Member Typedef Documentation

typedef cmnNamedMap<mtsStateTable> mtsTask::StateTableMapType [protected]

Map of state tables, includes the default StateTable under the name "StateTable"

Definition at line 93 of file mtsTask.h.

---

Constructor & Destructor Documentation

mtsTask::mtsTask	(	const std::string &	name,
		unsigned int	sizeStateTable = 256
	)

Create a task with name 'name' and set the state table size (see mtsStateTable). This is the task base class. Tasks should be derived from one of the existing derived classes: mtsTaskContinuous, mtsTaskPeriodic, and mtsTaskFromCallback.

Parameters:

	name	The name for the task
	sizeStateTable	The history size of the state table

Note:

The full string name is maintained in the class member data (in mtsComponent base class). But, be aware that when a thread and/or thread buddy is created, only the first 6 characters of this name are used with the thread or thread buddy. This is an artifact of the 6 character limit imposed by RTAI/Linux.

See also:

mtsComponent, mtsTaskContinuous, mtsTaskPeriodic, mtsTaskFromCallback

virtual mtsTask::~mtsTask

(

)

[virtual]

Default Destructor.

---

Member Function Documentation

virtual void* mtsTask::RunInternal

(

void *

argument

)

[protected, pure virtual]

The member function that is passed as 'start routine' argument for thread creation.

Referenced by mtsTaskFromCallback::DoCallback().

void mtsTask::DoRunInternal

(

void

)

[protected]

The main part of the Run loop that is the same for all derived classes. This should not be overloaded.

virtual void mtsTask::StartupInternal

(

void

)

[protected, virtual]

The member funtion that is executed as soon as the thread gets created. It does some housekeeping before the user code can be executed.

virtual void mtsTask::CleanupInternal

(

void

)

[protected, virtual]

The member function that is executed once the task terminates. This does some cleanup work.

void mtsTask::Sleep

(

double

timeInSeconds

)

[protected]

Delay the task by the specified amount. This is a protected member function because it should only be called from within the task. Otherwise, use osaSleep.

mtsStateIndex::TimeTicksType mtsTask::GetTick

(

void

)

const [protected]

Return the current tick count.

virtual void mtsTask::SaveThreadStartData

(

void *

data

)

[protected, virtual]

Save any 'user data' that was passed to the thread start routine.

bool mtsTask::WaitForState	(	mtsComponentState	desiredState,
		double	timeout
	)			[protected, virtual]

Helper function to wait on a state change, with specified timeout in seconds.

Reimplemented from mtsComponent.

virtual void mtsTask::Run

(

void

)

[pure virtual]

Virtual method that gets overloaded to run the actual task.

virtual void mtsTask::Startup

(

void

)

[inline, virtual]

Virtual method that gets overloaded, and is run before the task is started.

Definition at line 184 of file mtsTask.h.

virtual void mtsTask::Cleanup

(

void

)

[inline, virtual]

Virtual method that gets overloaded, and is run after the task gets killed using Kill() method.

Definition at line 189 of file mtsTask.h.

virtual void mtsTask::Configure

(

const std::string &

CMN_UNUSED(filename) = ""

)

[inline, virtual]

Virtual method that gets called when the task/interface needs to be configured. Should it take XML info??

Definition at line 193 of file mtsTask.h.

void mtsTask::SetInitializationDelay

(

double

delay

)

Set the initialization delay. See InitializationDelay.

void mtsTask::Create

(

void

)

[inline, virtual]

Virtual method to create the components, e.g. for tasks create the required threads. For other components, place initialization code.

Reimplemented from mtsComponent.

Definition at line 203 of file mtsTask.h.

References mtsComponent::Create().

virtual void mtsTask::Start

(

void

)

[pure virtual]

Start or resume execution of the task.

Reimplemented from mtsComponent.

virtual void mtsTask::Suspend

(

void

)

[pure virtual]

Suspend the execution of the task.

void mtsTask::Kill

(

void

)

[virtual]

End the task

Reimplemented from mtsComponent.

double mtsTask::GetAveragePeriod

(

void

)

const [inline]

Return the average period.

Definition at line 215 of file mtsTask.h.

const std::string mtsTask::GetDefaultStateTableName

(

void

)

const [inline]

Return the name of this state table.

Definition at line 218 of file mtsTask.h.

mtsStateTable* mtsTask::GetStateTable

(

const std::string &

stateTableName

)

[inline]

Return a pointer to state table with the given name.

Definition at line 223 of file mtsTask.h.

mtsStateTable* mtsTask::GetDefaultStateTable

(

void

)

[inline]

Return a pointer to the default state table. See GetStateTable and GetDefaultStateTableName.

Definition at line 229 of file mtsTask.h.

bool mtsTask::AddStateTable	(	mtsStateTable *	existingStateTable,
		bool	addInterfaceProvided = true
	)

Add an existing state table to the list of known state tables in this task. This method will add a provided interface for the state table using the name "StateTable" + existingStateTable->GetName() unless the caller specifies that no interface should be created.

By default, all state tables added will advance at each call of the Run method. To avoid the automatic advance, use the method mtsStateTable::SetAutomaticAdvance(false).

mtsInterfaceRequired* mtsTask::AddInterfaceRequired	(	const std::string &	interfaceRequiredName,
		mtsRequiredType	required = MTS_REQUIRED
	)			[virtual]

Add a required interface. This interface will later on be connected to another task and use the provided interface of the other task. The required interface created also contains a list of event handlers to be used as observers.

Reimplemented from mtsComponent.

mtsInterfaceProvided* mtsTask::AddInterfaceProvided	(	const std::string &	newInterfaceName,
		mtsInterfaceQueueingPolicy	queueingPolicy = MTS_COMPONENT_POLICY
	)			[virtual]

Method to add a provided interface to the component. This method is virtual so that mtsTaskBase can redefine it and generate the appropriate type of interface, i.e. mtsInterfaceProvided as opposed to mtsInterfaceProvided for mtsComponent.

Reimplemented from mtsComponent.

virtual bool mtsTask::WaitToStart

(

double

timeout

)

[virtual]

Wait for task to start.

Parameters:

timeout

The timeout in seconds

Returns:

true if task has started; false if timeout occurred before task started.

virtual bool mtsTask::WaitToTerminate

(

double

timeout

)

[virtual]

Wait for task to finish (after issuing a task Kill).

Parameters:

timeout

The timeout in seconds

Returns:

true if the task terminated without timeout happening; false if timeout occured and task did not finish

virtual void mtsTask::WaitForWakeup

(

void

)

[inline, virtual]

Suspend this task until the Wakeup method is called.

Definition at line 271 of file mtsTask.h.

virtual void mtsTask::Wakeup

(

void

)

[inline, virtual]

Wakeup the task.

Definition at line 276 of file mtsTask.h.

virtual bool mtsTask::IsPeriodic

(

void

)

const [inline, virtual]

Return true if thread is periodic.

Definition at line 283 of file mtsTask.h.

virtual bool mtsTask::IsOverranPeriod

(

void

)

const [inline, virtual]

Return true if task overran allocated period. Note that this is not restricted to mtsTaskPeriodic. For example, an mtsTaskFromCallback can overrun if a second callback occurs before the first is finished.

Definition at line 290 of file mtsTask.h.

virtual void mtsTask::ResetOverranPeriod

(

void

)

[inline, virtual]

Reset overran period flag.

Definition at line 295 of file mtsTask.h.

void mtsTask::ToStream

(

std::ostream &

outputStream

)

const [virtual]

Send a human readable description of the component.

Reimplemented from mtsComponent.

---

Member Data Documentation

osaThread mtsTask::Thread [protected]

The OS independent thread object.

Definition at line 72 of file mtsTask.h.

double mtsTask::InitializationDelay [protected]

Delay given for the task to start. During initialization the task thread will wait for the specified delay (set by default to 3 minutes in the constructor). Increasing this delay can be useful when using mtsTaskFromCallback if the callback might take more than 3 minutes to trigger the task's Run method.

Definition at line 79 of file mtsTask.h.

osaMutex mtsTask::StateChange [protected]

Mutex used when changing task states. Do not change this directly, use the ChangeState method instead.

Definition at line 83 of file mtsTask.h.

osaThreadSignal mtsTask::StateChangeSignal [protected]

Signal for caller to wait on task state changes.

Definition at line 86 of file mtsTask.h.

mtsStateTable mtsTask::StateTable [protected]

The state data table object to store the states of the task.

Definition at line 89 of file mtsTask.h.

bool mtsTask::OverranPeriod [protected]

True if the task took more time to do computation than allocated time.

Definition at line 98 of file mtsTask.h.

void* mtsTask::ThreadStartData [protected]

The data passed to the thread.

Definition at line 101 of file mtsTask.h.

void* mtsTask::ReturnValue [protected]

The return value for RunInternal.

Definition at line 104 of file mtsTask.h.

---

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

• mtsTask.h

---