distortos  v0.5.0
object-oriented C++ RTOS for microcontrollers
distortos::Semaphore Class Reference

Semaphore is the basic synchronization primitive. More...

#include <Semaphore.hpp>

Collaboration diagram for distortos::Semaphore:
[legend]

Public Types

using Value = unsigned int
 type used for semaphore's "value" More...
 

Public Member Functions

constexpr Semaphore (const Value value, const Value maxValue=std::numeric_limits< Value >::max())
 Semaphore constructor. More...
 
 ~Semaphore ()
 Semaphore destructor. More...
 
Value getValue () const
 Gets current value of semaphore. More...
 
int post ()
 Unlocks the semaphore. More...
 
int tryWait ()
 Tries to lock the semaphore. More...
 
int tryWaitFor (TickClock::duration duration)
 Tries to lock the semaphore for given duration of time. More...
 
template<typename Rep , typename Period >
int tryWaitFor (const std::chrono::duration< Rep, Period > duration)
 Tries to lock the semaphore for given duration of time. More...
 
int tryWaitUntil (TickClock::time_point timePoint)
 Tries to lock the semaphore until given time point. More...
 
template<typename Duration >
int tryWaitUntil (const std::chrono::time_point< TickClock, Duration > timePoint)
 Tries to lock the semaphore until given time point. More...
 
int wait ()
 Locks the semaphore. More...
 
 Semaphore (const Semaphore &)=delete
 
 Semaphore (Semaphore &&)=default
 
const Semaphoreoperator= (const Semaphore &)=delete
 
Semaphoreoperator= (Semaphore &&)=delete
 

Private Member Functions

int tryWaitInternal ()
 Internal version of tryWait(). More...
 

Private Attributes

internal::ThreadList blockedList_
 ThreadControlBlock objects blocked on this semaphore. More...
 
Value value_
 internal value of the semaphore More...
 
Value maxValue_
 max value of the semaphore More...
 

Detailed Description

Semaphore is the basic synchronization primitive.

Similar to POSIX semaphores - http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_16

Member Typedef Documentation

◆ Value

using distortos::Semaphore::Value = unsigned int

type used for semaphore's "value"

Constructor & Destructor Documentation

◆ Semaphore()

constexpr distortos::Semaphore::Semaphore ( const Value  value,
const Value  maxValue = std::numeric_limits<Value>::max() 
)
inlineexplicit

Semaphore constructor.

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

Parameters
[in]valueis the initial value of the semaphore, if this value is greater than maxValue, it will be truncated
[in]maxValueis the max value of the semaphore before post() returns EOVERFLOW, default - max for Value type
Here is the caller graph for this function:

◆ ~Semaphore()

distortos::Semaphore::~Semaphore ( )
inline

Semaphore destructor.

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

It is safe to destroy a semaphore upon which no threads are currently blocked. The effect of destroying a semaphore upon which other threads are currently blocked is system error.

Member Function Documentation

◆ getValue()

Value distortos::Semaphore::getValue ( ) const
inline

Gets current value of semaphore.

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

Returns
current value of semaphore, positive value if semaphore is not locked, 0 otherwise
Here is the call graph for this function:
Here is the caller graph for this function:

◆ post()

int distortos::Semaphore::post ( )

Unlocks the semaphore.

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

This function shall unlock the semaphore by performing a semaphore unlock operation. If the semaphore value resulting from this operation is positive, then no threads were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented. Otherwise one of the threads blocked waiting for the semaphore shall be allowed to return successfully from its call to lock() - the highest priority waiting thread shall be unblocked, and if there is more than one highest priority thread blocked waiting for the semaphore, then the highest priority thread that has been waiting the longest shall be unblocked.

Returns
0 if the calling process successfully "posted" the semaphore, error code otherwise:
  • EOVERFLOW - the maximum allowable value for a semaphore would be exceeded;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryWait()

int distortos::Semaphore::tryWait ( )

Tries to lock the semaphore.

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

This function shall lock the semaphore only if the semaphore is currently not locked; that is, if the semaphore value is currently positive. Otherwise, it shall not lock the semaphore. Upon successful return, the state of the semaphore shall be locked and shall remain locked until unlock() function is executed.

Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EAGAIN - semaphore was already locked, so it cannot be immediately locked by the tryWait() operation;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryWaitFor() [1/2]

int distortos::Semaphore::tryWaitFor ( TickClock::duration  duration)

Tries to lock the semaphore for given duration of time.

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

If the semaphore is already locked, the calling thread shall block until the semaphore becomes available as in wait() function. If the semaphore cannot be locked without waiting for another thread to unlock the semaphore, this wait shall be terminated when the specified timeout expires.

Under no circumstance shall the function fail with a timeout if the semaphore can be locked immediately. The validity of the duration parameter need not be checked if the semaphore can be locked immediately.

Warning
This function must not be called from interrupt context!
Parameters
[in]durationis the duration after which the wait will be terminated without locking the semaphore
Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EINTR - the wait was interrupted by an unmasked, caught signal;
  • ETIMEDOUT - the semaphore could not be locked before the specified timeout expired;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryWaitFor() [2/2]

template<typename Rep , typename Period >
int distortos::Semaphore::tryWaitFor ( const std::chrono::duration< Rep, Period >  duration)
inline

Tries to lock the semaphore for given duration of time.

Template variant of tryWaitFor(TickClock::duration 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 wait will be terminated without locking the semaphore
Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EINTR - the wait was interrupted by an unmasked, caught signal;
  • ETIMEDOUT - the semaphore could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ tryWaitInternal()

int distortos::Semaphore::tryWaitInternal ( )
private

Internal version of tryWait().

Internal version with no interrupt masking.

Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EAGAIN - semaphore was already locked, so it cannot be immediately locked by the tryWait() operation;
Here is the caller graph for this function:

◆ tryWaitUntil() [1/2]

int distortos::Semaphore::tryWaitUntil ( TickClock::time_point  timePoint)

Tries to lock the semaphore until given time point.

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

If the semaphore is already locked, the calling thread shall block until the semaphore becomes available as in wait() function. If the semaphore cannot be locked without waiting for another thread to unlock the semaphore, this wait shall be terminated when the specified timeout expires.

Under no circumstance shall the function fail with a timeout if the semaphore can be locked immediately. The validity of the timePoint parameter need not be checked if the semaphore can be locked immediately.

Warning
This function must not be called from interrupt context!
Parameters
[in]timePointis the time point at which the wait will be terminated without locking the semaphore
Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EINTR - the wait was interrupted by an unmasked, caught signal;
  • ETIMEDOUT - the semaphore could not be locked before the specified timeout expired;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryWaitUntil() [2/2]

template<typename Duration >
int distortos::Semaphore::tryWaitUntil ( const std::chrono::time_point< TickClock, Duration >  timePoint)
inline

Tries to lock the semaphore until given time point.

Template variant of tryWaitUntil(TickClock::time_point timePoint).

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 wait will be terminated without locking the semaphore
Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EINTR - the wait was interrupted by an unmasked, caught signal;
  • ETIMEDOUT - the semaphore could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ wait()

int distortos::Semaphore::wait ( )

Locks the semaphore.

Similar to sem_wait() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_trywait.html#

This function shall lock the semaphore by performing a semaphore lock operation on that semaphore. If the semaphore value is currently zero, then the calling thread shall not return from the call to lock() until it either locks the semaphore or the call is interrupted by a signal. Upon successful return, the state of the semaphore shall be locked and shall remain locked until unlock() function is executed.

Warning
This function must not be called from interrupt context!
Returns
0 if the calling process successfully performed the semaphore lock operation, error code otherwise:
  • EINTR - the wait was interrupted by an unmasked, caught signal;
Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ blockedList_

internal::ThreadList distortos::Semaphore::blockedList_
private

ThreadControlBlock objects blocked on this semaphore.

◆ maxValue_

Value distortos::Semaphore::maxValue_
private

max value of the semaphore

◆ value_

Value distortos::Semaphore::value_
private

internal value of the semaphore


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