fawkes::SemaphoreSet Class Reference
[Interprocess Communication (IPC)]

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.
	SemaphoreSet (int key, int num_sems, bool create=false, bool destroy_on_delete=false)
	Constructor.
	SemaphoreSet (int num_sems, bool destroy_on_delete=false)
	Constructor.
	~SemaphoreSet ()
	Destructor.
bool	valid ()
	Check if the semaphore set is valid.
void	lock (unsigned short sem_num=0, short num=1)
	Lock resources on the semaphore set.
bool	try_lock (unsigned short sem_num=0, short num=1)
	Try to lock resources on the semaphore set.
void	unlock (unsigned short sem_num=0, short num=-1)
	Unlock resources on the semaphore set.
void	set_value (int sem_num, int val)
	Set the semaphore value.
int	get_value (int sem_num)
	Get the semaphore value.
int	key ()
	Get key of semaphore.
void	set_destroy_on_delete (bool destroy)
	Set if semaphore set should be destroyed on delete.
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.
static void	destroy (int key)
	Destroy a semaphore set.
Protected Attributes
bool	destroy_on_delete
	Destroy this semaphore on delete?

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

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:

	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 102 of file semset.cpp.

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:

	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 137 of file semset.cpp.

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_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 173 of file semset.cpp.

fawkes::SemaphoreSet::~SemaphoreSet ( )

Destructor.

Definition at line 200 of file semset.cpp.

References destroy_on_delete.

Member Function Documentation

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:

key

key of the semaphore set

Definition at line 414 of file semset.cpp.

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

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.

References key().

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

Get the semaphore value.

Parameters:

sem_num

The semaphore number in the set

Returns:: value of the semaphore

Exceptions:

SemInvalidException

Semaphore set is invalid

Definition at line 348 of file semset.cpp.

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(), and free_key().

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_num	The semaphore number in the set
	num	How many resources to lock? Positive number.

Exceptions:

	InterruptedException	Operation was interrupted (for instance by a signal)
	SemCannotLockException	Semaphore cannot be locked
	SemInvalidException	Semaphore set is invalid

Definition at line 255 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.

Parameters:

destroy

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

Definition at line 373 of file semset.cpp.

References destroy_on_delete.

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

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

Set the semaphore value.

Parameters:

	sem_num	The semaphore number in the set
	val	The value to set

Exceptions:

SemCannotSetValException

Cannot set value

Definition at line 329 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.

Parameters:

	sem_num	The semaphore number in the set
	num	How many resources to lock? Positive number.

Returns:: true, if the semaphore could be locked, false otherwise

Exceptions:

	InterruptedException	Operation was interrupted (for instance by a signal)
	SemCannotLockException	Semaphore cannot be locked
	SemInvalidException	Semaphore 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().

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

Unlock resources on the semaphore set.

Parameters:

	sem_num	The semaphore number in the set
	num	How many resources to unlock? Negative number.

Exceptions:

	InterruptedException	Operation was interrupted (for instance by a signal)
	SemCannotUnlockException	Semaphore cannot be unlocked
	SemInvalidException	Semaphore 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().

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

fawkes::SemaphoreSet::destroy_on_delete [protected]

Destroy this semaphore on delete?

Definition at line 63 of file semset.h.

Referenced by set_destroy_on_delete(), and ~SemaphoreSet().

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

src/libs/utils/ipc/semset.h
src/libs/utils/ipc/semset.cpp

Context Navigation

fawkes::SemaphoreSet Class Reference [Interprocess Communication (IPC)]

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

fawkes::SemaphoreSet Class Reference
[Interprocess Communication (IPC)]