Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

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
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
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

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

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 (  ) 
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().

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::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.

See also:
add_testZero(), testZero()

Definition at line 375 of file SemaphoreManager.cc.

unsigned int SemaphoreManager::used (  )  const

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 116 of file SemaphoreManager.h.


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.

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

Definition at line 126 of file SemaphoreManager.h.

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

unsigned int SemaphoreManager::nsem [protected]

number of real semaphores in the set obtained from the system

Definition at line 124 of file SemaphoreManager.h.

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

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

Definition at line 127 of file SemaphoreManager.h.

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

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

Definition at line 123 of file SemaphoreManager.h.

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


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

Tekkotsu v5.1CVS
Generated Mon May 9 04:59:16 2016 by Doxygen 1.6.3