Fawkes API Fawkes Development Version
|
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... | |
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.
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.
path | Path to generate the id from |
id | Additional info for id. |
num_sems | Number of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured. |
destroy_on_delete | If true semaphore set is destroyed if instance is deleted. |
create | If true semaphore set is created if it does not exist. |
Definition at line 97 of file semset.cpp.
References destroy_on_delete.
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.
key | Key of semaphore set as printed by ipcs. |
num_sems | Number of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured. |
destroy_on_delete | If true semaphore set is destroyed if instance is deleted. |
create | If true semaphore set is created if it does not exist. |
Definition at line 132 of file semset.cpp.
References destroy_on_delete, and key().
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.
num_sems | Number of semaphores to generate in this set. Only used if semaphore set did not already exist and create is assured. |
destroy_on_delete | If true semaphore set is destroyed if instance is deleted. |
Definition at line 165 of file semset.cpp.
References destroy_on_delete.
fawkes::SemaphoreSet::~SemaphoreSet | ( | ) |
|
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!
key | key of the semaphore set |
Definition at line 404 of file semset.cpp.
References key().
Referenced by fawkes::SharedMemory::erase(), fawkes::SharedMemory::erase_orphaned(), and set_destroy_on_delete().
|
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.
Definition at line 381 of file semset.cpp.
References key().
int fawkes::SemaphoreSet::get_value | ( | int | sem_num | ) |
Get the semaphore value.
sem_num | The semaphore number in the set |
SemInvalidException | Semaphore set is invalid |
Definition at line 341 of file semset.cpp.
int fawkes::SemaphoreSet::key | ( | ) |
Get key of semaphore.
Definition at line 353 of file semset.cpp.
Referenced by fawkes::SharedMemory::add_semaphore(), destroy(), free_key(), and SemaphoreSet().
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.
sem_num | The semaphore number in the set |
num | How many resources to lock? Positive number. |
InterruptedException | Operation was interrupted (for instance by a signal) |
SemCannotLockException | Semaphore cannot be locked |
SemInvalidException | Semaphore set is invalid |
Definition at line 244 of file semset.cpp.
Referenced by fawkes::SharedMemory::lock_for_read(), and fawkes::SharedMemory::lock_for_write().
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.
destroy | set to true, if semaphore set should be destroyed on delete, false otherwise |
Definition at line 365 of file semset.cpp.
References destroy(), and destroy_on_delete.
Referenced by fawkes::SharedMemory::operator=(), and fawkes::SharedMemory::~SharedMemory().
void fawkes::SemaphoreSet::set_value | ( | int | sem_num, |
int | val | ||
) |
Set the semaphore value.
sem_num | The semaphore number in the set |
val | The value to set |
SemCannotSetValException | Cannot set value |
Definition at line 322 of file semset.cpp.
Referenced by fawkes::SharedMemory::add_semaphore().
bool fawkes::SemaphoreSet::try_lock | ( | unsigned short | sem_num = 0 , |
short | num = 1 |
||
) |
Try to lock resources on the semaphore set.
sem_num | The semaphore number in the set |
num | How many resources to lock? Positive number. |
InterruptedException | Operation was interrupted (for instance by a signal) |
SemCannotLockException | Semaphore cannot be locked |
SemInvalidException | Semaphore set is invalid |
Definition at line 270 of file semset.cpp.
Referenced by fawkes::SharedMemory::try_lock_for_read(), and fawkes::SharedMemory::try_lock_for_write().
void fawkes::SemaphoreSet::unlock | ( | unsigned short | sem_num = 0 , |
short | num = -1 |
||
) |
Unlock resources on the semaphore set.
sem_num | The semaphore number in the set |
num | How many resources to unlock? Negative number. |
InterruptedException | Operation was interrupted (for instance by a signal) |
SemCannotUnlockException | Semaphore cannot be unlocked |
SemInvalidException | Semaphore set is invalid |
Definition at line 299 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().
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.
Definition at line 205 of file semset.cpp.
|
protected |
Destroy this semaphore on delete?
Definition at line 59 of file semset.h.
Referenced by SemaphoreSet(), set_destroy_on_delete(), and ~SemaphoreSet().