corelinux::GatewaySemaphore Class Reference

GatewaySemphore enables a depth of resource indicator. More...

`#include <GatewaySemaphore.hpp>`

## Public Member Functions

| GatewaySemaphore (SemaphoreGroupPtr, SemaphoreIdentifierRef, Count, bool Recursive=false, bool Balking=false) throw ( NullPointerException )
| Default constructor requires the identifier of the semaphore in the semaphore group and a count of resources for control. More...
virtual | ~GatewaySemaphore (void)
| Virtual Destructor.
virtual bool | isLocked (void)
| Ask if AbstractSemaphore instance is locked.
virtual bool | isAnOwner (void)
| Returns true if calling thread owns a resource.
virtual Counter | getOwnerRecursionQueueLength (void)
| Returns the recursion depth for the calling thread. More...
virtual SemaphoreOperationStatus | lockWithWait (void) throw ( SemaphoreException )
| Request the lock, wait for availability.
virtual SemaphoreOperationStatus | lockWithNoWait (void) throw ( SemaphoreException )
| Request the lock without waiting.
virtual SemaphoreOperationStatus | release (void) throw ( SemaphoreException )
| Request the AbstractSemaphore but timeout if not available. More...
Public Member Functions inherited from corelinux::Semaphore
| Semaphore (SemaphoreGroupPtr, SemaphoreIdentifierRef, bool Recursive=false, bool Balking=false) throw ( NullPointerException )
| Default constructor requires the identifier of the semaphore in the semaphore group. More...
virtual | ~Semaphore (void)
| Virtual Destructor.
bool | operator== (SemaphoreCref aRef) const
| Equality operator returns true if identifiers match.
virtual bool | isBalkingEnabled (void) const
| Returns true if balking enabled.
virtual bool | isRecursionEnabled (void) const
| Returns true if recursion allowed.
virtual ThreadIdentifierCref | getOwningThreadIdentifier (void) const
| Returns the identifier of who currently owns the semaphore.
virtual CounterCref | getRecursionQueueLength (void) const
| Return the depth of the recursion for the owner.
Public Member Functions inherited from corelinux::AbstractSemaphore
| AbstractSemaphore (SemaphoreGroupPtr, SemaphoreIdentifierRef) throw ( NullPointerException )
| Default constructor.
virtual | ~AbstractSemaphore (void)
| Virtual Destructor.
bool | operator== (AbstractSemaphoreCref aRef) const
| Equality operator returns true if identifiers match.
SemaphoreIdentifierCref | getIdentifier (void) const
| Return a reference to this AbstractSemaphore identifier.
SemaphoreGroupIdentifierCref | getGroupIdentifier (void) const
| Returns a reference to the SemaphoreGroup identifier.
Int | getValue (void)
| Returns the current value of the semaphore.
Int | getInitialValue (void)
| Retrieves the initial value for a semaphore.
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

| GatewaySemaphore (void) throw ( Assertion )
| Default construct throws assert.
| throw (Assertion)
| Copy constructor throws assertion.
GatewaySemaphoreRef | operator= (GatewaySemaphoreCref) throw ( Assertion )
| Assignment operator throws assertion.
SemaphoreOperationStatus | lockAndAdd (ThreadIdentifierRef aTid, Int aFlag=0)
Protected Member Functions inherited from corelinux::Semaphore
| throw (Assertion)
| Default constructor throws assertion.
| throw (Assertion)
| Copy constructor throws assertion.
SemaphoreRef | operator= (SemaphoreCref) throw (Assertion)
| Assignment operator throws assertion.
CounterCref | operator++ (void)
| Operator for increasing theRecursionQueueLength.
CounterCref | operator-- (void)
| Operator for decreasing theRecursionQueueLength.
virtual ThreadIdentifierRef | getOwnerId (void)
| Returns a reference to the owning thread.
virtual void | setOwnerId (void)
| Sets the owner id to the current thread.
virtual void | setRecursionQueueLength (Counter)
| Sets the recursion length.
virtual void | resetOwnerId (void)
| Sets the owner thread id to not owned.
Protected Member Functions inherited from corelinux::AbstractSemaphore
| throw (Assertion)
AbstractSemaphoreRef | operator= (AbstractSemaphoreCref) throw (Assertion)
SemaphoreIdentifierRef | getId (void)
| Returns a reference to the AbstractSemaphore identifier.
Int | getGroupId (void) const
| Returns a reference to the group identifier.
SemaphoreOperationStatus | setLock (Int)
| Calls kernel lock mechanism.
SemaphoreOperationStatus | setUnlock (Int)
| Calls kernel unlock mechanism.
SemaphoreOperationStatus | waitZero (Int)
| Calls kernel zero mechanism.
SemaphoreOperationStatus | setValue (Int)
| Sets the value for the AbstractSemaphore.
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...

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

GatewaySemphore enables a depth of resource indicator.

Unlike the tradition boolean semaphore (locked,unlocked), this type assumes a finite number of threads/processes can be granted access up to theResourceMaximum. The semantics regarding semaphore and recursion in relationship to the GatewaySemaphore is as follows:

With recursion enabled:

- Semaphore::getOwningThreadIdentifier returns the ThreadIdentifier of the thread that pushed the value to zero(0).
- Semaphore::getRecursionQueueLength returns the depth of recursion by Semaphore::getOwningThreadIdentifier
- GatewaySemaphore::isAnOwner returns true if the current thread is in the set of threads that own a resource.
- GatewaySemaphore::getOwnerRecursionQueueLength returns either -1 if the current thread does not control a resource, 0 if the current thread does own a resource, but has not recursed, or returns the depth of recursion for the calling thread.

## Constructor & Destructor Documentation

corelinux::GatewaySemaphore::GatewaySemaphore | ( | SemaphoreGroupPtr | aGroup,
|  | SemaphoreIdentifierRef | aIdentifier,
|  | Count | aValue,
|  | bool | Recursive = `false`,
|  | bool | Balking = `false`
| ) |  |
throw | ( | NullPointerException
| ) |  |

Default constructor requires the identifier of the semaphore in the semaphore group and a count of resources for control.

Parameters

  SemaphoreGroupPtr | The owning SemaphoreGroup
  SemaphoreIdentifier | The identifier for the Semaphore from the SemaphoreGroup
  Count | number of resources the semaphore controls
  bool | true if recursion enabled
  bool | true if balking enabled

## Member Function Documentation

Counter corelinux::GatewaySemaphore::getOwnerRecursionQueueLength | ( | void |  | ) |

virtual

Returns the recursion depth for the calling thread.

Returns
  Counter -1 if not an owner, 0 if owner but not recursed, or > 0 for recursion depth.

References corelinux::Thread::getThreadIdentifier(), and isAnOwner().

SemaphoreOperationStatus corelinux::GatewaySemaphore::release | ( | void |  | ) |
throw | ( | SemaphoreException
| ) |  |

virtual

Request the AbstractSemaphore but timeout if not available.

Release the lock

Implements corelinux::AbstractSemaphore.

References corelinux::Semaphore::getOwnerId(), corelinux::Thread::getThreadIdentifier(), corelinux::Semaphore::isRecursionEnabled(), corelinux::Semaphore::resetOwnerId(), corelinux::AbstractSemaphore::setUnlock(), corelinux::SUCCESS, and corelinux::UNAVAILABLE.

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

- GatewaySemaphore.hpp
- GatewaySemaphore.cpp

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