Class: TRecoverableSemaphoreHandle

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. TRecoverableSemaphoreHandle are used to synchronize threads across different tasks. They provide a higher-overhead acquire than TLocalSemaphores, but add protocol for recovering the semaphore state when a thread dies.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

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

Concurrency:

Multithread safe.

Resource Use:

These objects should not be created in shared memory and shared across address spaces. Only way to share the semaphores across address spaces is by streaming then out and streaming them in.

Member Function: TRecoverableSemaphoreHandle::TRecoverableSemaphoreHandle

TRecoverableSemaphoreHandle ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and called by the client code.

Parameters:

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(TGeneralKernelException::kBadArgument) if the count is less than zero. Throws TGeneralKernelException(TGeneralKernelException::kInsufficientMemory) if system runs out of resources.

Concurrency:

Multithread safe.

Other Considerations:

After construction the semaphore is in free state. These objects should not be created in shared memory and shared across address spaces. Only way to share the semaphores across address spaces is by streaming then out and streaming them in. These objects are reference counted when created the underlying semaphore gets a reference count of 1, there on any stream-in operation increments the count, and destructor decrements the count. When the count reaches zero the semaphore is destroyed.

Member Function: TRecoverableSemaphoreHandle::~TRecoverableSemaphoreHandle

virtual ~ TRecoverableSemaphoreHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws TSemaphoreException(TSemaphoreException::kIllegallyAcquiredSemaphoreHandle) if the semaphore handle was not acquired by streaming it in or creating it.

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: TRecoverableSemaphoreHandle::Acquire

  1. void Acquire ()
  2. void Acquire (const TTime & maximumTime)

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(TGeneralKernelException::kInsufficientMemory) if system runs out of resources. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore. 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: TRecoverableSemaphoreHandle::AcquireShared

  1. void AcquireShared ()
  2. void AcquireShared (const TTime & maximumTime)

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(TGeneralKernelException::kInsufficientMemory) if system runs out of resources. Throws TSemaphoreException(TSemaphoreException::kInvalidSemaphore) if the handle does not refer to any real semaphore. 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: TRecoverableSemaphoreHandle::Release

void Release ()

Interface Category:

API.

Purpose:

Releases the semaphore.

Calling Context:

Called to relinquish the semaphore lock held by the client.

Parameters:

Return Value:

None.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

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

Member Function: TRecoverableSemaphoreHandle::SetRecovered

void SetRecovered ()

Interface Category:

API.

Purpose:

Sets the recovered status on the semaphore.

Calling Context:

Called to re-enable semaphore acquires after a thread has died while holding a read/write lock.

Parameters:

Return Value:

None.

Exceptions:

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

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TRecoverableSemaphoreHandle::Destroy

void Destroy ()

Interface Category:

API.

Purpose:

Removes the semaphore.

Calling Context:

Called to destroy the semaphore, usually after a thread has died while holding a read/write lock and the state cannot be reset.

Parameters:

Return Value:

None.

Exceptions:

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

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.

Member Function: TRecoverableSemaphoreHandle::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 threads are waiting to acquire the semaphore.

Parameters:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TRecoverableSemaphoreHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TRecoverableSemaphoreHandle::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

Return Value:

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

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.
Copyright©1995 Taligent,Inc. All rights reserved.