Class: TCountingSemaphore

Declaration: CountingSemaphore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TGlobalCountingSemaphoreHandle TLocalCountingSemaphore

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). This class provides the abstract base for classical counting semaphores.

Instantiation:

This class is an abstract base class hence creation not allowed.

Deriving Classes:

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

Derived classes are supposed to provide the actual implementation.

Member Function: TCountingSemaphore::TCountingSemaphore

TCountingSemaphore (long count =0)

Interface Category:

API.

Purpose:

Constructor constructs the semaphore.

Calling Context:

Called by the derived class constructors only.

Parameters:

Return Value:

None.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

After construction the count of the semaphore is set to value of 'count'. This constructor can only be invoked by the derived class constructors.

Member Function: TCountingSemaphore::~TCountingSemaphore

virtual ~ TCountingSemaphore ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TCountingSemaphore::P

  1. virtual void P ()
  2. virtual void P (const TTime & aTimeOut)

Interface Category:

API.

Purpose:

  1. Tries to decrement the count on the semaphore, waits if count is zero.
  2. Tries to decrement the count on the semaphore, waits for specified time if count is zero. Upon timeout throws an exception TTimeOutException::kTimeExpired.

Calling Context:

  1. Called to receive a signal or decrement the count.
  2. Called to receive a signal or decrement the count within certain time bound.

Parameters:

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if semaphore is being deleted. Throws TSemaphoreException(TTimeOutException::kTimeExpired) if operation times out.

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TCountingSemaphore::Decrement

  1. void Decrement ()
  2. void Decrement (const TTime & aTimeOut)

Interface Category:

API.

Purpose:

  1. Name alias to operation P.
  2. XName alias to operation P with timeout.

Calling Context:

  1. Called to receive a signal or decrement the count.
  2. Called to receive a signal or decrement the count within certain time bound.

Parameters:

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if semaphore is being deleted. Throws TTimeOutException(TTimeOutException::kTimeExpired) if operation times out.

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TCountingSemaphore::TryP

virtual bool TryP ()

Interface Category:

API.

Purpose:

Tries to receive a signal or decrement the count, but doesn't wait if the count is zero.

Calling Context:

Called to receive a signal or decrement the count, without having to wait.

Parameters:

Return Value:

Returns true if successfully decremented the count, false otherwise.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TCountingSemaphore::TryDecrement

bool TryDecrement ()

Interface Category:

API.

Purpose:

Name alias to TryP.

Calling Context:

Tries to receive a signal or decrement the count, but doesn't wait if the count is zero.

Parameters:

Return Value:

Returns true if successfully decremented the count, false otherwise.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TCountingSemaphore::V

virtual void V ()

Interface Category:

API.

Purpose:

Provides an operation to send a signal or to increment the count.

Calling Context:

Called to send a signal or to increment the count.

Parameters:

Return Value:

None.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

Any waiting threads are woken up in FIFO order.

Member Function: TCountingSemaphore::Increment

void Increment ()

Interface Category:

API.

Purpose:

Name alias to operation V.

Calling Context:

Called to send a signal or to increment the count.

Parameters:

Return Value:

None.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

Any waiting threads are woken up in FIFO order.

Member Function: TCountingSemaphore::GetCount

virtual long GetCount () const

Interface Category:

API.

Purpose:

Provides a means of finding out the current count.

Calling Context:

Called to get the value of the semaphore count.

Parameters:

Return Value:

Current count at the time of the call.

Exceptions:

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

Concurrency:

The count value is not safe to use, because of the concurrent access to the semaphore by multiple threads.

Other Considerations:

The value returned from this operation may not safe to use.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.