CYIWaitCondition Class Reference

Detailed Description

A class used to block a thread until a condition is met, as signaled by a different thread.

This class is used to perform synchronization between threads. The typical usage is that one or more threads 'wait' on the condition, and a different thread signals one or more of the waiters to wake up.

When waiting on a wait conditions, threads are expected to have a mutex locked. When a thread 'waits' on a wait condition, the mutex is unlocked automatically, and re-locked when a different thread calls 'wake' (or when a timeout is reached).

Sample usage:

{
   CYIMutex m_myMutex;
   CYIWaitCondition m_myCondition;
   std::vector<CYIString> m_items;
}

Thread 1 (consumer):

{
   while (true)
   {
       m_myMutex.Lock();
       while(m_items.size() == 0) // while loop for spurious wakeup protection
       {
           m_myCondition.Wait(m_myMutex);
       }
       ProcessItems(m_items);
       my_myMutex.Unlock();

       // (Do other things that don't require the mutex to be locked)
   }
}

Thread 2 (producer):

{
   m_myMutex.Lock();
   m_items.push_back("An Item");
   m_myMutex.Unlock();

   m_myCondition.WakeOne();
}

#include <thread/YiWaitCondition.h>

Public Member Functions
	CYIWaitCondition ()
virtual	~CYIWaitCondition ()
bool	Wait (CYIMutex &rMutex)
bool	Wait (CYIMutex &rMutex, uint64_t timeoutMs)
bool	WakeAll ()
bool	WakeOne ()

Constructor & Destructor Documentation

CYIWaitCondition::CYIWaitCondition

(

)

virtual CYIWaitCondition::~CYIWaitCondition ( )

virtual

Member Function Documentation

bool CYIWaitCondition::Wait

(

CYIMutex &

rMutex

)

Waits on this condition until a different thread calls WakeOne or WakeAll.

The mutex rMutex must be locked by the current thread prior to this function. While waiting, the mutex will be automatically unlocked, and will be re-locked when this function returns.

Note

It is also possible for this function to return without a different thread calling WakeOne or WakeAll. This is known as a spurious wakeup.

bool CYIWaitCondition::Wait	(	CYIMutex &	rMutex,
		uint64_t	timeoutMs
	)

Waits on this condition until a different thread calls WakeOne or WakeAll, or until timeoutMs milliseconds have elapsed.

The mutex rMutex must be locked by the current thread prior to this function. While waiting, the mutex will be automatically unlocked, and will be re-locked when this function returns.

Note

It is also possible for this function to return without a different thread calling WakeOne or WakeAll, and before the timeout has been reached. This is known as a spurious wakeup.

bool CYIWaitCondition::WakeAll

(

)

Causes all threads waiting on this condition to be awoken. Has no effect if no threads are currently waiting on this wait condition.

Note

It is not necessary for the calling thread to have the associated mutex locked.

bool CYIWaitCondition::WakeOne

(

)

Causes a single thread waiting on this condition to be awoken. There is no specified ordering to which thread is selected to be awoken. Has no effect if no threads are currently waiting on this wait condition.

Note

It is not necessary for the calling thread to have the associated mutex locked.

---

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

• thread/YiWaitCondition.h