Class: TLocalSemaphore

Declaration: CountingSemaphore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSemaphore

Inherited By:

None.

Purpose:

WARNING: Do not directly #include CountingSemaphore.h in any of your files. It is included in this version of the CommonPoint application system for internal implementation. It will be removed in future versions (and the public classes it contains will be moved to other public headers). A concrete derived class of TSemaphore. TLocalSemaphores are used to synchronize threads within the same task. They provide low-overhead (fast) acquires operations when the semaphore is available.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes would likely not override the member functions of TLocalSemaphore. Derived classes should add additional protocol in their constructors and through additional member functions.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

When constructed the semaphore is in free state. This object should not be shared across address spaces.

Member Function: TLocalSemaphore::TLocalSemaphore

TLocalSemaphore ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and to create a usable semaphore.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(TGeneralKernelException::kBadArgument) if the count is less than zero.

Concurrency:

Multithread safe.

Other Considerations:

When constructed the semaphore is in free state. This object should not be shared across address spaces.

Member Function: TLocalSemaphore::~TLocalSemaphore

virtual ~ TLocalSemaphore ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if the semaphore is being deleted.

Concurrency:

Multithread safe.

Other Considerations:

Destructors wakes up all the waiting threads and the thread so awakened throws a TSemaphoreException::kSemaphoreDeleted exception. This operation may block.

Member Function: TLocalSemaphore::Acquire

virtual void Acquire ()
virtual void Acquire (const TTime & maximumTime)

Interface Category:

API.

Purpose:

Acquires the semaphore in restricted mode, without a timeout.
Acquires the semaphore in restricted mode, with a timeout.

Calling Context:

Called when the client desires read/write access to the resource protected by the semaphore.
Called when the client desires read/write access to the resource protected by the semaphore.

Parameters:

Takes no parameters.
const TTime & maximumTime -The maximum amount of time to wait for the semaphore.

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if the semaphore is being deleted. Throws TSemaphoreException(TTimeOutException::kTimeExpired) if specified time expires.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TLocalSemaphore::AcquireShared

virtual void AcquireShared ()
virtual void AcquireShared (const TTime & maximumTime)

Interface Category:

API.

Purpose:

Acquires the semaphore in shared mode, without a timeout.
Acquires the semaphore in shared mode, with a timeout.

Calling Context:

Called when the client desires read-only access to the resource protected by the semaphore.
Called when the client desires read-only access to the resource protected by the semaphore.

Parameters:

Takes no parameters.
const TTime & maximumTime -The maximum amount of time to wait for the semaphore.

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if the semaphore is being deleted. Throws TSemaphoreException(TTimeOutException::kTimeExpired) if specified time expires.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TLocalSemaphore::Release

virtual void Release ()

Interface Category:

API.

Purpose:

Releases the semaphore.

Calling Context:

Called to relinquish the semaphore lock held by the client.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the semaphore is invalid. Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if the semaphore is being deleted.

Concurrency:

Multithread safe.

Other Considerations:

Wakes up any waiting threads in FIFO order, also alternates between readers and writers.

Member Function: TLocalSemaphore::AnyThreadsWaiting

virtual bool AnyThreadsWaiting () const

Interface Category:

API.

Purpose:

Determines if there are any threads waiting to acquire the semaphore.

Calling Context:

Called to determine whether or not threads are waiting to acquire the semaphore.

Parameters:

Takes no parameters.

Return Value:

Returns true if there are threads waiting to acquire the semaphore. Otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.