ts::GuardCondition Class Reference

Automatic guard class for synchronization condition (ts::Condition). More...

Classes
class	GuardConditionError
	Fatal low-level condition guard error. More...

Public Member Functions
	GuardCondition (Mutex &mutex, Condition &condition, MilliSecond timeout=Infinite)
	Constructor, automatically acquire the mutex with a timeout. More...
virtual	~GuardCondition ()
	Destructor, automatically release the mutex.
bool	isLocked () const
	Check if the mutex was actually locked. More...
void	signal ()
	Signal the condition. More...
bool	waitCondition (MilliSecond timeout=Infinite)
	Wait for the condition to be signaled with a timeout. More...

Detailed Description

Automatic guard class for synchronization condition (ts::Condition).

This class implements the guard design pattern for conditions. See ts::Guard for other usages of the guard design pattern.

Example (writer thread):

Mutex mutex;
Condition condition;
...
{
    GuardCondition guard(mutex, condition); // mutex acquired
    ...
    // do some modification on shared data
    ...
    guard.signal(); // notify other threads
    ...
} // mutex released

Example (reader thread):

// use same  mutex and condition
...
{
    GuardCondition guard(mutex, condition); // mutex acquired
    ...
    while (!expected_shared_data_state) {
        guard.waitCondition();
    }
    ...
    // use shared data
    ...
} // mutex released

Constructor & Destructor Documentation

GuardCondition()

ts::GuardCondition::GuardCondition	(	Mutex &	mutex,
		Condition &	condition,
		MilliSecond	timeout = Infinite
	)

Constructor, automatically acquire the mutex with a timeout.

The user has to invoke isLocked() to check that the mutex was actually acquired before the timeout expired.

Parameters

[in,out]	mutex	A reference on the mutex object to acquire.
[in,out]	condition	A reference on the condition to wait or signal.
[in]	timeout	Maximum number of milliseconds to wait for the mutex.

Exceptions

ts::GuardCondition::GuardConditionError

Thrown whenever an error occurs during the acquisition of the mutex. Exceeding the timeout is not error, the object is successfully constructed but isLocked() will return false.

Member Function Documentation

isLocked()

bool ts::GuardCondition::isLocked ( ) const

inline

Check if the mutex was actually locked.

This method is useful only with the object was constructed with a non-infinite timeout.

Returns

True if the mutex was successfully acquired and false if the timeout expired.

signal()

void ts::GuardCondition::signal

(

)

Signal the condition.

If more than one thread wait for the condition, at least one is awaken. It is then the responsibility of the awaken threads to check that the expected situation actually exists.

Exceptions

ts::GuardCondition::GuardConditionError

Thrown whenever an error occurs or if the mutex was not locked (the constructor with timeout was used and the timeout expired before the mutex was acquired).

waitCondition()

bool ts::GuardCondition::waitCondition

(

MilliSecond

timeout = Infinite

)

Wait for the condition to be signaled with a timeout.

The mutex is automatically released while waiting and then automatically re-acquired before returning.

Parameters

[in]

timeout

Maximum number of milliseconds to wait for the mutex.

Returns

True when the condition was signaled, false if the timeout expired before the condition was signaled.

Exceptions

ts::GuardCondition::GuardConditionError

Thrown whenever an error occurs or if the mutex was not locked (the constructor with timeout was used and the timeout expired before the mutex was acquired).

---

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

• tsGuardCondition.h