SemaphoreManager Class Reference

Ideally, this would be SEMMSL, but that is hard to portably determine at compile time. More...

#include <SemaphoreManager.h>

Detailed Description

Ideally, this would be SEMMSL, but that is hard to portably determine at compile time.

If you can't increase your system's SEMMSL (and possibly SEMMNS), you may want to consider decreasing this. initializes, manages, and releases a set of System V style semaphores

Should be initialized pre-fork into a shared region

Definition at line 21 of file SemaphoreManager.h.

List of all members.

Public Types
enum	IntrPolicy_t { INTR_CANCEL_VERBOSE, INTR_CANCEL, INTR_RETRY_VERBOSE, INTR_RETRY, INTR_THROW_VERBOSE, INTR_THROW, INTR_EXIT }
	specify options for how to handle EINTR (signal occurred) error condition during a semaphore operation, see setInterruptPolicy() More...
typedef sems_t::index_t	semid_t
	shorthand for the semaphore indexing type
Public Member Functions
	SemaphoreManager ()
	Creates a SemaphoreManager with room for sems_t::MAX_ENTRIES entries.
	SemaphoreManager (unsigned int numRequest)
	Creates a SemaphoreManager with room for numRequest entries.
	SemaphoreManager (const SemaphoreManager &mm)
	copy supported
SemaphoreManager &	operator= (const SemaphoreManager &mm)
	assignment supported
	~SemaphoreManager ()
	destructor
void	aboutToFork ()
	call this on semaphores in shared memory regions if a fork is about to occur so reference counts can be updated for the other process
void	faultShutdown ()
	call this if semaphores need to be released during an emergency shutdown (otherwise semaphore sets can leak past process shutdown -- bad system design IMHO!)
bool	hadFault () const
	returns true if semid is invalid, indicating further semaphore operations are bogus
semid_t	getSemaphore () ATTR_must_check
	returns a new semaphore id, or invalid() if none are available
void	releaseSemaphore (semid_t id)
	marks a semaphore as available for reassignment
IntrPolicy_t	getInterruptPolicy (semid_t id) const
	return the semaphore's interrupt policy (doesn't check id validity)
void	setInterruptPolicy (semid_t id, IntrPolicy_t p)
	set the semaphore's interrupt policy (doesn't check id validity)
bool	lower (semid_t id, unsigned int x, bool block=true) const
	Lowers a semaphore's value by x, optionally blocking if the value would go negative until it is raised enough to succeed.
void	raise (semid_t id, unsigned int x) const
	raises a semaphore's value by x
int	getValue (semid_t id) const
	returns the semaphore's value
void	setValue (semid_t id, int x) const
	sets the semaphore's value
int	getNumZeroBlockers (semid_t id) const
	return the number of threads/processes which are blocking for the indicated semaphore to hit zero
bool	testZero (semid_t id, bool block=true) const
	tests if the semaphore's value is zero, optionally blocking until it is
bool	testZero_add (semid_t id, int x, bool testblock=true, bool addblock=true) const
	tests if the semaphore's value is zero, optionally blocking until it is, and then adding x
bool	add_testZero (semid_t id, int x, bool addblock=true, bool testblock=true) const
	adds x to the semaphore's value, optionally blocking in the case that x is negative and larger than the semaphore's value. After adding, test whether the semaphore is zero, optionally blocking again until it is.
bool	add_testZero_add (semid_t id, int x1, int x2, bool add1block=true, bool testblock=true, bool add2block=true) const
	adds x to the semaphore's value, optionally blocking in the case that x1 is negative and larger than the semaphore's value. After adding, test whether the semaphore is zero, optionally blocking again until it is, and then adding x2
unsigned int	available () const
	returns the number of semaphores currently available in the set
unsigned int	used () const
	returns the number of semaphores which have been used
semid_t	invalid () const
	returns the "invalid" id value, for testing against getSemaphore
Static Public Attributes
static const unsigned int	MAX_SEM = SYSTEM_MAX_SEM
	wouldn't want to claim the entire system's worth, even if we could
Protected Types
typedef ListMemBuf< bool, SYSTEM_MAX_SEM >	sems_t
	shorthand for the type of sems
Protected Member Functions
void	init ()
	basic initialization called by the constructor -- don't call twice
Protected Attributes
sems_t	sems
	tracks which semaphores have been handed out; the bool value isn't actually used
unsigned int	nsem
	number of real semaphores in the set obtained from the system
int	semid
	the system's identifier for the set
semid_t	mysem
	a lock semaphore for management operations on the set (handing out or taking back semaphores from clients)
semid_t	refc
	a reference count of this semaphore set -- when it goes back to 0, the set is released from the system
IntrPolicy_t	intrPolicy [sems_t::MAX_ENTRIES]
	interrupt policy for each semaphore

Member Typedef Documentation

typedef sems_t::index_t SemaphoreManager::semid_t

shorthand for the semaphore indexing type

Definition at line 30 of file SemaphoreManager.h.

typedef ListMemBuf<bool,SYSTEM_MAX_SEM> SemaphoreManager::sems_t [protected]

shorthand for the type of sems

Definition at line 23 of file SemaphoreManager.h.

Member Enumeration Documentation

enum SemaphoreManager::IntrPolicy_t

specify options for how to handle EINTR (signal occurred) error condition during a semaphore operation, see setInterruptPolicy()

Enumerator:

INTR_CANCEL_VERBOSE	give up, return failure, display error message on console
INTR_CANCEL	give up, return failure
INTR_RETRY_VERBOSE	just repeat semaphore operation, display error message on console
INTR_RETRY	just repeat semaphore operation
INTR_THROW_VERBOSE	throw a std::runtime_error exception, display error message on console
INTR_THROW	throw a std::runtime_error exception
INTR_EXIT	kill process, with error message

Definition at line 32 of file SemaphoreManager.h.

Constructor & Destructor Documentation

SemaphoreManager::SemaphoreManager ( )

Creates a SemaphoreManager with room for sems_t::MAX_ENTRIES entries.

2 of these entries are reserved for internal use, so user code will actually only have access to sems_t::MAX_ENTRIES-2 entries. Use available() to determine this value at runtime.

Definition at line 34 of file SemaphoreManager.cc.

SemaphoreManager::SemaphoreManager ( unsigned int numRequest ) [explicit]

Creates a SemaphoreManager with room for numRequest entries.

adds 2 for SemaphoreManager's own reference count and mutex lock, so you'll actually have numRequest semaphores available

Definition at line 38 of file SemaphoreManager.cc.

SemaphoreManager::SemaphoreManager ( const SemaphoreManager & mm )

copy supported

Definition at line 134 of file SemaphoreManager.cc.

SemaphoreManager::~SemaphoreManager ( )

destructor

Definition at line 195 of file SemaphoreManager.cc.

Member Function Documentation

void SemaphoreManager::aboutToFork ( )

call this on semaphores in shared memory regions if a fork is about to occur so reference counts can be updated for the other process

Definition at line 218 of file SemaphoreManager.cc.

bool SemaphoreManager::add_testZero	(	semid_t	id,
		int	x,
		bool	addblock = `true`,
		bool	testblock = `true`
	)			const

adds x to the semaphore's value, optionally blocking in the case that x is negative and larger than the semaphore's value. After adding, test whether the semaphore is zero, optionally blocking again until it is.

If no blocking is required (e.g. x is positive) then the add and test should be an atomic pair. If a thread cancellation occurs, the operation WILL NOT be undone before the call unwinds, as adding to the count can unblock threads which can't be recalled.

See also:: testZero_add(), testZero()

Definition at line 441 of file SemaphoreManager.cc.

bool SemaphoreManager::add_testZero_add	(	semid_t	id,
		int	x1,
		int	x2,
		bool	add1block = `true`,
		bool	testblock = `true`,
		bool	add2block = `true`
	)			const

adds x to the semaphore's value, optionally blocking in the case that x1 is negative and larger than the semaphore's value. After adding, test whether the semaphore is zero, optionally blocking again until it is, and then adding x2

If no blocking is required (e.g. x is positive) then the add and test should be an atomic pair. If a thread cancellation occurs, the operation WILL NOT be undone before the call unwinds, as adding to the count can unblock threads which can't be recalled.

See also:: testZero_add(), testZero()

Definition at line 497 of file SemaphoreManager.cc.

unsigned int SemaphoreManager::available ( ) const

returns the number of semaphores currently available in the set

Definition at line 111 of file SemaphoreManager.h.

void SemaphoreManager::faultShutdown ( )

call this if semaphores need to be released during an emergency shutdown (otherwise semaphore sets can leak past process shutdown -- bad system design IMHO!)

Definition at line 222 of file SemaphoreManager.cc.

IntrPolicy_t SemaphoreManager::getInterruptPolicy ( semid_t id ) const

return the semaphore's interrupt policy (doesn't check id validity)

Definition at line 70 of file SemaphoreManager.h.

int SemaphoreManager::getNumZeroBlockers ( semid_t id ) const

return the number of threads/processes which are blocking for the indicated semaphore to hit zero

Definition at line 317 of file SemaphoreManager.cc.

SemaphoreManager::semid_t SemaphoreManager::getSemaphore ( )

returns a new semaphore id, or invalid() if none are available

Definition at line 230 of file SemaphoreManager.cc.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReadStatusListener(), and MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReceiver().

int SemaphoreManager::getValue ( semid_t id ) const

returns the semaphore's value

Definition at line 303 of file SemaphoreManager.cc.

Referenced by MessageQueueStatusThread::run().

bool SemaphoreManager::hadFault ( ) const

returns true if semid is invalid, indicating further semaphore operations are bogus

Definition at line 62 of file SemaphoreManager.h.

void SemaphoreManager::init ( ) [protected]

basic initialization called by the constructor -- don't call twice

Definition at line 42 of file SemaphoreManager.cc.

Referenced by SemaphoreManager().

semid_t SemaphoreManager::invalid ( ) const

returns the "invalid" id value, for testing against getSemaphore

Definition at line 118 of file SemaphoreManager.h.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReadStatusListener(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReceiver(), MessageQueueStatusThread::addStatusListener(), MessageQueueStatusThread::cancelled(), MessageReceiver::finish(), MessageReceiver::launched(), MessageReceiver::MessageReceiver(), MessageQueueStatusThread::stop(), and MessageReceiver::~MessageReceiver().

bool SemaphoreManager::lower	(	semid_t	id,
		unsigned int	x,
		bool	block = `true`
	)			const

Lowers a semaphore's value by x, optionally blocking if the value would go negative until it is raised enough to succeed.

Returns true if the semaphore was successfully lowered. If a thread cancellation occurs, the operation WILL NOT be undone before the call unwinds, as hitting zero can unblock threads which can't be recalled.

Definition at line 245 of file SemaphoreManager.cc.

Referenced by getSemaphore(), operator=(), releaseSemaphore(), MessageQueueStatusThread::run(), MessageReceiver::runloop(), SemaphoreManager(), testZero_add(), MessageReceiver::waitNextMessage(), and ~SemaphoreManager().

SemaphoreManager & SemaphoreManager::operator= ( const SemaphoreManager & mm )

assignment supported

Definition at line 145 of file SemaphoreManager.cc.

void SemaphoreManager::raise	(	semid_t	id,
		unsigned int	x
	)			const

raises a semaphore's value by x

Definition at line 297 of file SemaphoreManager.cc.

Referenced by MessageReceiver::markRead(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::markRead(), operator=(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::readMessage(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), MessageReceiver::stop(), and MessageQueueStatusThread::stop().

void SemaphoreManager::releaseSemaphore ( semid_t id )

marks a semaphore as available for reassignment

Definition at line 239 of file SemaphoreManager.cc.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReadStatusListener(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::addReceiver(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReadStatusListener(), and MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver().

void SemaphoreManager::setInterruptPolicy	(	semid_t	id,
		IntrPolicy_t	p
	)

set the semaphore's interrupt policy (doesn't check id validity)

Definition at line 72 of file SemaphoreManager.h.

void SemaphoreManager::setValue	(	semid_t	id,
		int	x
	)			const

sets the semaphore's value

Definition at line 309 of file SemaphoreManager.cc.

Referenced by getSemaphore(), and init().

bool SemaphoreManager::testZero	(	semid_t	id,
		bool	block = `true`
	)			const

tests if the semaphore's value is zero, optionally blocking until it is

returns true if the semaphore's value is zero.

See also:: testZero_add(), add_testZero()

Definition at line 323 of file SemaphoreManager.cc.

bool SemaphoreManager::testZero_add	(	semid_t	id,
		int	x,
		bool	testblock = `true`,
		bool	addblock = `true`
	)			const

tests if the semaphore's value is zero, optionally blocking until it is, and then adding x

If x is negative, then addblock will cause it to block again until someone else raises the semaphore. Otherwise, the add should be performed as an atomic unit with the test. If x is non-negative, then the add should never block. If a thread cancellation occurs, the operation WILL be undone before the call unwinds, as this usage is exclusive to other threads.