ItomSharedSemaphore - ReferenceΒΆ

class ItomSharedSemaphore

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.

Public Functions

ItomSharedSemaphore(int numberOfListeners = 1)

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
  • numberOfListeners -

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

~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)

mutex initialization

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

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 Members

ito::RetVal 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.