WinWaitMuxWaitSem

Syntax
WinWaitMuxWaitSem( hmuxSemaphore, ulTimeOut, pulUserField )

Parameters
returning.
 * HEV hevSemaphore (input):The handle of the semaphore to block on.
 * ULONG ulTimeout (input):The number of milliseconds the function will wait before
 * Set to SEM_IMMEDIATE_RETURN (0), the function will return immediately regardless of whether or not the semaphore is posted.
 * Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore is posted.


 * PULONG pulUserField (output):A pointer to a ULONG that will contain the value of the user field from the SEMRECORD structure. If the MuxWait semaphore was created with the DCMW_WAIT_ALL flag, this will contain the user field of the last semaphore that was posted or released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY flag, this will contain the user field of the semaphore that was posted or released. If the thread did not block, this will contain the user field of the last semaphore in the MuxWait list.

Returns

 * APIRET rc:The following values can be returned:

Usage Explanation
WinWaitMuxWaitSem blocks until the specified muxwait semaphore clears. MuxWait semaphores are edge triggered. This means that if a muxwait semaphore consists of a number of event semaphores and all have posted except for one, if one of the semaphores resets before the last hold-out posts then it will need to wait for the reset semaphore to post again.

If the MuxWait semaphore consists of mutex semaphores and was created with the DCMW_WAIT_ALL attribute, the process obtains ownership of all mutex semaphores only when all semaphores have been released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY attribute, the process obtains ownership of the first mutex semaphore to release.

WinWaitMuxWaitSem is intended to be used in Presentation Manager applications in place of the DosWaitMuxWaitSem counterpart to avoid hanging the PM Message Queue.

Gotchas
The process calling WinWaitMuxWaitSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned. If the thread to be blocked, waiting on an event semaphore, is not a PM thread, DosWaitMuxWaitSem should be used instead of WinWaitMuxWaitSem.

Sample Code

 * 1) define INCL_WINMESSAGEMGR
 * 2) include 

HMUX hmuxMySemaphore;     /* MySemaphore handle */ ULONG TimeOut= -1;        /* the number of milliseconds the */ /* the caller will block for the sem */ /* this example will block forever */ ULONG ulUserField;        /* to be filled with useful info */ APIRET rc;                /* return code */

/* access is gained to the semaphore in question */ /* either by DosCreateEventSem ... */	/* ... or by DosOpenEventSem */ /* its handle is placed in hevMySemaphore */

rc = WinWaitMuxWaitSem(hevMySemaphore, TimeOut,&ulUserField);

if (rc != 0) {	 /* We got an error to take care of. */	}