DosWaitMuxWaitSem
DosWaitMuxWaitSem blocks until the specified muxwait semaphore clears.
Contents
Syntax
DosWaitMuxWaitSem( hmuxSemaphore, ulTimeOut, pulUserField )
Parameters
- HEV hevSemaphore (input)
- The handle of the semaphore to block on.
- ULONG ulTimeout (input)
- The number of milliseconds the function will wait before
returning.
- 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:
| 0 | NO_ERROR | Operation successful |
| 6 | ERROR_INVALID_HANDLE | Error, The value in phmuxSemaphore does not point to a valid
semaphore |
| 8 | ERROR_NOT_ENOUGH_MEMORY | Error, The system memory limit has been exceeded |
| 87 | ERROR_INVALID_PARAMETER | Error, One or more parameters is not recognized, See parameters above, Both pszSemaphoreName and phmuxSemaphore may be NULL |
| 95 | ERROR_INTERRUPT | Error, The thread has become unblocked by an external event such as an exception |
| 103 | ERROR_TOO_MANY_SEM_REQUESTS | Error |
| 105 | ERROR_SEM_OWNER_DIED | Error, The owner of a mutex semaphore in the muxwait list has died
without freeing the semaphore |
| 286 | ERROR_EMPTY_MUXWAIT | Error, The MuxWait semaphore hmuxSemaphore is empty |
| 287 | ERROR_MUTEX_OWNED | Error, A mutex semaphore in the muxwait list is currently owned |
| 292 | ERROR_WRONG_TYPE | Error |
| 640 | ERROR_TIMEOUT | Error, The caller was blocked for ulTimeout milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired |
Usage Explanation
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.
Gotchas
The process calling DosWaitMuxWaitSem 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 a PM thread, WinWaitMuxWaitSem should be used instead of DosWaitMuxWaitSem. This will allow the message queue thread to continue processing.
Sample Code
#define INCL_DOSSEMAPHORES
#include <os2.h>
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 */
/* access is gained to the semaphore in question */
/* either by DosCreateEventSem ... */
/* ... or by DosOpenEventSem */
/* its handle is placed in hevMySemaphore */
rc = DosWaitMuxWaitSem(hevMySemaphore, TimeOut,&ulUserField);
if (rc != 0)
{
/* We got an error to take care of. */
}
