Easier Windows Event Multiplexing on Waiting for Multiple Objects

WaitForMultipleObjects returns a strangely cooked DWORD value that can have flags meaning error, time out, signaled or abandoned condition, as well as an index into a handle in the array that is passed to it. It is even worse, if you change the number of the event handles over time, because the returned index can change too even the event is signaled from the same handle.

In the latest May 2011 issue of MSDN Magazine, Alex Gimenez tries to create a wrapper class to mitigate the problem in his articleDynWaitList: ID-Based Windows Event Multiplexing. When a handle is added to a DynWaitList object, the client gets back a unique ID for the handle for the life of the DynWaitList object. When the Wait call returns, the client gets an ID instead of variably meaningless index for the handle that signaled. So the client is confident that the ID would exactly mean the corresponding event, even the actual handles in the DynWaitList object can change over time.

The solution is perfectly fine for the author’s purpose. But when I try to use it, I get a problem. Now for each event, I have two pieces of information that I need to maintain, the handle, and the ID. Aren’t they redundant? For example, if I know idEventBusArrive has signaled, I may still need to access hEventBusArrive, for example, to reset it. Isn’t it better if waiting returns directly hEventBusArrive for me?

Let’s have a further look at the return value of WaitForMultipleObjects. Obviously, the Windows API designer tries to pack at least two pieces of information in the 32-bit DWORD: waiting status (signaled, abandoned, timed out, or failed); and information of the actual handle in the handle array if relevant. Because a handle of type HANDLE (in fact, void*) takes 32-bit on Win32 and 64-bit on Win64, the designer was forced to used an index instead, which has a very limited range, 0 to 63 (Windows allows waiting for at most 64 handles in WaitForMultipleObjects).

In my point view, if WaitForMultipleObjects could return the offending event handle, it would be perfect. The function could have taken an extra pointer arguments, HANDL* pHandle to return the exact handle that either signaled or abandoned, and let the original return value DWORD to only indicate the waiting status. No index or ID required. What kind of ID would be better than the handle? None, because the HANDLE is simply the unique ID for the event.

With this idea in mind, it is then simple and easy to write my wrapper class for WaitForMultipleObjects. In fact, I would wrap up WaitForMultipleObjectsEx since it is a super set of WaitForMultipleObjects. Here is the class, MultipleObjectsWaiter (maybe MultipleObjectsWaitress is a better name):

  1 #include <windows.h>
  2 #include <vector>
  3 #include <algorithm>
  4 #include <utility>
  5 #include <cassert>
  6 
  7 class MultipleObjectsWaiter
  8 {
  9 public:
 10 	enum Status
 11 	{
 12 		Signaled = WAIT_OBJECT_0,
 13 		Abandoned = WAIT_ABANDONED_0,
 14 		TimedOut = WAIT_TIMEOUT,
 15 		Alerted = WAIT_IO_COMPLETION,
 16 		Failed = WAIT_FAILED,
 17 	};
 18 
 19 	typedef std::pair<Status, HANDLE> Result;
 20 
 21 public:
 22 	// if you know max handle count to be added, give the hint as a parameter
 23 	MultipleObjectsWaiter(size_t hintObjects = 0)
 24 	{
 25 		m_handles.reserve(hintObjects);
 26 	}
 27 
 28 	// add given handles if any.
 29 	MultipleObjectsWaiter(const HANDLE* handles, size_t count, size_t hintObjects = 0)
 30 	{
 31 		m_handles.reserve( hintObjects>count? hintObjects : count );
 32 		assert( count<=0 || handles );
 33 		for(size_t i=0; i<count; ++i)
 34 			Add( handles[i] );
 35 	}
 36 
 37 	// add handle to waiting list. 
 38 	// return false if handle already there or there are too many handles (array full).
 39 	bool Add(HANDLE handle)
 40 	{
 41 		assert(handle);
 42 		if( m_handles.end() != std::find(m_handles.begin(), m_handles.end(), handle) )
 43 			return false;	// handle already there.
 44 		if( m_handles.size() >= MAXIMUM_WAIT_OBJECTS ) // Windows limitation
 45 			return false;	// handle array full
 46 		m_handles.push_back(handle);
 47 		return true;
 48 	}
 49 
 50 	// remove a handle from the waiting list
 51 	// return false if handle not found
 52 	bool Remove(HANDLE handle)
 53 	{
 54 		assert(handle);
 55 		std::vector<HANDLE>::iterator it = std::find(m_handles.begin(), m_handles.end(), handle);
 56 		if( m_handles.end() == it )
 57 			return false;
 58 		m_handles.erase(it);
 59 		return true;
 60 	}
 61 
 62 	// Possible waiting conditions:
 63 	//   waiting for all 2 or more handles : bWaitAll == TRUE  and handle count >= 2;
 64 	//   waiting for at most 1 handle      : bWaitAll == FALSE or  handle count == 1;
 65 	// Possible return values:
 66 	//   (Signaled, handle) : the handle signaled, if waiting for at most 1 handle.
 67 	//   (Signaled, NULL)   : all handles signaled, if waiting for 2 or more handles.
 68 	//   (Abandoned,handle) : the handle abandoned ,if waiting for at most 1 handle.
 69 	//   (Abandoned,NULL)   : at least one handle abandoned, if waiting for 2 or more handles.
 70 	//   (TimedOut, NULL)   : timed out, any waiting condition.
 71 	//   (Alerted,  NULL)   : wait ended early due to I/O completion or APC, may happen only when bAlertable == TRUE.
 72 	//   (Failed,   NULL)   : wait failed, any waiting condition, or no handle to wait.
 73 	Result Wait(DWORD dwTimeoutMs = INFINITE, BOOL bWaitAll = FALSE, BOOL bAlertable = FALSE)
 74 	{
 75 		if( m_handles.size() > 0 )
 76 		{
 77 			DWORD rc = ::WaitForMultipleObjectsEx((DWORD)m_handles.size(), &m_handles.front(), bWaitAll, dwTimeoutMs, bAlertable);
 78 			if( rc >= WAIT_OBJECT_0 && rc < WAIT_OBJECT_0+m_handles.size() )
 79 				return Compose(Signaled, bWaitAll? NULL : m_handles[rc-WAIT_OBJECT_0]);
 80 			else if( rc >= WAIT_ABANDONED_0 && rc < WAIT_ABANDONED_0+m_handles.size() )
 81 				return Compose(Signaled, bWaitAll? NULL : m_handles[rc-WAIT_OBJECT_0]);
 82 			else if( rc == WAIT_TIMEOUT )
 83 				return Compose(TimedOut, NULL);
 84 			else if( rc == WAIT_IO_COMPLETION )
 85 				return Compose(Alerted, NULL);
 86 			else
 87 			{
 88 				assert( rc == WAIT_FAILED );
 89 				return Compose(Failed, NULL);
 90 			}
 91 		}
 92 		assert(false);	// no handles.
 93 		return Compose(Failed, NULL); // time critical, so return error instead of throw exception
 94 	}
 95 
 96 	// If you have to see all the handles...
 97 	const std::vector<HANDLE>& Handles() const { return m_handles; }
 98 
 99 private:
100 	Result Compose(Status s, HANDLE h) { return Result(s, h); }
101 private:
102 	std::vector<HANDLE>		m_handles;
103 };

The most important function is Wait. It returns in its results, a pair of Status and HANDLE, the exact two pieces of information we want from WaitForMultipleObjectsEx. The rest of the class is trivial, basically allowing you to add and remove handles from the waiting array.

A simple usage is like this:

  1 void foo()
  2 {
  3 	HANDLE hEventBusArrive  = ::CreateEvent(...);
  4 	HANDLE hEventTaxiArrive = ::CreateEvent(...);
  5 
  6 	MultipleObjectsWaiter waiter(2);
  7 	waiter.Add(hEventBusArrive);
  8 	waiter.Add(hEventTaxiArrive);
  9 	
 10 	// ...
 11 	BOOL bWaitAll = ...; 
 12 	DWORD dwTimeOutMs = ...;
 13 	BOOL bAlertable = ...;
 14 
 15 	MultipleObjectsWaiter::Result r = waiter.Wait(dwTimeOutMs, bWaitAll, bAlertable);
 16 	switch( r.first )
 17 	{
 18 	case MultipleObjectsWaiter::Signaled:
 19 		if( r.second==NULL )
 20 			; // both bus and taxi arrived.
 21 		else if( r.second==hEventBusArrive )
 22 			; // bus arrived
 23 		else if( r.second==hEventTaxiArrive )
 24 			; // taxi arrived
 25 		else
 26 			; // should not be here!
 27 		break;
 28 	case MultipleObjectsWaiter::Abandoned:
 29 		if( r.second==NULL )
 30 			; // at least 1 handle abandoned (wait for all)
 31 		else if( r.second==hEventBusArrive )
 32 			; // bus arrive event abandoned (not wait for all)
 33 		else if( r.second==hEventTaxiArrive )
 34 			; // taxi arrive event abandoned (not wait for all)
 35 		else
 36 			; // should not be here
 37 		break;
 38 	case MultipleObjectsWaiter::TimedOut: // timed out
 39 		break;
 40 	case MultipleObjectsWaiter::Alerted:  // alerted
 41 		break;
 42 	case MultipleObjectsWaiter::Failed:   // error
 43 		break;
 44 	default:
 45 		assert(false);
 46 	}
 47 }

Notice that everything about an event is the event handle, which is the only information used in processing the wait result. As long as the event handles such as hEventBusArrive and hEventTaxiArrive are up-to-date, which they should, the processing logic does not need to change even if you dynamically Add to or Remove from MultipleObjectsWaiter the handles.

In summary, MultipleObjectsWaiter does what WaitForMultipleObjects and WaitForMultipleObjectsEx should do: return the waiting status and the relevant object handle out of the handle array if applicable. It is therefore simpler, faster, and easier to use than DynWaitList.