Fawkes API  Fawkes Development Version
fawkes::SemaphoreSet Class Reference

IPC semaphore set. More...

#include <utils/ipc/semset.h>

Public Member Functions

 SemaphoreSet (const char *path, char id, int num_sems, bool create=false, bool destroy_on_delete=false)
 Constructor. More...
 
 SemaphoreSet (int key, int num_sems, bool create=false, bool destroy_on_delete=false)
 Constructor. More...
 
 SemaphoreSet (int num_sems, bool destroy_on_delete=false)
 Constructor. More...
 
 ~SemaphoreSet ()
 Destructor. More...
 
bool valid ()
 Check if the semaphore set is valid. More...
 
void lock (unsigned short sem_num=0, short num=1)
 Lock resources on the semaphore set. More...
 
bool try_lock (unsigned short sem_num=0, short num=1)
 Try to lock resources on the semaphore set. More...
 
void unlock (unsigned short sem_num=0, short num=-1)
 Unlock resources on the semaphore set. More...
 
void set_value (int sem_num, int val)
 Set the semaphore value. More...
 
int get_value (int sem_num)
 Get the semaphore value. More...
 
int key ()
 Get key of semaphore. More...
 
void set_destroy_on_delete (bool destroy)
 Set if semaphore set should be destroyed on delete. More...
 

Static Public Member Functions

static int free_key ()
 Get a non-zero free key Scans the key space sequentially until a non-zero unused key is found. More...
 
static void destroy (int key)
 Destroy a semaphore set. More...
 

Protected Attributes

bool destroy_on_delete
 Destroy this semaphore on delete? More...
 

Detailed Description

IPC semaphore set.

This class handles semaphore sets. A semaphore is a tool to control access to so-called critical sections. It is used to ensure that only a single process at a time is in the critical section or modifying shared data to avoid corruption.

Semaphores use a single integer as the semaphore value. It denotes the number of resources that are available for the given semaphore. For example if you have two cameras on a robot you may have a value of two for the semaphore value. If the value reaches zero no more resources are available. You will have to wait until more resources are freed again.

Now these individual semaphores are bundled to sets of semaphores. This is useful since there are situations where you want different semaphores for different operations on the shared resource. In the case of a shared memory segment for instance you could have one semaphore for reading and one for writing.

See also
qa_ipc_semset.cpp
Author
Tim Niemueller

Definition at line 32 of file semset.h.

Constructor & Destructor Documentation

◆ SemaphoreSet() [1/3]

fawkes::SemaphoreSet::SemaphoreSet ( const char *  path,
char  id,
int  num_sems,
bool  create = false,
bool  destroy_on_delete = false 
)

Constructor.

Creates a new semaphore set. Will try to open the semaphore if it does exist. Tries to create if create is assured.

Parameters
pathPath to generate the id from
idAdditional info for id.
num_semsNumber of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured.
destroy_on_deleteIf true semaphore set is destroyed if instance is deleted.
createIf true semaphore set is created if it does not exist.

Definition at line 102 of file semset.cpp.

◆ SemaphoreSet() [2/3]

fawkes::SemaphoreSet::SemaphoreSet ( int  key,
int  num_sems,
bool  create = false,
bool  destroy_on_delete = false 
)

Constructor.

Creates a new semaphore set. Will try to open the semaphore if it does exist. Tries to create if create is assured.

Parameters
keyKey of semaphore set as printed by ipcs.
num_semsNumber of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured.
destroy_on_deleteIf true semaphore set is destroyed if instance is deleted.
createIf true semaphore set is created if it does not exist.

Definition at line 137 of file semset.cpp.

◆ SemaphoreSet() [3/3]

fawkes::SemaphoreSet::SemaphoreSet ( int  num_sems,
bool  destroy_on_delete = false 
)

Constructor.

Creates a new semaphore set with a new ID supplied by the system. The id can be queried with getID.

Parameters
num_semsNumber of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured.
destroy_on_deleteIf true semaphore set is destroyed if instance is deleted.

Definition at line 173 of file semset.cpp.

◆ ~SemaphoreSet()

fawkes::SemaphoreSet::~SemaphoreSet ( )

Destructor.

Definition at line 200 of file semset.cpp.

Member Function Documentation

◆ destroy()

void fawkes::SemaphoreSet::destroy ( int  key)
static

Destroy a semaphore set.

Destroy the semaphore denoted by key. No tests are done if some other process is using this semaphore. Use with care!

Parameters
keykey of the semaphore set

Definition at line 414 of file semset.cpp.

Referenced by fawkes::SharedMemory::erase(), and fawkes::SharedMemory::erase_orphaned().

◆ free_key()

int fawkes::SemaphoreSet::free_key ( )
static

Get a non-zero free key Scans the key space sequentially until a non-zero unused key is found.

Not that using this can cause a race-condition. You are in most cases better off using the appropriate constructor that automatically finds a free key.

Returns
0, if no free key could be found, otherwise the non-zero unused key

Definition at line 390 of file semset.cpp.

◆ get_value()

int fawkes::SemaphoreSet::get_value ( int  sem_num)

Get the semaphore value.

Parameters
sem_numThe semaphore number in the set
Returns
value of the semaphore
Exceptions
SemInvalidExceptionSemaphore set is invalid

Definition at line 348 of file semset.cpp.

◆ key()

int fawkes::SemaphoreSet::key ( )

Get key of semaphore.

Returns
Key of semaphore as listed by ipcs.

Definition at line 360 of file semset.cpp.

Referenced by fawkes::SharedMemory::add_semaphore().

◆ lock()

void fawkes::SemaphoreSet::lock ( unsigned short  sem_num = 0,
short  num = 1 
)

Lock resources on the semaphore set.

Locks num resources on semaphore sem_num.

Parameters
sem_numThe semaphore number in the set
numHow many resources to lock? Positive number.
Exceptions
InterruptedExceptionOperation was interrupted (for instance by a signal)
SemCannotLockExceptionSemaphore cannot be locked
SemInvalidExceptionSemaphore set is invalid

Definition at line 255 of file semset.cpp.

Referenced by fawkes::SharedMemory::lock_for_read(), and fawkes::SharedMemory::lock_for_write().

◆ set_destroy_on_delete()

void fawkes::SemaphoreSet::set_destroy_on_delete ( bool  destroy)

Set if semaphore set should be destroyed on delete.

If this is set to true the semaphore set is destroyed from the system if this instance is deleted.

Parameters
destroyset to true, if semaphore set should be destroyed on delete, false otherwise

Definition at line 373 of file semset.cpp.

Referenced by fawkes::SharedMemory::~SharedMemory().

◆ set_value()

void fawkes::SemaphoreSet::set_value ( int  sem_num,
int  val 
)

Set the semaphore value.

Parameters
sem_numThe semaphore number in the set
valThe value to set
Exceptions
SemCannotSetValExceptionCannot set value

Definition at line 329 of file semset.cpp.

Referenced by fawkes::SharedMemory::add_semaphore().

◆ try_lock()

bool fawkes::SemaphoreSet::try_lock ( unsigned short  sem_num = 0,
short  num = 1 
)

Try to lock resources on the semaphore set.

Parameters
sem_numThe semaphore number in the set
numHow many resources to lock? Positive number.
Returns
true, if the semaphore could be locked, false otherwise
Exceptions
InterruptedExceptionOperation was interrupted (for instance by a signal)
SemCannotLockExceptionSemaphore cannot be locked
SemInvalidExceptionSemaphore set is invalid

Definition at line 279 of file semset.cpp.

Referenced by fawkes::SharedMemory::try_lock_for_read(), and fawkes::SharedMemory::try_lock_for_write().

◆ unlock()

void fawkes::SemaphoreSet::unlock ( unsigned short  sem_num = 0,
short  num = -1 
)

Unlock resources on the semaphore set.

Parameters
sem_numThe semaphore number in the set
numHow many resources to unlock? Negative number.
Exceptions
InterruptedExceptionOperation was interrupted (for instance by a signal)
SemCannotUnlockExceptionSemaphore cannot be unlocked
SemInvalidExceptionSemaphore set is invalid

Definition at line 308 of file semset.cpp.

Referenced by fawkes::SharedMemory::add_semaphore(), fawkes::SharedMemory::lock_for_write(), fawkes::SharedMemory::try_lock_for_write(), and fawkes::SharedMemory::unlock().

◆ valid()

bool fawkes::SemaphoreSet::valid ( )

Check if the semaphore set is valid.

If the queue could not be opened yet (for example if you gave create=false to the constructor) isValid() will try to open the queue.

Returns
This method returns false if the message queue could not be opened or if it has been closed, it returns true if messages can be sent or received.

Definition at line 216 of file semset.cpp.

Member Data Documentation

◆ destroy_on_delete

fawkes::SemaphoreSet::destroy_on_delete
protected

Destroy this semaphore on delete?

Definition at line 63 of file semset.h.


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