Semaphore is the basic synchronization primitive. More...

#include "distortos/Semaphore.hpp"

Collaboration diagram for distortos::Semaphore:

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's constructor. More...

	~Semaphore ()=default
	Semaphore's destructor. More...

Value	getMaxValue () const

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 Semaphore &	operator= (const Semaphore &)=delete

Semaphore &	operator= (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.

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's constructor.

Parameters

[in]	value	is the initial value of the semaphore, if this value is greater than maxValue, it will be truncated
[in]	maxValue	is the max value of the semaphore before post() returns EOVERFLOW, default - max for Value type

◆ ~Semaphore()

distortos::Semaphore::~Semaphore ( )

default

Semaphore's destructor.

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

◆ getMaxValue()

Value distortos::Semaphore::getMaxValue ( ) const

inline

Returns: max value of the semaphore

Here is the caller graph for this function:

◆ getValue()

Value distortos::Semaphore::getValue ( ) const

inline

Gets current value of semaphore.

Returns: current value of semaphore, positive value if semaphore is not locked, 0 otherwise

◆ post()

int distortos::Semaphore::post ( )

Unlocks the semaphore.

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.

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.

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] duration is 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

Rep	is type of tick counter
Period	is std::ratio type representing the tick period of the clock, seconds

Parameters

[in] duration is 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.

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] timePoint is 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

Duration is a std::chrono::duration type used to measure duration

Parameters

[in] timePoint is 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.

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:

include/distortos/Semaphore.hpp
source/synchronization/Semaphore.cpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Value

Constructor & Destructor Documentation

◆ Semaphore()

◆ ~Semaphore()

Member Function Documentation

◆ getMaxValue()

◆ getValue()

◆ post()

◆ tryWait()

◆ tryWaitFor() [1/2]

◆ tryWaitFor() [2/2]

◆ tryWaitInternal()

◆ tryWaitUntil() [1/2]

◆ tryWaitUntil() [2/2]

◆ wait()

Member Data Documentation

◆ blockedList_

◆ maxValue_

◆ value_