Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

SemaphoreManager Class Reference

#include <SemaphoreManager.h>

List of all members.


Detailed Description

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.


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
SemaphoreManageroperator= (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
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, unsigned 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, unsigned 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.
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 ListMemBuf<bool,SYSTEM_MAX_SEM> SemaphoreManager::sems_t [protected]

shorthand for the type of sems

Definition at line 23 of file SemaphoreManager.h.

shorthand for the semaphore indexing type

Definition at line 30 of file SemaphoreManager.h.


Member Enumeration Documentation

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 30 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 34 of file SemaphoreManager.cc.

SemaphoreManager::SemaphoreManager ( const SemaphoreManager mm  ) 

copy supported

Definition at line 130 of file SemaphoreManager.cc.

SemaphoreManager::~SemaphoreManager (  ) 

destructor

Definition at line 191 of file SemaphoreManager.cc.


Member Function Documentation

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

assignment supported

Definition at line 141 of file SemaphoreManager.cc.

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 214 of file SemaphoreManager.cc.

Referenced by MutexLockBase::aboutToFork().

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 218 of file SemaphoreManager.cc.

bool SemaphoreManager::hadFault (  )  const [inline]

IntrPolicy_t SemaphoreManager::getInterruptPolicy ( semid_t  id  )  const [inline]

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

Definition at line 70 of file SemaphoreManager.h.

void SemaphoreManager::setInterruptPolicy ( semid_t  id,
IntrPolicy_t  p 
) [inline]

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

Definition at line 72 of file SemaphoreManager.h.

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.

Definition at line 239 of file SemaphoreManager.cc.

Referenced by getSemaphore(), operator=(), MessageQueueStatusThread::run(), MessageReceiver::runloop(), SemaphoreManager(), MutexLock< MAX_ACCESS >::unlock(), MessageReceiver::waitNextMessage(), and ~SemaphoreManager().

int SemaphoreManager::getValue ( semid_t  id  )  const

returns the semaphore's value

Definition at line 288 of file SemaphoreManager.cc.

Referenced by MutexLock< MAX_ACCESS >::get_lock_level(), MessageQueueStatusThread::run(), and MutexLock< MAX_ACCESS >::unlock().

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 302 of file SemaphoreManager.cc.

Referenced by WorldStatePool::getCurrentReadState(), and WorldStatePool::isComplete().

bool SemaphoreManager::testZero_add ( semid_t  id,
unsigned 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.

See also:
add_testZero(), testZero()

Definition at line 346 of file SemaphoreManager.cc.

Referenced by MutexLock< MAX_ACCESS >::lock(), and MutexLock< MAX_ACCESS >::try_lock().

bool SemaphoreManager::add_testZero ( semid_t  id,
unsigned 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.

See also:
testZero_add(), testZero()

Definition at line 394 of file SemaphoreManager.cc.

unsigned int SemaphoreManager::available (  )  const [inline]

returns the number of semaphores currently available in the set

Definition at line 101 of file SemaphoreManager.h.

unsigned int SemaphoreManager::used (  )  const [inline]

returns the number of semaphores which have been used

the SemaphoreManager requires 2 semaphores from the set, one for reference counting and one for mutual exclusion during function calls

Definition at line 106 of file SemaphoreManager.h.

void SemaphoreManager::init (  )  [protected]

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

Definition at line 38 of file SemaphoreManager.cc.

Referenced by SemaphoreManager().


Member Data Documentation

const unsigned int SemaphoreManager::MAX_SEM = SYSTEM_MAX_SEM [static]

wouldn't want to claim the entire system's worth, even if we could

Definition at line 27 of file SemaphoreManager.h.

tracks which semaphores have been handed out; the bool value isn't actually used

Definition at line 113 of file SemaphoreManager.h.

Referenced by available(), getSemaphore(), init(), invalid(), operator=(), SemaphoreManager(), and used().

unsigned int SemaphoreManager::nsem [protected]

number of real semaphores in the set obtained from the system

Definition at line 114 of file SemaphoreManager.h.

Referenced by init(), operator=(), and used().

int SemaphoreManager::semid [protected]

the system's identifier for the set

Definition at line 115 of file SemaphoreManager.h.

Referenced by faultShutdown(), hadFault(), init(), lower(), operator=(), SemaphoreManager(), and ~SemaphoreManager().

a lock semaphore for management operations on the set (handing out or taking back semaphores from clients)

Definition at line 116 of file SemaphoreManager.h.

Referenced by getSemaphore(), init(), operator=(), SemaphoreManager(), and ~SemaphoreManager().

a reference count of this semaphore set -- when it goes back to 0, the set is released from the system

Definition at line 117 of file SemaphoreManager.h.

Referenced by aboutToFork(), init(), operator=(), SemaphoreManager(), and ~SemaphoreManager().

interrupt policy for each semaphore

Definition at line 118 of file SemaphoreManager.h.

Referenced by getInterruptPolicy(), getSemaphore(), lower(), and setInterruptPolicy().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:41 2007 by Doxygen 1.5.4