A condition variable is an object able to block the calling thread until notified to resume. More...

#include <piconditionvar.h>

Public Member Functions
void	notifyOne ()
	Unblocks one of the threads currently waiting for this condition. If no threads are waiting, the function does nothing. If more than one, it is unspecified which of the threads is selected.

void	notifyAll ()
	Unblocks all threads currently waiting for this condition. If no threads are waiting, the function does nothing.

virtual void	wait (PIMutex &lk)
	see wait(PIMutex &, const std::function<bool()>&)

virtual void	wait (PIMutex &lk, const std::function< bool()> &condition)
	Wait until notified. More...

virtual bool	waitFor (PIMutex &lk, PISystemTime timeout)
	see waitFor(PIMutex &, int, const std::function<bool()>&)

virtual bool	waitFor (PIMutex &lk, PISystemTime timeout, const std::function< bool()> &condition)
	Wait for timeout or until notified. More...

Detailed Description

A condition variable is an object able to block the calling thread until notified to resume.

It uses a PIMutex to lock the thread when one of its wait functions is called. The thread remains blocked until woken up by another thread that calls a notification function on the same PIConditionVariable object.

Member Function Documentation

◆ wait()

void PIConditionVariable::wait	(	PIMutex &	lk,
		const std::function< bool()> &	condition
	)

virtual

Wait until notified.

The execution of the current thread (which shall have locked with lk method PIMutex::lock()) is blocked until notified.

At the moment of blocking the thread, the function automatically calls lk.unlock() (PIMutex::unlock()), allowing other locked threads to continue.

Once notified (explicitly, by some other thread), the function unblocks and calls lk.lock() (PIMutex::lock()), leaving lk in the same state as when the function was called. Then the function returns (notice that this last mutex locking may block again the thread before returning).

Generally, the function is notified to wake up by a call in another thread either to member notifyOne() or to member notifyAll(). But certain implementations may produce spurious wake-up calls without any of these functions being called. Therefore, users of this function shall ensure their condition for resumption is met.

If condition is specified, the function only blocks if condition returns false, and notifications can only unblock the thread when it becomes true (which is specially useful to check against spurious wake-up calls).

Parameters

lk	lock object used by method wait for data protection
condition	A callable object or function that takes no arguments and returns a value that can be evaluated as a bool. This is called repeatedly until it evaluates to true.

◆ waitFor()

bool PIConditionVariable::waitFor	(	PIMutex &	lk,
		PISystemTime	timeout,
		const std::function< bool()> &	condition
	)

virtual

Wait for timeout or until notified.

The execution of the current thread (which shall have locked with lk method PIMutex::lock()) is blocked during timeout, or until notified (if the latter happens first).

At the moment of blocking the thread, the function automatically calls lk.lock() (PIMutex::lock()), allowing other locked threads to continue.

Once notified or once timeout has passed, the function unblocks and calls lk.unlock() (PIMutex::unlock()), leaving lk in the same state as when the function was called. Then the function returns (notice that this last mutex locking may block again the thread before returning).