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.

	GatewaySemaphore (GatewaySemaphoreCref) 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
	Semaphore (void) throw (Assertion)
	Default constructor throws assertion.

	Semaphore (SemaphoreCref) 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
	AbstractSemaphore (AbstractSemaphoreCref) 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