Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Private Member Functions | Friends | List of all members
RTT::os::Thread Class Reference

#include <Thread.hpp>

Inheritance diagram for RTT::os::Thread:
Inheritance graph
[legend]

Public Member Functions

virtual unsigned getCpuAffinity () const
 
virtual int getMaxOverrun () const
 
virtual const char * getName () const
 
void getPeriod (secs &s, nsecs &ns) const
 
virtual Seconds getPeriod () const
 
virtual nsecs getPeriodNS () const
 
virtual unsigned int getPid () const
 
virtual int getPriority () const
 
virtual int getScheduler () const
 
Seconds getStopTimeout () const
 
virtual RTOS_TASKgetTask ()
 
virtual const RTOS_TASKgetTask () const
 
virtual bool isActive () const
 
virtual bool isPeriodic () const
 
virtual bool isRunning () const
 
virtual bool setCpuAffinity (unsigned cpu_affinity)
 
virtual void setMaxOverrun (int m)
 
bool setPeriod (Seconds s)
 
bool setPeriod (secs s, nsecs ns)
 
bool setPeriod (TIME_SPEC p)
 
virtual bool setPriority (int priority)
 
virtual bool setScheduler (int sched_type)
 
void setStopTimeout (Seconds s)
 
virtual void setWaitPeriodPolicy (int p)
 
virtual bool start ()
 
virtual bool stop ()
 
 Thread (int scheduler, int priority, double period, unsigned cpu_affinity, const std::string &name)
 
virtual void yield ()
 
virtual ~Thread ()
 
- Public Member Functions inherited from RTT::os::ThreadInterface
bool isSelf () const
 
 ThreadInterface ()
 
unsigned int threadNumber () const
 
virtual ~ThreadInterface ()
 

Static Public Member Functions

static void setLockTimeoutNoPeriod (double timeout_in_s)
 
static void setLockTimeoutPeriodFactor (double factor)
 
static void setStackSize (unsigned int ssize)
 

Protected Member Functions

virtual bool breakLoop ()
 
void emergencyStop ()
 
virtual void finalize ()
 
virtual bool initialize ()
 
virtual void loop ()
 
virtual void step ()
 
void terminate ()
 

Protected Attributes

bool active
 
MutexRecursive breaker
 
bool inloop
 
int maxOverRun
 
int msched_type
 
NANO_TIME period
 
bool prepareForExit
 
RTOS_TASK rtos_task
 
bool running
 
rt_sem_t sem
 
double stopTimeout
 
- Protected Attributes inherited from RTT::os::ThreadInterface
int threadnb
 

Static Protected Attributes

static unsigned int default_stack_size = 0
 
static double lock_timeout_no_period_in_s = 1.0
 
static double lock_timeout_period_factor = 10.0
 

Private Member Functions

void configure ()
 
void setup (int _priority, unsigned cpu_affinity, const std::string &name)
 
 Thread (const Thread &)
 

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 245 of file Thread.cpp.

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

Definition at line 334 of file Thread.cpp.

RTT::os::Thread::Thread ( const Thread )
private

Member Function Documentation

bool RTT::os::Thread::breakLoop ( )
protectedvirtual
void RTT::os::Thread::configure ( )
private

Do configuration actions when the thread is stopped.

Definition at line 500 of file Thread.cpp.

void RTT::os::Thread::emergencyStop ( )
protected

Definition at line 235 of file Thread.cpp.

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 613 of file Thread.cpp.

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

Implements RTT::os::ThreadInterface.

Definition at line 655 of file Thread.cpp.

const char * RTT::os::Thread::getName ( ) const
virtual

Read the name of this task

Implements RTT::os::ThreadInterface.

Definition at line 645 of file Thread.cpp.

void RTT::os::Thread::getPeriod ( secs s,
nsecs ns 
) const

Get the periodicity of this thread (seconds, nanoseconds)

Definition at line 577 of file Thread.cpp.

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 598 of file Thread.cpp.

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

Get the periodicity in nanoseconds. Return zero if non periodic.

Implements RTT::os::ThreadInterface.

Definition at line 603 of file Thread.cpp.

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 618 of file Thread.cpp.

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 593 of file Thread.cpp.

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 495 of file Thread.cpp.

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 415 of file Thread.cpp.

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.

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 471 of file Thread.cpp.

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

Reimplemented in RTT::Activity.

Definition at line 588 of file Thread.cpp.

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 466 of file Thread.cpp.

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 608 of file Thread.cpp.

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 78 of file Thread.cpp.

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 80 of file Thread.cpp.

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

Implements RTT::os::ThreadInterface.

Definition at line 650 of file Thread.cpp.

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 543 of file Thread.cpp.

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

Set the periodicity of this thread (seconds, nanoseconds)

Definition at line 549 of file Thread.cpp.

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

Set the periodicity of this thread

Definition at line 572 of file Thread.cpp.

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 583 of file Thread.cpp.

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 476 of file Thread.cpp.

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 76 of file Thread.cpp.

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

Sets the timeout for stop(), in seconds

See also
getStopTimeout

Definition at line 410 of file Thread.cpp.

void RTT::os::Thread::setup ( int  _priority,
unsigned  cpu_affinity,
const std::string &  name 
)
private

Definition at line 259 of file Thread.cpp.

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 660 of file Thread.cpp.

bool RTT::os::Thread::start ( )
virtual

Start the Thread.

Postcondition
initialize() is called first
The Thread is running
Returns
true if the function did succeed. false otherwise.

Implements RTT::os::ThreadInterface.

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

Definition at line 345 of file Thread.cpp.

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

Stop the Thread.

Postcondition
The Thread is no longer being run
finalize() is called when the Thread is stopped.
Returns
true if the function did succeed. false otherwise.

Implements RTT::os::ThreadInterface.

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

Definition at line 424 of file Thread.cpp.

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 628 of file Thread.cpp.

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 623 of file Thread.cpp.

Friends And Related Function Documentation

void* thread_function ( void *  t)
friend

This is one time initialisation

The real task starts here.

Definition at line 82 of file Thread.cpp.

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.

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

Used to implement synchronising breakLoop().

Definition at line 341 of file Thread.hpp.

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

Definition at line 290 of file Thread.hpp.

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

Is true when in the loop (isRunning() )

Definition at line 321 of file Thread.hpp.

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.

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.

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.

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

Desired scheduler type.

Definition at line 305 of file Thread.hpp.

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.

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

Signal the thread that it should exit.

Definition at line 316 of file Thread.hpp.

RTOS_TASK RTT::os::Thread::rtos_task
protected

The realtime task structure created by this object.

Definition at line 331 of file Thread.hpp.

bool RTT::os::Thread::running
protected

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

Definition at line 326 of file Thread.hpp.

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

The semaphore used for starting the thread.

Definition at line 336 of file Thread.hpp.

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

The timeout, in seconds, for stop()

Definition at line 357 of file Thread.hpp.


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


rtt
Author(s): RTT Developers
autogenerated on Tue Jun 25 2019 19:33:46