iox::posix::Semaphore🔗

Posix semaphore C++ Wrapping class. More...

#include <iceoryx_hoofs/posix_wrapper/semaphore.hpp>

Inherits from DesignPattern::Creation< Semaphore, SemaphoreError >

Public Functions🔗

	Name
	Semaphore() Default constructor which creates an uninitialized semaphore. This semaphore object is unusable you need to reassign it with an object created by the semaphore factory methods.
	Semaphore(Semaphore && rhs) Move constructor.
Semaphore &	operator=(Semaphore && rhs) Move assignment operator.
	Semaphore(const Semaphore & ) We are denying Semaphore copy since it manages the semaphore resource and the underlying concept did not include copying.
Semaphore &	operator=(const Semaphore & ) We are denying Semaphore copy since it manages the semaphore resource and the underlying concept did not include copying.
	~Semaphore() Destructor.
cxx::expected< int, SemaphoreError >	getValue() const calls sem_getvalue which gets the value of a semaphore From the sem_getvalue manpage: sem_getvalue() places the current value of the semaphore pointed to sem into the integer pointed to by sval.
cxx::expected< SemaphoreError >	post() calls sem_post which unlocks a semaphore From the sem_post manpage: sem_post() increments (unlocks) the semaphore pointed to by sem. If the semaphore's value consequently becomes greater than zero, then another process or thread blocked in a sem_wait(3) call will be woken up and proceed to lock the semaphore.
cxx::expected< SemaphoreWaitState, SemaphoreError >	timedWait(const units::Duration abs_timeout) see wait()
cxx::expected< bool, SemaphoreError >	tryWait() see wait()
cxx::expected< SemaphoreError >	wait() calls sem_wait which locks a semaphore From the sem_wait manpage: sem_wait() decrements (locks) the semaphore pointed to by sem. If the semaphore's value is greater than zero, then the decrement proceeds, and the function returns, immediately. If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or a signal handler interrupts the call.

Friends🔗

	Name
class	DesignPattern::Creation< Semaphore, SemaphoreError >

Additional inherited members🔗

Public Types inherited from DesignPattern::Creation< Semaphore, SemaphoreError >

	Name
using Creation< DerivedClass, ErrorType >	CreationPattern_t
using iox::cxx::expected< DerivedClass, ErrorType >	result_t
using ErrorType	errorType_t

Public Functions inherited from DesignPattern::Creation< Semaphore, SemaphoreError >

	Name
template <typename... Targs> result_t	create(Targs &&... args) factory method which guarantees that either a working object is produced or an error value describing the error during construction
result_t	verify(DerivedClass && newObject) verifies if a class was created successfully
template <typename... Targs> iox::cxx::expected< ErrorType >	placementCreate(void *const memory, Targs &&... args) factory method which guarantees that either a working object is produced or an error value describing the error during construction
	Creation() =default
	Creation(Creation && rhs)
	Creation(const Creation & rhs) =default
bool	isInitialized() const returns true if the object was constructed successfully, otherwise false

Protected Attributes inherited from DesignPattern::Creation< Semaphore, SemaphoreError >

	Name
bool	m_isInitialized
ErrorType	m_errorValue

Detailed Description🔗

class iox::posix::Semaphore;

Posix semaphore C++ Wrapping class.

auto semaphore = posix::Semaphore::CreateUnnamed(false, 5);
int value;
if ( semaphore.getValue(value) ) // no error has occurred
{
    std::cout << value << std::endl;
}

Public Functions Documentation🔗

function Semaphore🔗

Semaphore()

Default constructor which creates an uninitialized semaphore. This semaphore object is unusable you need to reassign it with an object created by the semaphore factory methods.

function Semaphore🔗

Semaphore(
    Semaphore && rhs
)

Move constructor.

function operator=🔗

Semaphore & operator=(
    Semaphore && rhs
)

Move assignment operator.

function Semaphore🔗

Semaphore(
    const Semaphore & 
)

We are denying Semaphore copy since it manages the semaphore resource and the underlying concept did not include copying.

function operator=🔗

Semaphore & operator=(
    const Semaphore & 
)

We are denying Semaphore copy since it manages the semaphore resource and the underlying concept did not include copying.

function ~Semaphore🔗

~Semaphore()

Destructor.

function getValue🔗

cxx::expected< int, SemaphoreError > getValue() const

calls sem_getvalue which gets the value of a semaphore From the sem_getvalue manpage: sem_getvalue() places the current value of the semaphore pointed to sem into the integer pointed to by sval.

Parameters:

value reference in which the value of the semaphore is written to

Return: expected which contains either the value of the semaphore or the cause why the value could not be retrieved

If one or more processes or threads are blocked waiting to lock the semaphore with sem_wait(3), POSIX.1 permits two possibilities for the value returned in sval: either 0 is returned; or a negative number whose absolute value is the count of the number of processes and threads currently blocked in sem_wait(3). Linux adopts the former behavior.

function post🔗

cxx::expected< SemaphoreError > post()

calls sem_post which unlocks a semaphore From the sem_post manpage: sem_post() increments (unlocks) the semaphore pointed to by sem. If the semaphore's value consequently becomes greater than zero, then another process or thread blocked in a sem_wait(3) call will be woken up and proceed to lock the semaphore.

Return: if post fails the expected contains the error which occurred

function timedWait🔗

cxx::expected< SemaphoreWaitState, SemaphoreError > timedWait(
    const units::Duration abs_timeout
)

see wait()

Parameters:

abs_timeout timeout of the wait

Return: when successful the SemaphoreWaitState states if a timeout happened or not otherwise the SemaphoreError contains the error

function tryWait🔗

cxx::expected< bool, SemaphoreError > tryWait()

see wait()

Return: if the semaphore was decremented the expected contains the value true otherwise false. if an error occurred it is stored inside the expected

function wait🔗

cxx::expected< SemaphoreError > wait()

calls sem_wait which locks a semaphore From the sem_wait manpage: sem_wait() decrements (locks) the semaphore pointed to by sem. If the semaphore's value is greater than zero, then the decrement proceeds, and the function returns, immediately. If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or a signal handler interrupts the call.

Return: if an error during the call occurs the error value is set

iox_sem_trywait() is the same as sem_wait(), except that if the decrement cannot be immediately performed, then call returns an error (errno set to EAGAIN) instead of blocking.

iox_sem_timedwait() is the same as sem_wait(), except that abs_timeout specifies a limit on the amount of time that the call should block if the decrement cannot be immediately performed.

If the timeout has already expired by the time of the call, and the semaphore could not be locked immediately, then iox_sem_timedwait() fails with a timeout error (errno set to ETIMEDOUT).

If the operation can be performed immediately, then iox_sem_timedwait() never fails with a timeout error, regardless of the value of abs_timeout. Furthermore, the validity of abs_timeout is not checked in this case.

Friends🔗

friend DesignPattern::Creation< Semaphore, SemaphoreError >🔗

friend class DesignPattern::Creation< Semaphore, SemaphoreError >;

Updated on 18 December 2023 at 13:11:42 CET