corelinux::SemaphoreGroup Class Referenceabstract

A SemaphoreGroup is an extension to the Linux semaphore set. More...

`#include <SemaphoreGroup.hpp>`

## Public Member Functions

| throw (Assertion, SemaphoreException)
| Default constructor creates a private group semaphores. More...
| SemaphoreGroup (Short, SemaphoreGroupIdentifierCref, Int, CreateDisposition disp=FAIL_IF_EXISTS) throw (Assertion,SemaphoreException)
| Constructor to open or create a semaphore group with a specific identifier. More...
| SemaphoreGroup (Short, CharCptr, Int, CreateDisposition disp=FAIL_IF_EXISTS) throw (Assertion,SemaphoreException)
| Constructor to open or create a semaphore group by name. More...
virtual | ~SemaphoreGroup (void)
| Virtual destructor.
bool | operator== (SemaphoreGroupCref) const
| Equality operator compares the identifier. More...
Short | getSemaphoreCount (void) const
| Return the number of semaphores in the group. More...
SemaphoreGroupIdentifierCref | getIdentifier (void) const
| Return the SemaphoreGroupIdentifier. More...
virtual AbstractSemaphorePtr | createSemaphore (void)=0 throw ( SemaphoreException )
| Create a default semaphore type from group. More...
virtual AbstractSemaphorePtr | createSemaphore (SemaphoreIdentifierRef aIdentifier, CreateDisposition disp=CREATE_OR_REUSE, bool Recursive=false, bool Balking=false)=0 throw ( SemaphoreException )
| Create or open (use) a specific semphore in the group. More...
virtual AbstractSemaphorePtr | createSemaphore (std::string aName, CreateDisposition disp=CREATE_OR_REUSE, bool Recursive=false, bool Balking=false)=0 throw ( SemaphoreException )
| Create or open (use) a specific semphore in the group. More...
virtual void | destroySemaphore (AbstractSemaphorePtr)=0 throw ( SemaphoreException )
| Destroys a created semaphore from this group. More...
Public Member Functions inherited from corelinux::Synchronized
| Synchronized (void)
| Default constructor.
| Synchronized (SynchronizedCref)
| Copy constructor.
virtual | ~Synchronized (void)
| Virtual Destructor.
SynchronizedRef | operator= (SynchronizedCref)
| Assignment operator.
bool | operator== (SynchronizedCref) const
| Equality operator.

## Protected Member Functions

| SemaphoreGroup (void) throw ( Assertion )
| Default constructor not allowed.
| throw (Assertion)
| Copy constructor not allowed.
SemaphoreGroupRef | operator= (SemaphoreGroupCref) throw ( Assertion )
| Assignment operator not allowed.
void | setGroupType (IntCref) const
| This indirects to CSA for non-private group types. More...
bool | isPrivate (void) const
| Claim an unused semaphore from the group. More...
Protected Member Functions inherited from corelinux::Synchronized
Guard | access (void) const throw (SemaphoreException)
| Access returns a instance of Guard which is block scoped to the caller. More...

## Friends

class | SemaphoreCommon

## Additional Inherited Members

Protected Types inherited from corelinux::Synchronized
typedef Guard * | GuardPtr
typedef const Guard * | GuardCptr
typedef Guard & | GuardRef
typedef const Guard & | GuardCref

## Detailed Description

A SemaphoreGroup is an extension to the Linux semaphore set.

This provides a way to logically group semaphores. A SemaphoreGroup acts as a Semaphore factory, creating and destroying Semaphores for the user.

## Constructor & Destructor Documentation

corelinux::SemaphoreGroup::SemaphoreGroup | ( | Short | aSemCount,
|  | SemaphoreGroupIdentifierCref | aGID,
|  | Int | aRightSet,
|  | CreateDisposition | disp = `FAIL_IF_EXISTS`
| ) |  |
throw | ( | Assertion,
|  | SemaphoreException
| ) |  |

Constructor to open or create a semaphore group with a specific identifier.

Parameters

  Short | Number of semaphores in group, this only has meaning used if failOnExist = true
  SemaphoreGroupIdentifier | valid group identifier either through a system call or via another ipc mechanism
  AccessRights | Specifies access control for group
  CreateDisposition | indicates how to treat the conditions that the group may meet in the request: CREATE_OR_REUSE indicates that the caller doesn't care FAIL_IF_EXISTS indicates the attempt was for a create FAIL_IF_NOTEXISTS indicates the attempt was for a open

Exceptions

  Assertion | if aCount < 1
  SemaphoreException | for described states

See Also
  corelinux::AccessRights

References corelinux::FAIL_IF_EXISTS, corelinux::FAIL_IF_NOTEXISTS, corelinux::Thread::getKernelError(), and corelinux::SemaphoreCommon::groupDefined().

corelinux::SemaphoreGroup::SemaphoreGroup | ( | Short | aSemCount,
|  | CharCptr | aName,
|  | Int | aRightSet,
|  | CreateDisposition | disp = `FAIL_IF_EXISTS`
| ) |  |
throw | ( | Assertion,
|  | SemaphoreException
| ) |  |

Constructor to open or create a semaphore group by name.

Parameters

  Short | Number of semaphores in group, this only has meaning used if failOnExist = true
  Char | pointer to Group name
  AccessRights | Specifies access control for group
  CreateDisposition | indicates how to treat the conditions that the group may meet in the request: CREATE_OR_REUSE indicates that the caller doesn't care FAIL_IF_EXISTS indicates the attempt was for a create FAIL_IF_NOTEXISTS indicates the attempt was for a open

Exceptions

  Assertion | if aCount < 1 or aCount > system defined maximum for group
  SemaphoreException | for described states

See Also
  corelinux::AccessRights

References corelinux::CREATE_OR_REUSE, corelinux::FAIL_IF_EXISTS, corelinux::FAIL_IF_NOTEXISTS, corelinux::Thread::getKernelError(), corelinux::SemaphoreCommon::groupDefined(), corelinux::Environment::removeCommonAccess(), and corelinux::Environment::setupCommonAccess().

## Member Function Documentation

virtual AbstractSemaphorePtr corelinux::SemaphoreGroup::createSemaphore | ( | void |  | ) |
throw | ( | SemaphoreException
| ) |  |

pure virtual

Create a default semaphore type from group.

Returns
  AbstractSemaphore aSem - pointer to created semaphore

Exceptions

  SemaphoreException | if no sems left in group

Implemented in corelinux::EventSemaphoreGroup, corelinux::GatewaySemaphoreGroup, corelinux::MutexSemaphoreGroup, and corelinux::CoreLinuxGuardGroup.

virtual AbstractSemaphorePtr corelinux::SemaphoreGroup::createSemaphore | ( | SemaphoreIdentifierRef | aIdentifier,
|  | CreateDisposition | disp = `CREATE_OR_REUSE`,
|  | bool | Recursive = `false`,
|  | bool | Balking = `false`
| ) |  |
throw | ( | SemaphoreException
| ) |  |

pure virtual

Create or open (use) a specific semphore in the group.

Parameters

  SemaphoreIdentifier | identifies which semphore id to create or attempt to use
  CreateDisposition | indicates how to treat the conditions that the group may meet in the request: CREATE_OR_REUSE indicates that the caller doesn't care FAIL_IF_EXISTS indicates the attempt was for a create FAIL_IF_NOTEXISTS indicates the attempt was for a open
  Recursive | to allow same thread multiple locks
  Balking | to allow the semaphore to balk

Returns
  AbstractSemaphore aSem - pointer to created or opened semaphore

Exceptions

  SemaphoreException | if the disposition disagrees with the semaphore state, or if it is a erroneous identifier

Implemented in corelinux::EventSemaphoreGroup, corelinux::MutexSemaphoreGroup, corelinux::GatewaySemaphoreGroup, and corelinux::CoreLinuxGuardGroup.

virtual AbstractSemaphorePtr corelinux::SemaphoreGroup::createSemaphore | ( | std::string | aName,
|  | CreateDisposition | disp = `CREATE_OR_REUSE`,
|  | bool | Recursive = `false`,
|  | bool | Balking = `false`
| ) |  |
throw | ( | SemaphoreException
| ) |  |

pure virtual

Create or open (use) a specific semphore in the group.

Parameters

  string | identifies which semphore id to create or attempt to use
  CreateDisposition | indicates how to treat the conditions that the group may meet in the request: CREATE_OR_REUSE indicates that the caller doesn't care FAIL_IF_EXISTS indicates the attempt was for a create FAIL_IF_NOTEXISTS indicates the attempt was for a open
  Recursive | to allow same thread multiple locks
  Balking | to allow the semaphore to balk

Returns
  AbstractSemaphore aSem - pointer to created or opened semaphore

Exceptions

  SemaphoreException | if the disposition disagrees with the semaphore state, or if it is a erroneous identifier

Implemented in corelinux::EventSemaphoreGroup, corelinux::GatewaySemaphoreGroup, corelinux::MutexSemaphoreGroup, and corelinux::CoreLinuxGuardGroup.

virtual void corelinux::SemaphoreGroup::destroySemaphore | ( | AbstractSemaphorePtr |  | ) |
throw | ( | SemaphoreException
| ) |  |

pure virtual

Destroys a created semaphore from this group.

Parameters

  AbstractSemaphore | pointer of semaphore to destroy

Exceptions

  SemaphoreException | if semaphore does not belong to this group

Implemented in corelinux::EventSemaphoreGroup, corelinux::GatewaySemaphoreGroup, corelinux::MutexSemaphoreGroup, and corelinux::CoreLinuxGuardGroup.

SemaphoreGroupIdentifierCref corelinux::SemaphoreGroup::getIdentifier | ( | void |  | ) | const

inline

Return the SemaphoreGroupIdentifier.

Returns
  SemaphoreGroupIdentifier

Referenced by corelinux::AbstractSemaphore::AbstractSemaphore(), corelinux::AbstractSemaphore::getGroupIdentifier(), corelinux::SemaphoreCommon::registerGroup(), and corelinux::SemaphoreCommon::SemaphoreCommon().

Short corelinux::SemaphoreGroup::getSemaphoreCount | ( | void |  | ) | const

Return the number of semaphores in the group.

Returns
  Short Count

References isPrivate().

Referenced by corelinux::CoreLinuxGuardGroup::createSemaphore(), and corelinux::SemaphoreCommon::SemaphoreCommon().

bool corelinux::SemaphoreGroup::isPrivate | ( | void |  | ) | const

inline protected

Claim an unused semaphore from the group.

This implies that even though the group may be shared, the user has elected to use privately.Internal check for creation visibility

Referenced by getSemaphoreCount(), corelinux::SemaphoreCommon::getSemaphoreMaxValue(), corelinux::SemaphoreCommon::obtainSemaphore(), corelinux::SemaphoreCommon::relinquishSemaphore(), corelinux::SemaphoreCommon::setLock(), corelinux::SemaphoreCommon::setMaxValue(), corelinux::SemaphoreCommon::setUnLock(), and corelinux::SemaphoreCommon::waitZero().

bool corelinux::SemaphoreGroup::operator== | ( | SemaphoreGroupCref | aSemGroupRef | ) | const

Equality operator compares the identifier.

Parameters

  SemaphoreGroup | a reference to SemaphoreGroup

Returns
  bool True if equal

void corelinux::SemaphoreGroup::setGroupType | ( | IntCref |  | ) | const

protected

This indirects to CSA for non-private group types.

Parameters

  Int | reference to type where 0 = Mutex, 1 = Gateway, 2 = Event, 3-10 reserved. Anything greater than 10 is user defined.

corelinux::SemaphoreGroup::throw | ( | Assertion | ,
|  | SemaphoreException |
| ) |  |

Default constructor creates a private group semaphores.

Parameters

  Short | Number of semaphores in group
  AccessRights | Specifies access control for group, default is owner only.

Exceptions

  Assertion | if aCount < 1
  SemaphoreException | if kernel group create call fails.

See Also
  corelinux::AccessRights

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

- SemaphoreGroup.hpp
- SemaphoreGroup.cpp

This is the CoreLinux++ reference manual
Provided by The CoreLinux Consortium