distortos  v0.7.0
object-oriented C++ RTOS for microcontrollers
Threads

Threads-related API of distortos. More...

Classes

class  distortos::DynamicThread
 DynamicThread class is a type-erased interface for thread that has dynamic storage for bound function, stack and internal DynamicSignalsReceiver object. More...
 
struct  distortos::DynamicThreadParameters
 DynamicThreadParameters struct is a helper with parameters for DynamicThread's constructor. More...
 
class  distortos::StaticThread< StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args >
 StaticThread class is a templated interface for thread that has automatic storage for stack. More...
 
class  distortos::StaticThread< StackSize, true, QueuedSignals, SignalActions, Function, Args... >
 StaticThread class is a templated interface for thread that has automatic storage for stack and internal StaticSignalsReceiver object. More...
 
class  distortos::Thread
 Thread class is a pure abstract interface for threads. More...
 
class  distortos::ThreadIdentifier
 ThreadIdentifier class is an identifier of thread. More...
 
class  distortos::UndetachableThread
 UndetachableThread class is a ThreadCommon that cannot be detached. More...
 

Enumerations

enum  distortos::SchedulingPolicy : uint8_t { distortos::SchedulingPolicy::fifo, distortos::SchedulingPolicy::roundRobin }
 scheduling policy of the thread More...
 
enum  distortos::ThreadState : uint8_t {
  distortos::ThreadState::created, distortos::ThreadState::runnable, distortos::ThreadState::terminated, distortos::ThreadState::sleeping,
  distortos::ThreadState::blockedOnSemaphore, distortos::ThreadState::suspended, distortos::ThreadState::blockedOnMutex, distortos::ThreadState::blockedOnConditionVariable,
  distortos::ThreadState::waitingForSignal, distortos::ThreadState::detached
}
 state of the thread More...
 

Functions

template<typename Function , typename... Args>
DynamicThread distortos::makeDynamicThread (const size_t stackSize, const bool canReceiveSignals, const size_t queuedSignals, const size_t signalActions, const uint8_t priority, const SchedulingPolicy schedulingPolicy, Function &&function, Args &&... args)
 Helper factory function to make DynamicThread object. More...
 
template<typename Function , typename... Args>
DynamicThread distortos::makeDynamicThread (const DynamicThreadParameters parameters, Function &&function, Args &&... args)
 Helper factory function to make DynamicThread object. More...
 
template<typename Function , typename... Args>
DynamicThread distortos::makeAndStartDynamicThread (const size_t stackSize, const bool canReceiveSignals, const size_t queuedSignals, const size_t signalActions, const uint8_t priority, const SchedulingPolicy schedulingPolicy, Function &&function, Args &&... args)
 Helper factory function to make and start DynamicThread object. More...
 
template<typename Function , typename... Args>
DynamicThread distortos::makeAndStartDynamicThread (const DynamicThreadParameters parameters, Function &&function, Args &&... args)
 Helper factory function to make and start DynamicThread object. More...
 
template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread< StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args... > distortos::makeStaticThread (const uint8_t priority, const SchedulingPolicy schedulingPolicy, Function &&function, Args &&... args)
 Helper factory function to make StaticThread object with partially deduced template arguments. More...
 
template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread< StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args... > distortos::makeStaticThread (const uint8_t priority, Function &&function, Args &&... args)
 Helper factory function to make StaticThread object with partially deduced template arguments. More...
 
template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread< StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args... > distortos::makeAndStartStaticThread (const uint8_t priority, const SchedulingPolicy schedulingPolicy, Function &&function, Args &&... args)
 Helper factory function to make and start StaticThread object with partially deduced template arguments. More...
 
template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread< StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args... > distortos::makeAndStartStaticThread (const uint8_t priority, Function &&function, Args &&... args)
 Helper factory function to make and start StaticThread object with partially deduced template arguments. More...
 
int distortos::ThisThread::detach ()
 Detaches calling (current) thread. More...
 
void distortos::ThisThread::exit ()
 Exits calling (current) thread. More...
 
Threaddistortos::ThisThread::get ()
 
uint8_t distortos::ThisThread::getEffectivePriority ()
 
ThreadIdentifier distortos::ThisThread::getIdentifier ()
 
uint8_t distortos::ThisThread::getPriority ()
 
SchedulingPolicy distortos::ThisThread::getSchedulingPolicy ()
 
size_t distortos::ThisThread::getStackHighWaterMark ()
 
size_t distortos::ThisThread::getStackSize ()
 
void distortos::ThisThread::setPriority (const uint8_t priority, const bool alwaysBehind)
 
void distortos::ThisThread::setSchedulingPolicy (const SchedulingPolicy schedulingPolicy)
 
int distortos::ThisThread::sleepFor (TickClock::duration duration)
 Makes the calling (current) thread sleep for at least given duration. More...
 
template<typename Rep , typename Period >
int distortos::ThisThread::sleepFor (const std::chrono::duration< Rep, Period > duration)
 Makes the calling (current) thread sleep for at least given duration. More...
 
int distortos::ThisThread::sleepUntil (TickClock::time_point timePoint)
 Makes the calling (current) thread sleep until some time point is reached. More...
 
template<typename Duration >
int distortos::ThisThread::sleepUntil (const std::chrono::time_point< TickClock, Duration > timePoint)
 Makes the calling (current) thread sleep until some time point is reached. More...
 
void distortos::ThisThread::yield ()
 Yields time slot of the scheduler to next thread. More...
 

Detailed Description

Threads-related API of distortos.

Enumeration Type Documentation

◆ SchedulingPolicy

enum distortos::SchedulingPolicy : uint8_t
strong

scheduling policy of the thread

Enumerator
fifo 

FIFO scheduling policy.

roundRobin 

round-robin scheduling policy

◆ ThreadState

enum distortos::ThreadState : uint8_t
strong

state of the thread

Enumerator
created 

state in which thread is created, before being added to Scheduler

runnable 

thread is runnable

terminated 

thread is terminated

sleeping 

thread is sleeping

blockedOnSemaphore 

thread is blocked on Semaphore

suspended 

thread is suspended

blockedOnMutex 

thread is blocked on Mutex

blockedOnConditionVariable 

thread is blocked on ConditionVariable

waitingForSignal 

thread is waiting for signal

detached 

internal thread object was detached

Function Documentation

◆ detach()

int distortos::ThisThread::detach ( )

Detaches calling (current) thread.

Similar to std::thread::detach() - http://en.cppreference.com/w/cpp/thread/thread/detach Similar to POSIX pthread_detach() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_detach.html

Detaches calling (current) thread from its Thread object, allowing execution to continue independently. All resources allocated for the thread will be deallocated when the thread terminates.

Warning
This function must not be called from interrupt context!
Returns
0 on success, error code otherwise:
  • EINVAL - current thread is already detached;
  • ENOTSUP - current thread cannot be detached;
Here is the call graph for this function:

◆ exit()

void distortos::ThisThread::exit ( )

Exits calling (current) thread.

Similar to POSIX pthread_exit() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_exit.html

Warning
This function must not be called from interrupt context!
Here is the call graph for this function:

◆ get()

Thread & distortos::ThisThread::get ( )
Warning
This function must not be called from interrupt context!
Returns
reference to Thread object of currently active thread
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getEffectivePriority()

uint8_t distortos::ThisThread::getEffectivePriority ( )
Warning
This function must not be called from interrupt context!
Returns
effective priority of calling (current) thread
Here is the call graph for this function:

◆ getIdentifier()

ThreadIdentifier distortos::ThisThread::getIdentifier ( )
Warning
This function must not be called from interrupt context!
Returns
thread identifier of calling (current) thread
Here is the call graph for this function:

◆ getPriority()

uint8_t distortos::ThisThread::getPriority ( )
Warning
This function must not be called from interrupt context!
Returns
priority of calling (current) thread
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getSchedulingPolicy()

SchedulingPolicy distortos::ThisThread::getSchedulingPolicy ( )
Returns
scheduling policy of calling (current) thread
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getStackHighWaterMark()

size_t distortos::ThisThread::getStackHighWaterMark ( )
Warning
This function must not be called from interrupt context!
Returns
"high water mark" (max usage) of thread's stack, bytes
Here is the call graph for this function:

◆ getStackSize()

size_t distortos::ThisThread::getStackSize ( )
Warning
This function must not be called from interrupt context!
Returns
size of calling (current) thread's stack, bytes
Here is the call graph for this function:

◆ makeAndStartDynamicThread() [1/2]

template<typename Function , typename... Args>
DynamicThread distortos::makeAndStartDynamicThread ( const size_t  stackSize,
const bool  canReceiveSignals,
const size_t  queuedSignals,
const size_t  signalActions,
const uint8_t  priority,
const SchedulingPolicy  schedulingPolicy,
Function &&  function,
Args &&...  args 
)

Helper factory function to make and start DynamicThread object.

Template Parameters
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]stackSizeis the size of stack, bytes
[in]canReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
[in]queuedSignalsis the max number of queued signals for this thread, relevant only if canReceiveSignals == true, 0 to disable queuing of signals for this thread
[in]signalActionsis the max number of different SignalAction objects for this thread, relevant only if canReceiveSignals == true, 0 to disable catching of signals for this thread
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]schedulingPolicyis the scheduling policy of the thread
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
DynamicThread object
Here is the call graph for this function:

◆ makeAndStartDynamicThread() [2/2]

template<typename Function , typename... Args>
DynamicThread distortos::makeAndStartDynamicThread ( const DynamicThreadParameters  parameters,
Function &&  function,
Args &&...  args 
)

Helper factory function to make and start DynamicThread object.

Template Parameters
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]parametersis a DynamicThreadParameters struct with thread parameters
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
DynamicThread object
Here is the call graph for this function:

◆ makeAndStartStaticThread() [1/2]

template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread<StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args...> distortos::makeAndStartStaticThread ( const uint8_t  priority,
const SchedulingPolicy  schedulingPolicy,
Function &&  function,
Args &&...  args 
)

Helper factory function to make and start StaticThread object with partially deduced template arguments.

Template Parameters
StackSizeis the size of stack, bytes
CanReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
QueuedSignalsis the max number of queued signals for this thread, relevant only if CanReceiveSignals == true, 0 to disable queuing of signals for this thread
SignalActionsis the max number of different SignalAction objects for this thread, relevant only if CanReceiveSignals == true, 0 to disable catching of signals for this thread
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]schedulingPolicyis the scheduling policy of the thread
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
StaticThread object with partially deduced template arguments

◆ makeAndStartStaticThread() [2/2]

template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread<StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args...> distortos::makeAndStartStaticThread ( const uint8_t  priority,
Function &&  function,
Args &&...  args 
)

Helper factory function to make and start StaticThread object with partially deduced template arguments.

Template Parameters
StackSizeis the size of stack, bytes
CanReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
QueuedSignalsis the max number of queued signals for this thread, relevant only if CanReceiveSignals == true, 0 to disable queuing of signals for this thread
SignalActionsis the max number of different SignalAction objects for this thread, relevant only if CanReceiveSignals == true, 0 to disable catching of signals for this thread
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
StaticThread object with partially deduced template arguments

◆ makeDynamicThread() [1/2]

template<typename Function , typename... Args>
DynamicThread distortos::makeDynamicThread ( const size_t  stackSize,
const bool  canReceiveSignals,
const size_t  queuedSignals,
const size_t  signalActions,
const uint8_t  priority,
const SchedulingPolicy  schedulingPolicy,
Function &&  function,
Args &&...  args 
)

Helper factory function to make DynamicThread object.

Template Parameters
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]stackSizeis the size of stack, bytes
[in]canReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
[in]queuedSignalsis the max number of queued signals for this thread, relevant only if canReceiveSignals == true, 0 to disable queuing of signals for this thread
[in]signalActionsis the max number of different SignalAction objects for this thread, relevant only if canReceiveSignals == true, 0 to disable catching of signals for this thread
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]schedulingPolicyis the scheduling policy of the thread
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
DynamicThread object
Here is the caller graph for this function:

◆ makeDynamicThread() [2/2]

template<typename Function , typename... Args>
DynamicThread distortos::makeDynamicThread ( const DynamicThreadParameters  parameters,
Function &&  function,
Args &&...  args 
)

Helper factory function to make DynamicThread object.

Template Parameters
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]parametersis a DynamicThreadParameters struct with thread parameters
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
DynamicThread object

◆ makeStaticThread() [1/2]

template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread<StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args...> distortos::makeStaticThread ( const uint8_t  priority,
const SchedulingPolicy  schedulingPolicy,
Function &&  function,
Args &&...  args 
)

Helper factory function to make StaticThread object with partially deduced template arguments.

Template Parameters
StackSizeis the size of stack, bytes
CanReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
QueuedSignalsis the max number of queued signals for this thread, relevant only if CanReceiveSignals == true, 0 to disable queuing of signals for this thread
SignalActionsis the max number of different SignalAction objects for this thread, relevant only if CanReceiveSignals == true, 0 to disable catching of signals for this thread
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]schedulingPolicyis the scheduling policy of the thread
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
StaticThread object with partially deduced template arguments

◆ makeStaticThread() [2/2]

template<size_t StackSize, bool CanReceiveSignals = {}, size_t QueuedSignals = {}, size_t SignalActions = {}, typename Function , typename... Args>
StaticThread<StackSize, CanReceiveSignals, QueuedSignals, SignalActions, Function, Args...> distortos::makeStaticThread ( const uint8_t  priority,
Function &&  function,
Args &&...  args 
)

Helper factory function to make StaticThread object with partially deduced template arguments.

Template Parameters
StackSizeis the size of stack, bytes
CanReceiveSignalsselects whether reception of signals is enabled (true) or disabled (false) for this thread
QueuedSignalsis the max number of queued signals for this thread, relevant only if CanReceiveSignals == true, 0 to disable queuing of signals for this thread
SignalActionsis the max number of different SignalAction objects for this thread, relevant only if CanReceiveSignals == true, 0 to disable catching of signals for this thread
Functionis the function that will be executed
Argsare the arguments for Function
Parameters
[in]priorityis the thread's priority, 0 - lowest, UINT8_MAX - highest
[in]functionis a function that will be executed in separate thread
[in]argsare arguments for function
Returns
StaticThread object with partially deduced template arguments

◆ setPriority()

void distortos::ThisThread::setPriority ( uint8_t  priority,
bool  alwaysBehind = {} 
)

Changes priority of calling (current) thread.

Warning
This function must not be called from interrupt context!
Parameters
[in]priorityis the new priority for thread
[in]alwaysBehindselects the method of ordering when lowering the priority
  • false - the thread is moved to the head of the group of threads with the new priority (default),
  • true - the thread is moved to the tail of the group of threads with the new priority.
Here is the call graph for this function:

◆ setSchedulingPolicy()

void distortos::ThisThread::setSchedulingPolicy ( SchedulingPolicy  schedulingPolicy)

param [in] schedulingPolicy is the new scheduling policy of calling (current) thread

Here is the call graph for this function:

◆ sleepFor() [1/2]

int distortos::ThisThread::sleepFor ( TickClock::duration  duration)

Makes the calling (current) thread sleep for at least given duration.

Current thread's state is changed to "sleeping".

Note
To fulfill the "at least" requirement, one additional tick is always added to the sleep duration.
Warning
This function must not be called from interrupt context!
Parameters
[in]durationis the duration after which the thread will be woken
Returns
0 on success, error code otherwise:
  • EINTR - the sleep was interrupted by an unmasked, caught signal;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ sleepFor() [2/2]

template<typename Rep , typename Period >
int distortos::ThisThread::sleepFor ( const std::chrono::duration< Rep, Period >  duration)

Makes the calling (current) thread sleep for at least given duration.

Current thread's state is changed to "sleeping".

Note
To fulfill the "at least" requirement, one additional tick is always added to the sleep duration.
Warning
This function must not be called from interrupt context!
Template Parameters
Repis type of tick counter
Periodis std::ratio type representing the tick period of the clock, seconds
Parameters
[in]durationis the duration after which the thread will be woken
Returns
0 on success, error code otherwise:
  • EINTR - the sleep was interrupted by an unmasked, caught signal;
Here is the call graph for this function:

◆ sleepUntil() [1/2]

int distortos::ThisThread::sleepUntil ( TickClock::time_point  timePoint)

Makes the calling (current) thread sleep until some time point is reached.

Current thread's state is changed to "sleeping".

Warning
This function must not be called from interrupt context!
Parameters
[in]timePointis the time point at which the thread will be woken
Returns
0 on success, error code otherwise:
  • EINTR - the sleep was interrupted by an unmasked, caught signal;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ sleepUntil() [2/2]

template<typename Duration >
int distortos::ThisThread::sleepUntil ( const std::chrono::time_point< TickClock, Duration >  timePoint)

Makes the calling (current) thread sleep until some time point is reached.

Current thread's state is changed to "sleeping".

Warning
This function must not be called from interrupt context!
Template Parameters
Durationis a std::chrono::duration type used to measure duration
Parameters
[in]timePointis the time point at which the thread will be woken
Returns
0 on success, error code otherwise:
  • EINTR - the sleep was interrupted by an unmasked, caught signal;
Here is the call graph for this function:

◆ yield()

void distortos::ThisThread::yield ( )

Yields time slot of the scheduler to next thread.

Warning
This function must not be called from interrupt context!
Here is the call graph for this function: