Orocos Real-Time Toolkit
2.9.0
|
A Thread object executes user code in its own thread. More...
#include <rtt/os/Thread.hpp>
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_TASK * | getTask () |
Get the RTOS_TASK pointer. More... | |
virtual const RTOS_TASK * | getTask () 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) |
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.
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().
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.
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.
Definition at line 109 of file Thread.hpp.
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.
scheduler | The scheduler, one of ORO_SCHED_RT or ORO_SCHED_OTHER. |
priority | The priority of the thread, this is interpreted by your RTOS. |
period | The period in seconds (eg 0.001) of the thread, or zero if not periodic. |
cpu_affinity | The cpu affinity of the thread, this is interpreted by your RTOS. If 0, the new thread inherits the affinity of its creator (the default). |
name | The 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.
|
virtual |
Definition at line 325 of file Thread.cpp.
References RTT::Debug, getName(), isRunning(), rtos_sem_destroy(), sem, stop(), and terminate().
|
protectedvirtual |
Reimplemented in RTT::corba::OrbRunner, RTT::extras::FileDescriptorActivity, RTT::Activity, RTT::mqueue::Dispatcher, and RTT::corba::CorbaDispatcher.
Definition at line 521 of file Thread.cpp.
Referenced by stop().
|
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().
|
protectedvirtual |
Reimplemented in RTT::corba::OrbRunner, RTT::Activity, RTT::extras::TimerThread, and RTT::extras::SimulationThread.
Definition at line 532 of file Thread.cpp.
Referenced by emergencyStop(), and stop().
|
virtual |
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().
|
virtual |
Implements RTT::os::ThreadInterface.
Definition at line 643 of file Thread.cpp.
References maxOverRun.
|
virtual |
Read the name of this task.
Implements RTT::os::ThreadInterface.
Definition at line 633 of file Thread.cpp.
References rtos_task, and RTT::os::rtos_task_get_name().
Referenced by RTT::corba::CorbaDispatcher::initialize(), RTT::extras::SimulationThread::SimulationThread(), stop(), RTT::Activity::stop(), Thread(), RTT::os::thread_function(), and ~Thread().
Get the periodicity of this thread (seconds, nanoseconds)
Definition at line 570 of file Thread.cpp.
References period.
|
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().
|
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.
|
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().
|
virtual |
The priority of this Thread.
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().
|
virtual |
Get the scheduler policy in which this thread runs.
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().
|
inlinevirtual |
Get the RTOS_TASK pointer.
Implements RTT::os::ThreadInterface.
Definition at line 205 of file Thread.hpp.
Referenced by RTT::Activity::loop(), and RTT::os::thread_function().
|
inlinevirtual |
const version of the above.
Implements RTT::os::ThreadInterface.
Definition at line 210 of file Thread.hpp.
|
protectedvirtual |
Reimplemented in RTT::Activity, RTT::corba::CorbaDispatcher, RTT::mqueue::Dispatcher, RTT::extras::TimerThread, and RTT::extras::SimulationThread.
Definition at line 527 of file Thread.cpp.
Referenced by start().
|
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().
|
virtual |
Reimplemented in RTT::Activity.
Definition at line 581 of file Thread.cpp.
References period.
Referenced by RTT::Activity::isPeriodic().
|
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().
|
inherited |
Definition at line 58 of file ThreadInterface.cpp.
References RTT::os::ThreadInterface::getTask(), and RTT::os::rtos_task_is_self().
Referenced by RTT::ExecutionEngine::isSelf().
|
protectedvirtual |
Reimplemented in RTT::corba::OrbRunner, RTT::extras::FileDescriptorActivity, RTT::Activity, RTT::corba::CorbaDispatcher, and RTT::mqueue::Dispatcher.
Definition at line 516 of file Thread.cpp.
References step().
Referenced by RTT::os::thread_function().
|
virtual |
Set cpu affinity for this thread.
cpu_affinity | The cpu affinity of the thread ( |
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().
|
static |
Sets the lock timeout for a thread which does not have a period The default is 1 second.
timeout_in_s | the timeout is seconds |
Definition at line 71 of file Thread.cpp.
References lock_timeout_no_period_in_s.
|
static |
Set the lock timeout for a thread which has a period by a factor of the period The default is factor 10.
factor | Factor of the period |
Definition at line 73 of file Thread.cpp.
References lock_timeout_period_factor.
|
virtual |
Implements RTT::os::ThreadInterface.
Definition at line 638 of file Thread.cpp.
References maxOverRun.
|
virtual |
Set the periodicity in Seconds.
new_period | A positive number expressing the period |
Implements RTT::os::ThreadInterface.
Definition at line 536 of file Thread.cpp.
References RTT::Seconds_to_nsecs().
Referenced by RTT::Activity::Activity(), and setPeriod().
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().
|
virtual |
Set the priority of this Thread.
priority | The priority given upon construction of this thread. It has to be interpreted in the current OS scheduler. |
Implements RTT::os::ThreadInterface.
Definition at line 576 of file Thread.cpp.
References rtos_task, and RTT::os::rtos_task_set_priority().
|
virtual |
Change the scheduler policy in which this thread runs.
sched_type | An OS-specific value which selects a scheduler. Orocos requires that these two values are available:
|
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.
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().
|
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.
ssize | the 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.
Definition at line 403 of file Thread.cpp.
References stopTimeout.
|
virtual |
Set the wait policy of a periodic thread.
The | wait 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().
|
virtual |
Start the Thread.
Implements RTT::os::ThreadInterface.
Reimplemented in RTT::extras::FileDescriptorActivity, RTT::Activity, RTT::extras::IRQActivity, and RTT::extras::SimulationThread.
Definition at line 338 of file Thread.cpp.
References active, RTT::Critical, initialize(), isActive(), period, rtos_sem_signal(), rtos_sem_value(), rtos_task, RTT::os::rtos_task_make_periodic(), running, and sem.
Referenced by RTT::extras::SimulationThread::start(), RTT::Activity::start(), RTT::Activity::timeout(), and RTT::Activity::trigger().
|
protectedvirtual |
Reimplemented in RTT::extras::FileDescriptorActivity, RTT::Activity, RTT::extras::TimerThread, and RTT::extras::SimulationThread.
Definition at line 512 of file Thread.cpp.
Referenced by loop(), and RTT::os::thread_function().
|
virtual |
Stop the Thread.
Implements RTT::os::ThreadInterface.
Reimplemented in RTT::extras::FileDescriptorActivity, and RTT::Activity.
Definition at line 417 of file Thread.cpp.
References active, breaker, breakLoop(), RTT::Error, finalize(), getName(), getStopTimeout(), inloop, RTT::os::MutexTimedLock::isSuccessful(), period, rtos_task, RTT::os::rtos_task_make_periodic(), running, and RTT::Warning.
Referenced by RTT::extras::SimulationThread::step(), RTT::extras::SimulationThread::~SimulationThread(), ~Thread(), and RTT::extras::TimerThread::~TimerThread().
|
protected |
Exit and destroy the thread.
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().
|
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().
|
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().
|
friend |
This is one time initialisation
The real task starts here.
Definition at line 75 of file Thread.cpp.
Referenced by Thread().
|
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().
|
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().
|
staticprotected |
Definition at line 290 of file Thread.hpp.
Referenced by setStackSize(), and Thread().
|
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().
|
staticprotected |
configuration of the lock timeout in seconds
Definition at line 295 of file Thread.hpp.
Referenced by getStopTimeout(), and setLockTimeoutNoPeriod().
|
staticprotected |
configuration of the lock timeout for periodic tasks in seconds
Definition at line 300 of file Thread.hpp.
Referenced by getStopTimeout(), and setLockTimeoutPeriodFactor().
|
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().
|
protected |
Desired scheduler type.
Definition at line 305 of file Thread.hpp.
Referenced by getScheduler(), setScheduler(), Thread(), and RTT::os::thread_function().
|
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().
|
protected |
Signal the thread that it should exit.
Definition at line 316 of file Thread.hpp.
Referenced by terminate(), and RTT::os::thread_function().
|
protected |
The realtime task structure created by this object.
Definition at line 331 of file Thread.hpp.
Referenced by getCpuAffinity(), getName(), getPid(), getPriority(), getScheduler(), setCpuAffinity(), setPeriod(), setPriority(), setScheduler(), setWaitPeriodPolicy(), start(), stop(), RTT::Activity::stop(), terminate(), Thread(), and yield().
|
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().
|
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().
|
protected |
The timeout, in seconds, for stop()
Definition at line 357 of file Thread.hpp.
Referenced by getStopTimeout(), and setStopTimeout().
|
protectedinherited |
Threads are given an unique number, which follows thread creation order.
Definition at line 229 of file ThreadInterface.hpp.
Referenced by RTT::os::ThreadInterface::ThreadInterface().