Class: TGlobalCountingSemaphoreHandle

Declaration: CountingSemaphore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TCountingSemaphore

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). Provides a concrete class with counting semaphore features, for use across a multiple address spaces.

Instantiation:

Allocate on the local heap or the stack.

Deriving Classes:

None.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TGlobalCountingSemaphoreHandle::TGlobalCountingSemaphoreHandle

TGlobalCountingSemaphoreHandle (long count =0)

Interface Category:

API.

Purpose:

Constructor constructs the semaphore handle.

Calling Context:

Called by the derived class constructors as well as client code.

Parameters:

Return Value:

None.

Exceptions:

Throws 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. Constructor constructs a handle to the real semaphore. To share this semaphore use streaming. Whenever a handle is constructed the underlying semaphore gets a reference count of one, and the operation of sharing using stream-in operator increments the reference count. Any handle destructor call decrements the reference count on the semaphore. When the count reaches zero the semaphore is destroyed.

Member Function: TGlobalCountingSemaphoreHandle::~TGlobalCountingSemaphoreHandle

virtual ~ TGlobalCountingSemaphoreHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy the handle to the global counting semaphore handle.

Parameters:

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kIllegallyAcquiredSemaphoreHandle) if the semaphore handled was not created using the constructor, or the stream-in operation.

Concurrency:

Multithread safe.

Other Considerations:

The handle objects are reference counted against the underlying real semaphore. Thus calling the destructor operation may not destroy the real semaphore if there are outstanding handles to that semaphore.

Member Function: TGlobalCountingSemaphoreHandle::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 TTimeOutException(TTimeOutException::kTimeExpired) if operation times out. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TGlobalCountingSemaphoreHandle::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. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

Concurrency:

Multithread safe.

Other Considerations:

Member Function: TGlobalCountingSemaphoreHandle::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. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

Concurrency:

Multithread safe.

Other Considerations:

Any waiting threads are woken up in FIFO order.

Member Function: TGlobalCountingSemaphoreHandle::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. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

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.

Member Function: TGlobalCountingSemaphoreHandle::operator<<=

TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in the semaphore handle.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if there is a version mismatch while streaming in.

Concurrency:

Multithread safe.

Other Considerations:

Streaming in is the only way to share the semaphore across address spaces.

Member Function: TGlobalCountingSemaphoreHandle::operator>>=

TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out the handle to some semaphore.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

Concurrency:

Multithread safe.

Other Considerations:

Streaming out is only way to let other address space share this semaphore.

Member Function: TGlobalCountingSemaphoreHandle::Destroy

void Destroy ()

Interface Category:

API.

Purpose:

To destroy the real semaphore.

Calling Context:

Called to destroy the semaphore.

Parameters:

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kSemaphoreDeleted) if semaphore is being deleted. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore.

Concurrency:

Multithread safe.

Other Considerations:

Destroy operation wakes up all the waiting threads. This operation may cause the waiting threads to get exception TSemaphoreException::kSemaphoreDeleted. Any new operation that gets initiated on this semaphore also gets the TSemaphoreException::kSemaphoreDeleted exception. This operation may block.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.