Public Member Functions | Static Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | Friends
RTT::os::Thread Class Reference

#include <Thread.hpp>

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

List of all members.

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

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

Private Member Functions

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

Private 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

Static Private 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

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

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

Definition at line 324 of file Thread.cpp.

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

Member Function Documentation

bool RTT::os::Thread::breakLoop ( ) [protected, virtual]
void RTT::os::Thread::configure ( ) [private]

Do configuration actions when the thread is stopped.

Definition at line 492 of file Thread.cpp.

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

Definition at line 225 of file Thread.cpp.

void RTT::os::Thread::finalize ( ) [protected, virtual]
unsigned RTT::os::Thread::getCpuAffinity ( ) const [virtual]
Returns:
the cpu affinity (
See also:
rtos_task_set_cpu_affinity)

Reimplemented in RTT::Activity.

Definition at line 605 of file Thread.cpp.

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

Implements RTT::os::ThreadInterface.

Definition at line 641 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 631 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 569 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 590 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 595 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 610 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 585 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 487 of file Thread.cpp.

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

virtual RTOS_TASK* RTT::os::Thread::getTask ( ) [inline, virtual]

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 204 of file Thread.hpp.

virtual const RTOS_TASK* RTT::os::Thread::getTask ( ) const [inline, virtual]

const version of the above.

Implements RTT::os::ThreadInterface.

Definition at line 209 of file Thread.hpp.

bool RTT::os::Thread::initialize ( ) [protected, virtual]
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 463 of file Thread.cpp.

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

Reimplemented in RTT::Activity.

Definition at line 580 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 458 of file Thread.cpp.

void RTT::os::Thread::loop ( ) [protected, virtual]
bool RTT::os::Thread::setCpuAffinity ( unsigned  cpu_affinity) [virtual]

Set cpu affinity for this thread The 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 600 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 70 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 72 of file Thread.cpp.

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

Implements RTT::os::ThreadInterface.

Definition at line 636 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.

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

Definition at line 535 of file Thread.cpp.

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

Set the periodicity of this thread (seconds, nanoseconds)

Definition at line 541 of file Thread.cpp.

Set the periodicity of this thread

Definition at line 564 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 575 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 468 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 68 of file Thread.cpp.

Sets the timeout for stop(), in seconds

See also:
getStopTimeout

Definition at line 402 of file Thread.cpp.

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

Definition at line 249 of file Thread.cpp.

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

Set the wait policy of a periodic thread

Parameters:
Thewait policy between ORO_WAIT_ABS (absolute wait) and ORO_WAIT_REL (relative wait)

Implements RTT::os::ThreadInterface.

Definition at line 646 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 337 of file Thread.cpp.

void RTT::os::Thread::step ( ) [protected, virtual]
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 416 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 620 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 615 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 74 of file Thread.cpp.


Member Data Documentation

bool RTT::os::Thread::active [private]

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

Definition at line 308 of file Thread.hpp.

Used to implement synchronising breakLoop().

Definition at line 338 of file Thread.hpp.

unsigned int RTT::os::Thread::default_stack_size = 0 [static, private]

Definition at line 287 of file Thread.hpp.

bool RTT::os::Thread::inloop [private]

Is true when in the loop (isRunning() )

Definition at line 318 of file Thread.hpp.

double RTT::os::Thread::lock_timeout_no_period_in_s = 1.0 [static, private]

configuration of the lock timeout in seconds

Definition at line 292 of file Thread.hpp.

double RTT::os::Thread::lock_timeout_period_factor = 10.0 [static, private]

configuration of the lock timeout for periodic tasks in seconds

Definition at line 297 of file Thread.hpp.

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

Definition at line 344 of file Thread.hpp.

Desired scheduler type.

Definition at line 302 of file Thread.hpp.

The period as it is passed to the operating system.

Definition at line 349 of file Thread.hpp.

Signal the thread that it should exit.

Definition at line 313 of file Thread.hpp.

The realtime task structure created by this object.

Definition at line 328 of file Thread.hpp.

bool RTT::os::Thread::running [private]

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

Definition at line 323 of file Thread.hpp.

The semaphore used for starting the thread.

Definition at line 333 of file Thread.hpp.

double RTT::os::Thread::stopTimeout [private]

The timeout, in seconds, for stop()

Definition at line 354 of file Thread.hpp.


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


rtt
Author(s): RTT Developers
autogenerated on Fri Sep 9 2016 04:02:20