ItomSharedSemaphore Class Reference

semaphore which can be used for asychronous thread communication. By using this class it is possible to realize timeouts. More...

Public Member Functions
	ItomSharedSemaphore (int numberOfListeners=1)
	constructor More...
	~ItomSharedSemaphore ()
	destructor (do not call directly, instead free the semaphore by ItomSharedSemaphore::deleteSemaphore
bool	wait (int timeout)
	The call of this method returns if a certain timeout has been expired or every listener released the semaphore.
bool	waitAndProcessEvents (int timeout, QEventLoop::ProcessEventsFlags flags=QEventLoop::AllEvents)
	The call of this method returns if a certain timeout has been expired or every listener released the semaphore. More...
void	release ()
	decreases the number of locks by one
int	available () const
	checks whether the semaphore is still locked or not
bool	isCallerStillWaiting ()
	indicates whether caller-method is still waiting that the lock is released by the listener(s).
void	deleteSemaphore (void)
	static method to decrease the reference counter of any ItomSharedSemaphore or delete it if the reference counter drops to zero

Public Attributes
ito::RetVal	returnValue

Private Attributes
QSemaphore *	m_pSemaphore
int	m_instCounter
bool	m_enableDelete
int	m_numOfListeners
bool	m_callerStillWaiting
QMutex	internalMutex

Detailed Description

semaphore which can be used for asychronous thread communication. By using this class it is possible to realize timeouts.

This semaphore is usually applied if any method invokes another method in another thread and should wait for the called method being terminated or the waiting routine drops into a possible timeout. Therefore, the calling method must create an instance of ItomSharedSemaphore with a number of listeners equal to one. Then, the pointer to ItomSharedSemaphore is transmitted to the called method (usually as last argument). If the called method is done or wants the caller to continue the release-method of ItomSharedSemaphore is called. The calling method calls the wait-method of the semaphore which blocks the method until the semaphore is released. Finally, both the caller and the calling method must call ItomSharedSemaphore::deleteSemaphore in order to decrease the reference counter from two to zero, which allows the system to delete the semaphore.

Consider to guard an instance of ItomSharedSemaphore by the capsule-class ItomSharedSemaphoreLocker both in the caller and calling method, such that the decrease of the reference counter is executed if the ItomSharedSemaphoreLocker-variables are deleted, e.g. if they run out of scope, which is even after the return-command of any method.

Constructor & Destructor Documentation

ItomSharedSemaphore::ItomSharedSemaphore ( int  numberOfListeners = 1 )

inline

constructor

A new ItomSharedSemaphore is created and the underlying semaphore is already locked with a certain number. This number depends on the number of listeners (usually: 1). A listener is a method which is called in another thread. The caller creates the ItomSharedSemaphore in order to wait until the listener decreases the lock level of the semaphore by one or a certain timout time has been reached.

Parameters

[in]

numberOfListeners

(default: 1) are the number of different methods in other threads which should release this semaphore before the caller can go on.

Member Function Documentation

bool ItomSharedSemaphore::waitAndProcessEvents	(	int	timeout,
		QEventLoop::ProcessEventsFlags	flags = QEventLoop::AllEvents
	)

The call of this method returns if a certain timeout has been expired or every listener released the semaphore.

mutex initialization

The call of this method returns if a certain timeout has been expired or every listener released the semaphore.

Member Data Documentation

QMutex ItomSharedSemaphore::internalMutex

private

static mutex internally used for protecting some commands

bool ItomSharedSemaphore::m_callerStillWaiting

private

true if caller is still waiting, false if caller finished or run into a timeout

bool ItomSharedSemaphore::m_enableDelete

private

helper member variable avoiding that this instance is deleted directly by "delete"-keyword

int ItomSharedSemaphore::m_instCounter

private

counts how many instances are remaining, which are still participating at this wait condition

int ItomSharedSemaphore::m_numOfListeners

private

number of called methods (listeners) in different threads. Every listener must release this semaphore before it is finally unlocked.

QSemaphore* ItomSharedSemaphore::m_pSemaphore

private

underlying instance of QSemaphore. This semaphore is created and destructed in the constructor and destructor respectively.

ito::RetVal ItomSharedSemaphore::returnValue

public returnValue member variable of ItomSharedSemaphore. This return value can be used to return the result of any called method (listener) to the caller. Please access this value in caller only if the wait-method returned with true. Write to returnValue in called method (listener) before releasing the semaphore. This is important, since the returnValue is not fully thread safe.

---

The documentation for this class was generated from the following files:

• C:/itom/sources/itom/common/sharedStructuresQt.h
• C:/itom/sources/itom/common/sources/sharedStructuresQt.cpp