Class: TSemaphore

Declaration: CountingSemaphore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TLocalSemaphore TRecoverableSemaphoreHandle

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). TSemaphore is an abstract class which defines the protocol for semaphores. It is derived by TLocalSemaphore and TRecoverableSemaphore.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes TLocalSemaphore and TRecoverableSemaphore provide real implementation for clients.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TSemaphore::TSemaphore

TSemaphore ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and derived class constructors.

Parameters:

long count =0 -Initial count on the semaphore.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

After construction the semaphore is in free state. This constructor is invoked only from the derived class constructors.

Member Function: TSemaphore::~TSemaphore

virtual ~ TSemaphore ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSemaphore::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(TTimeOutException::kTimeExpired) if specified time expires.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSemaphore::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(TTimeOutException::kTimeExpired) if specified time expires.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSemaphore::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 no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

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

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