Orocos Real-Time Toolkit  2.9.0
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Friends | List of all members
RTT::os::Thread Class Reference

A Thread object executes user code in its own thread. More...

#include <rtt/os/Thread.hpp>

Inheritance diagram for RTT::os::Thread:
RTT::os::ThreadInterface RTT::Activity RTT::extras::TimerThread RTT::corba::CorbaDispatcher RTT::corba::OrbRunner RTT::extras::FileDescriptorActivity RTT::extras::IRQActivity RTT::mqueue::Dispatcher RTT::extras::SimulationThread

Public Member Functions

 Thread (int scheduler, int priority, double period, unsigned cpu_affinity, const std::string &name)
 Create a Thread with a given scheduler type, priority and a name. More...
 
virtual ~Thread ()
 
virtual bool start ()
 Start the Thread. More...
 
virtual bool stop ()
 Stop the Thread. More...
 
void setStopTimeout (Seconds s)
 Sets the timeout for stop(), in seconds. More...
 
Seconds getStopTimeout () const
 Returns the desired timeout for stop(), in seconds. More...
 
bool setPeriod (Seconds s)
 Set the periodicity in Seconds. More...
 
bool setPeriod (secs s, nsecs ns)
 Set the periodicity of this thread (seconds, nanoseconds) More...
 
bool setPeriod (TIME_SPEC p)
 Set the periodicity of this thread. More...
 
void getPeriod (secs &s, nsecs &ns) const
 Get the periodicity of this thread (seconds, nanoseconds) More...
 
virtual Seconds getPeriod () const
 Get the periodicity in Seconds. More...
 
virtual nsecs getPeriodNS () const
 Get the periodicity in nanoseconds. More...
 
virtual bool isPeriodic () const
 
virtual bool isRunning () const
 Returns whether the thread is running. More...
 
virtual bool isActive () const
 Returns whether the thread is active. More...
 
virtual const char * getName () const
 Read the name of this task. More...
 
virtual RTOS_TASKgetTask ()
 Get the RTOS_TASK pointer. More...
 
virtual const RTOS_TASKgetTask () const
 const version of the above. More...
 
virtual bool setScheduler (int sched_type)
 Change the scheduler policy in which this thread runs. More...
 
virtual int getScheduler () const
 Get the scheduler policy in which this thread runs. More...
 
virtual bool setPriority (int priority)
 Set the priority of this Thread. More...
 
virtual int getPriority () const
 The priority of this Thread. More...
 
virtual unsigned int getPid () const
 Returns the Process or Thread ID of this thread, as assigned by the Operating System. More...
 
virtual bool setCpuAffinity (unsigned cpu_affinity)
 Set cpu affinity for this thread. More...
 
virtual unsigned getCpuAffinity () const
 
virtual void yield ()
 Yields (put to the back of the scheduler queue) the calling thread. More...
 
virtual void setMaxOverrun (int m)
 
virtual int getMaxOverrun () const
 
virtual void setWaitPeriodPolicy (int p)
 Set the wait policy of a periodic thread. More...
 
unsigned int threadNumber () const
 The unique thread number (within the same process). More...
 
bool isSelf () const
 

Static Public Member Functions

static void setStackSize (unsigned int ssize)
 Sets the stack size of the threads to be created. More...
 
static void setLockTimeoutNoPeriod (double timeout_in_s)
 Sets the lock timeout for a thread which does not have a period The default is 1 second. More...
 
static void setLockTimeoutPeriodFactor (double factor)
 Set the lock timeout for a thread which has a period by a factor of the period The default is factor 10. More...
 

Protected Member Functions

void terminate ()
 Exit and destroy the thread. More...
 
void emergencyStop ()
 
virtual void step ()
 
virtual void loop ()
 
virtual bool breakLoop ()
 
virtual bool initialize ()
 
virtual void finalize ()
 

Protected Attributes

int msched_type
 Desired scheduler type. More...
 
bool active
 When set to 1, the thread will run, when set to 0 the thread will stop ( isActive() ) More...
 
bool prepareForExit
 Signal the thread that it should exit. More...
 
bool inloop
 Is true when in the loop (isRunning() ) More...
 
bool running
 Indicates if step() or loop() should be executed. More...
 
RTOS_TASK rtos_task
 The realtime task structure created by this object. More...
 
rt_sem_t sem
 The semaphore used for starting the thread. More...
 
MutexRecursive breaker
 Used to implement synchronising breakLoop(). More...
 
int maxOverRun
 The maximum times a periodic overrun may happen, or -1 if unlimited. More...
 
NANO_TIME period
 The period as it is passed to the operating system. More...
 
double stopTimeout
 The timeout, in seconds, for stop() More...
 
int threadnb
 Threads are given an unique number, which follows thread creation order. More...
 

Static Protected Attributes

static unsigned int default_stack_size = 0
 
static double lock_timeout_no_period_in_s = 1.0
 configuration of the lock timeout in seconds More...
 
static double lock_timeout_period_factor = 10.0
 configuration of the lock timeout for periodic tasks in seconds More...
 

Friends

void * thread_function (void *t)
 

Detailed Description

A Thread object executes user code in its own thread.

If the underlying OS supports it, both period and priority can be changed after creation. When the period is 0, the loop() function is executed, when the period is greater than 0, the step() function is executed. Note: if the user does not implement loop(), it will call step() by default.

The main functions to implement are initialize(), step()/loop() and finalize(). initialize() is called when start() is called, and before the first step()/loop() and finalize() is called when stop() is called after the last step()/loop() returns.

behavior

When a period is set, step() is executed from the moment start() is called, and afterwards according to it's period. When stop() is called, it waits for the step() function to return and then stops the periodic execution.

Step() overruns are detected and the threshold to 'emergency stop' the thread can be set by setMaxOverrun(). Overruns must be accumulated 'on average' to trigger this behavior: one not overrunning step() compensates for one overrunning step().

periodic behaviour

The first invocation of start() invokes the initialize() function and runs the loop() method in the thread. When loop() returns the thread waits for another start() to execute loop() again. In that case, initialize() is not executed.

When stop() is called and the thread is still executing loop() and breakLoop() returns true (not the default), the stop() function succeeds and the finalize() method is called by stop(). If the thread was not executing loop(), stop will always call finalize() and return success.

The user must provide an implementation of breakLoop() returning true to make stop() work while loop() is being executed. stop() will fail and not execute finalize() if the thread executes loop() and breakLoop() is not reimplemented to return true.

, priorities, schedulers and stack sizes

These four parameters are the parameters that users wish to set for every thread created. All but stack size can be modified after creation, and if the OS permits it, modified even when the thread is using user code. All these parameters are passed to the underlying OS unmodified. In case an incorrect combination is made, the change may be rejected or adjusted to a close or safe value.

See also
setPeriod, setScheduler, setPriority, setStackSize

Definition at line 109 of file Thread.hpp.

Constructor & Destructor Documentation

RTT::os::Thread::Thread ( int  scheduler,
int  priority,
double  period,
unsigned  cpu_affinity,
const std::string &  name 
)

Create a Thread with a given scheduler type, priority and a name.

Parameters
schedulerThe scheduler, one of ORO_SCHED_RT or ORO_SCHED_OTHER.
priorityThe priority of the thread, this is interpreted by your RTOS.
periodThe period in seconds (eg 0.001) of the thread, or zero if not periodic.
cpu_affinityThe cpu affinity of the thread, this is interpreted by your RTOS. If 0, the new thread inherits the affinity of its creator (the default).
nameThe name of the Thread. May be used by your OS to identify the thread. the thread's own virtual functions are executed.

Definition at line 236 of file Thread.cpp.

References breaker, RTT::Critical, default_stack_size, getCpuAffinity(), getName(), RTT::dev::NameServer< _ValueType >::getObject(), getPeriod(), getPid(), getPriority(), getScheduler(), RTT::Info, msched_type, RTT::dev::DigitalOutInterface::nameserver, ORO_SCHED_OTHER, rtos_sem_destroy(), rtos_sem_init(), rtos_sem_wait(), rtos_task, RTT::os::rtos_task_create(), sem, thread_function, RTT::os::ThreadInterface::threadNumber(), and RTT::Warning.

RTT::os::Thread::~Thread ( )
virtual

Definition at line 325 of file Thread.cpp.

References RTT::Debug, getName(), isRunning(), rtos_sem_destroy(), sem, stop(), and terminate().

Member Function Documentation

bool RTT::os::Thread::breakLoop ( )
protectedvirtual
void RTT::os::Thread::emergencyStop ( )
protected

Definition at line 226 of file Thread.cpp.

References active, finalize(), inloop, and running.

Referenced by RTT::Activity::loop(), and RTT::os::thread_function().

void RTT::os::Thread::finalize ( )
protectedvirtual
unsigned RTT::os::Thread::getCpuAffinity ( ) const
virtual
Returns
the cpu affinity (
See also
rtos_task_set_cpu_affinity)

Implements RTT::os::ThreadInterface.

Reimplemented in RTT::Activity.

Definition at line 606 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_get_cpu_affinity().

Referenced by RTT::Activity::getCpuAffinity(), and Thread().

int RTT::os::Thread::getMaxOverrun ( ) const
virtual

Implements RTT::os::ThreadInterface.

Definition at line 643 of file Thread.cpp.

References maxOverRun.

const char * RTT::os::Thread::getName ( ) const
virtual
void RTT::os::Thread::getPeriod ( secs s,
nsecs ns 
) const

Get the periodicity of this thread (seconds, nanoseconds)

Definition at line 570 of file Thread.cpp.

References period.

double RTT::os::Thread::getPeriod ( ) const
virtual

Get the periodicity in Seconds.

Return zero if non periodic.

Implements RTT::os::ThreadInterface.

Reimplemented in RTT::extras::FileDescriptorActivity, and RTT::Activity.

Definition at line 591 of file Thread.cpp.

References RTT::nsecs_to_Seconds(), and period.

Referenced by getStopTimeout(), RTT::extras::SimulationThread::run(), RTT::extras::SimulationThread::SimulationThread(), RTT::extras::SimulationThread::step(), and Thread().

nsecs RTT::os::Thread::getPeriodNS ( ) const
virtual

Get the periodicity in nanoseconds.

Return zero if non periodic.

Implements RTT::os::ThreadInterface.

Definition at line 596 of file Thread.cpp.

References period.

unsigned int RTT::os::Thread::getPid ( ) const
virtual

Returns the Process or Thread ID of this thread, as assigned by the Operating System.

This function tries to return the Thread ID, if the OS supports it, otherwise it returns the process ID. If that is not available either, zero is returned. On Linux systems for example, the Thread ID of the main thread is equal to the Process ID. The Thread ID of every newly created thread is different from the Process ID (and unique).

Implements RTT::os::ThreadInterface.

Definition at line 611 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_get_pid().

Referenced by Thread().

int RTT::os::Thread::getPriority ( ) const
virtual

The priority of this Thread.

Returns
The priority given upon construction of this thread or set with setPriority. The returned number has to be interpreted in the current OS scheduler.
See also
setScheduler

Implements RTT::os::ThreadInterface.

Definition at line 586 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_get_priority().

Referenced by RTT::extras::SimulationThread::SimulationThread(), and Thread().

int RTT::os::Thread::getScheduler ( ) const
virtual

Get the scheduler policy in which this thread runs.

Returns
An OS-specific value which represents the used scheduler.
See also
setScheduler

Implements RTT::os::ThreadInterface.

Definition at line 488 of file Thread.cpp.

References msched_type, period, rtos_task, RTT::os::rtos_task_get_scheduler(), RTT::os::rtos_task_set_period(), and RTT::os::rtos_task_set_scheduler().

Referenced by setScheduler(), and Thread().

Seconds RTT::os::Thread::getStopTimeout ( ) const

Returns the desired timeout for stop(), in seconds.

If not set with setStopTimeout, the timeout is deduced from the global values lock_timeout_period_factor and lock_timeout_no_period_in_s

Definition at line 408 of file Thread.cpp.

References getPeriod(), lock_timeout_no_period_in_s, lock_timeout_period_factor, period, and stopTimeout.

Referenced by stop(), and RTT::Activity::stop().

virtual RTOS_TASK* RTT::os::Thread::getTask ( )
inlinevirtual

Get the RTOS_TASK pointer.

Note
Using this function leads to non-portable code. It is here for users which wish to tweak OS specific thread settings.

Implements RTT::os::ThreadInterface.

Definition at line 205 of file Thread.hpp.

Referenced by RTT::Activity::loop(), and RTT::os::thread_function().

virtual const RTOS_TASK* RTT::os::Thread::getTask ( ) const
inlinevirtual

const version of the above.

Implements RTT::os::ThreadInterface.

Definition at line 210 of file Thread.hpp.

bool RTT::os::Thread::initialize ( )
protectedvirtual
bool RTT::os::Thread::isActive ( ) const
virtual

Returns whether the thread is active.

A thread is active between the invocation of start() and the invocation of stop().

Implements RTT::os::ThreadInterface.

Reimplemented in RTT::Activity.

Definition at line 464 of file Thread.cpp.

References active.

Referenced by RTT::Activity::isActive(), start(), and RTT::Activity::trigger().

bool RTT::os::Thread::isPeriodic ( ) const
virtual

Reimplemented in RTT::Activity.

Definition at line 581 of file Thread.cpp.

References period.

Referenced by RTT::Activity::isPeriodic().

bool RTT::os::Thread::isRunning ( ) const
virtual

Returns whether the thread is running.

A thread is running if it is executing its loop() function or in the process of periodically calling step(). Hence for periodic threads, isRunning() == isActive() while for non-periodic threads, isRunning() is only true if isActive() and it is executing loop().

Implements RTT::os::ThreadInterface.

Reimplemented in RTT::extras::FileDescriptorActivity, RTT::Activity, and RTT::extras::SimulationThread.

Definition at line 459 of file Thread.cpp.

References running.

Referenced by RTT::extras::SimulationThread::isRunning(), RTT::Activity::isRunning(), and ~Thread().

bool ThreadInterface::isSelf ( ) const
inherited
void RTT::os::Thread::loop ( )
protectedvirtual
bool RTT::os::Thread::setCpuAffinity ( unsigned  cpu_affinity)
virtual

Set cpu affinity for this thread.

Parameters
cpu_affinityThe cpu affinity of the thread (
See also
rtos_task_set_cpu_affinity).
Returns
true if the mask has been applied

Reimplemented in RTT::Activity.

Definition at line 601 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_set_cpu_affinity().

Referenced by RTT::Activity::setCpuAffinity().

void RTT::os::Thread::setLockTimeoutNoPeriod ( double  timeout_in_s)
static

Sets the lock timeout for a thread which does not have a period The default is 1 second.

Parameters
timeout_in_sthe timeout is seconds

Definition at line 71 of file Thread.cpp.

References lock_timeout_no_period_in_s.

void RTT::os::Thread::setLockTimeoutPeriodFactor ( double  factor)
static

Set the lock timeout for a thread which has a period by a factor of the period The default is factor 10.

Parameters
factorFactor of the period

Definition at line 73 of file Thread.cpp.

References lock_timeout_period_factor.

void RTT::os::Thread::setMaxOverrun ( int  m)
virtual

Implements RTT::os::ThreadInterface.

Definition at line 638 of file Thread.cpp.

References maxOverRun.

bool RTT::os::Thread::setPeriod ( Seconds  new_period)
virtual

Set the periodicity in Seconds.

Parameters
new_periodA positive number expressing the period
Returns
true if it was accepted, false otherwise.

Implements RTT::os::ThreadInterface.

Definition at line 536 of file Thread.cpp.

References RTT::Seconds_to_nsecs().

Referenced by RTT::Activity::Activity(), and setPeriod().

bool RTT::os::Thread::setPeriod ( secs  s,
nsecs  ns 
)

Set the periodicity of this thread (seconds, nanoseconds)

Definition at line 542 of file Thread.cpp.

References period, rtos_sem_signal(), rtos_task, RTT::os::rtos_task_make_periodic(), and sem.

bool RTT::os::Thread::setPeriod ( TIME_SPEC  p)

Set the periodicity of this thread.

Definition at line 565 of file Thread.cpp.

References setPeriod().

bool RTT::os::Thread::setPriority ( int  priority)
virtual

Set the priority of this Thread.

Parameters
priorityThe priority given upon construction of this thread. It has to be interpreted in the current OS scheduler.
See also
setScheduler

Implements RTT::os::ThreadInterface.

Definition at line 576 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_set_priority().

bool RTT::os::Thread::setScheduler ( int  sched_type)
virtual

Change the scheduler policy in which this thread runs.

Parameters
sched_typeAn OS-specific value which selects a scheduler. Orocos requires that these two values are available:
  • ORO_SCHED_RT: Hint the OS that this thread should be scheduled as a priority or real-time process.
  • ORO_SCHED_OTHER: Hint the OS that this thread should not be scheduled as a priority or real-time process.

Your OS can in addition provide other sched_type's which map more naturally to the schedulers present. If your OS does not make a distinction between real-time and other, both values may map to the same scheduler type.

Returns
true if the change could be made.

Implements RTT::os::ThreadInterface.

Definition at line 469 of file Thread.cpp.

References RTT::os::CheckScheduler(), getScheduler(), RTT::Info, msched_type, rtos_sem_signal(), rtos_task, RTT::os::rtos_task_get_name(), RTT::os::rtos_task_set_scheduler(), and sem.

Referenced by RTT::extras::SimulationThread::SimulationThread().

void RTT::os::Thread::setStackSize ( unsigned int  ssize)
static

Sets the stack size of the threads to be created.

This value is suggestive and may be altered or ignored by your operating system. Use zero to use the system's default.

Parameters
ssizethe size of the stack in bytes

Definition at line 69 of file Thread.cpp.

References default_stack_size.

void RTT::os::Thread::setStopTimeout ( Seconds  s)

Sets the timeout for stop(), in seconds.

See also
getStopTimeout

Definition at line 403 of file Thread.cpp.

References stopTimeout.

void RTT::os::Thread::setWaitPeriodPolicy ( int  p)
virtual

Set the wait policy of a periodic thread.

Parameters
Thewait policy can be ORO_WAIT_ABS (absolute wait) and ORO_WAIT_REL (relative wait, with respect to current time)

Implements RTT::os::ThreadInterface.

Reimplemented in RTT::Activity.

Definition at line 648 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_set_wait_period_policy().

bool RTT::os::Thread::start ( )
virtual
void RTT::os::Thread::step ( )
protectedvirtual
bool RTT::os::Thread::stop ( )
virtual
void RTT::os::Thread::terminate ( )
protected

Exit and destroy the thread.

Precondition
this is only called from within the destructor.
Postcondition
the thread does no longer exist.

Definition at line 621 of file Thread.cpp.

References active, prepareForExit, rtos_sem_signal(), rtos_task, RTT::os::rtos_task_delete(), and sem.

Referenced by RTT::Activity::~Activity(), and ~Thread().

unsigned int RTT::os::ThreadInterface::threadNumber ( ) const
inlineinherited

The unique thread number (within the same process).

Definition at line 217 of file ThreadInterface.hpp.

Referenced by Thread(), and RTT::os::thread_function().

void RTT::os::Thread::yield ( )
virtual

Yields (put to the back of the scheduler queue) the calling thread.

Implements RTT::os::ThreadInterface.

Definition at line 616 of file Thread.cpp.

References rtos_task, and RTT::os::rtos_task_yield().

Friends And Related Function Documentation

void* thread_function ( void *  t)
friend

This is one time initialisation

The real task starts here.

Definition at line 75 of file Thread.cpp.

Referenced by Thread().

Member Data Documentation

bool RTT::os::Thread::active
protected

When set to 1, the thread will run, when set to 0 the thread will stop ( isActive() )

Definition at line 311 of file Thread.hpp.

Referenced by emergencyStop(), isActive(), start(), stop(), RTT::Activity::stop(), terminate(), and RTT::os::thread_function().

MutexRecursive RTT::os::Thread::breaker
protected

Used to implement synchronising breakLoop().

Definition at line 341 of file Thread.hpp.

Referenced by stop(), RTT::Activity::stop(), Thread(), and RTT::os::thread_function().

unsigned int RTT::os::Thread::default_stack_size = 0
staticprotected

Definition at line 290 of file Thread.hpp.

Referenced by setStackSize(), and Thread().

bool RTT::os::Thread::inloop
protected

Is true when in the loop (isRunning() )

Definition at line 321 of file Thread.hpp.

Referenced by emergencyStop(), stop(), RTT::Activity::stop(), and RTT::os::thread_function().

double RTT::os::Thread::lock_timeout_no_period_in_s = 1.0
staticprotected

configuration of the lock timeout in seconds

Definition at line 295 of file Thread.hpp.

Referenced by getStopTimeout(), and setLockTimeoutNoPeriod().

double RTT::os::Thread::lock_timeout_period_factor = 10.0
staticprotected

configuration of the lock timeout for periodic tasks in seconds

Definition at line 300 of file Thread.hpp.

Referenced by getStopTimeout(), and setLockTimeoutPeriodFactor().

int RTT::os::Thread::maxOverRun
protected

The maximum times a periodic overrun may happen, or -1 if unlimited.

Definition at line 347 of file Thread.hpp.

Referenced by getMaxOverrun(), RTT::Activity::loop(), setMaxOverrun(), and RTT::os::thread_function().

int RTT::os::Thread::msched_type
protected

Desired scheduler type.

Definition at line 305 of file Thread.hpp.

Referenced by getScheduler(), setScheduler(), Thread(), and RTT::os::thread_function().

NANO_TIME RTT::os::Thread::period
protected

The period as it is passed to the operating system.

Definition at line 352 of file Thread.hpp.

Referenced by getPeriod(), getPeriodNS(), getScheduler(), getStopTimeout(), isPeriodic(), setPeriod(), start(), stop(), and RTT::os::thread_function().

bool RTT::os::Thread::prepareForExit
protected

Signal the thread that it should exit.

Definition at line 316 of file Thread.hpp.

Referenced by terminate(), and RTT::os::thread_function().

RTOS_TASK RTT::os::Thread::rtos_task
protected
bool RTT::os::Thread::running
protected

Indicates if step() or loop() should be executed.

Definition at line 326 of file Thread.hpp.

Referenced by emergencyStop(), isRunning(), start(), stop(), RTT::Activity::stop(), and RTT::os::thread_function().

rt_sem_t RTT::os::Thread::sem
protected

The semaphore used for starting the thread.

Definition at line 336 of file Thread.hpp.

Referenced by setPeriod(), setScheduler(), start(), terminate(), Thread(), RTT::os::thread_function(), and ~Thread().

double RTT::os::Thread::stopTimeout
protected

The timeout, in seconds, for stop()

Definition at line 357 of file Thread.hpp.

Referenced by getStopTimeout(), and setStopTimeout().

int RTT::os::ThreadInterface::threadnb
protectedinherited

Threads are given an unique number, which follows thread creation order.

See also
os::threads

Definition at line 229 of file ThreadInterface.hpp.

Referenced by RTT::os::ThreadInterface::ThreadInterface().


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