API FOR ADVANCED USERS – This class defines a condition variable. More...

#include <ilserver/ilthread.h>

Inheritance diagram for IlsCond:

Public Member Functions
	IlsCond (IlsUnsafeMutex *=0)
	Constructor. More...

void	broadcast ()
	This member function is used to release the threads that are currently waiting for the condition variable. More...

IlsWaitResult	wait (IlsCondTestFunc=0, IlsAny=0, long timeout_millisecs=-1L)
	This member function is used to block the current thread on the condition variable. More...

Public Member Functions inherited from IlsMTBase
virtual	~IlsMTBase ()
	This is the public virtual destructor for this class.

virtual IlsThreadObjectName	getName () const
	This member function returns the name of an object. More...

Friends
ostream &	operator<< (ostream &, const IlsCond &)

Detailed Description

API FOR ADVANCED USERS – This class defines a condition variable.

Library: server
and mvcomp

A condition variable allows multiple threads to wait for a condition and to be released when the condition is true. The testing of the condition is handled by the application. All the waiting threads are released by means of the broadcast() member function.

See also: IlsBarrier, ILS_CUT_DIRECTIVE, IlsSafeMutex, IlsUnsafeMutex.

Constructor & Destructor Documentation

◆ IlsCond()

IlsCond::IlsCond ( IlsUnsafeMutex * = 0 )

Constructor.

It is possible to provide the mutex that the condition variable should use internally in the constructor. In this case, it is the responsibility of the application to lock the mutex before calling any member functions of the condition variable, and to unlock the mutex when the member function returns.

You should use this mutex when you want to modify data that is logically associated with the condition variable. For example, if you want to set the value of an integer to zero before calling the method wait() and then test the value of the integer after the condition variable has been broadcasted, you must provide your own mutex and lock it before accessing the integer. In this case, the condition variable will guarantee that unlocking the mutex and calling the function wait() or broadcast() are atomic operations so that there are no possible race conditions. Failing that, it might happen that one of the other threads modifies the value of the integer in between the unlocking of the mutex and the call to the function wait() or broadcast(), which could break the integrity of the application.

Member Function Documentation

◆ broadcast()

void IlsCond::broadcast ( )

This member function is used to release the threads that are currently waiting for the condition variable.

It must be called by the application. It is not called under any circumstances by the thread library.

◆ wait()

IlsWaitResult IlsCond::wait	(	IlsCondTestFunc	= `0`,
		IlsAny	= `0`,
		long	timeout_millisecs = `-1L`
	)

This member function is used to block the current thread on the condition variable.

The current thread remains blocked until a different thread calls the broadcast() method or until the method times out if a timeout is provided.

This function takes an optional predicate function which can be used to test an application condition in order to decide whether the wait() member function should unblock or continue to block. The call of the predicate function is protected by the mutex associated with the condition variable. If the predicate function returns IlsFalse, the thread will reblock until the next broadcast. For example, you can use the predicate function to allow only a certain number of waiting threads to unblock. In this case, the predicate function tests an application condition and, if required, returns IlsFalse so that the thread reblocks until the next broadcast. If no predicate function is provided, all threads waiting for the condition variable are unblocked every time the broadcast() function is called.

This member function can be called with a timeout. If the timeout is positive, the function will wait the number of milliseconds requested before returning ILS_WAIT_TIMEOUT unless the function broadcast() is called in the meantime. The return value ILS_WAIT_OK means that the condition variable was acquired by the current thread.

Friends And Related Function Documentation

◆ operator<<

ostream& operator<<	(	ostream &	,
		const IlsCond &
	)

friend

This operator prints the name of the object to the output stream.

This uses the method getName() to get the name of the condition variable. If the method getName() returns 0 then it uses a platform dependent value.

Public Member Functions

Friends