DosWaitEventSem
From EDM2
DosWaitEventSem blocks until the specified event semaphore is posted. Event semaphores are edge-triggered. This means that if the semaphore is posted and reset before a waiting thread has a chance to run, the waiting thread will still act as though the semaphore is posted.
Syntax
DosWaitEventSem( hevSemaphore, ulTimeOut )
Parameters
- HEV hevSemaphore (input)
- The handle of the semaphore wait 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.
Returns
- APIRET rc
- The following values can be returned:
0 | NO_ERROR | Successfully waited for the event semaphore to be posted to |
6 | ERROR_INVALID_HANDLE | Error, The value in phevSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question |
8 | ERROR_NOT_ENOUGH_MEMORY | Error, The system memory limit has been exhausted |
95 | ERROR_INTERRUPT | Error, The thread has become unblocked by an external event such as an exception, ownership has not been obtained |
640 | ERROR_TIMEOUT | Error, The caller was blocked for ulTimeout milliseconds but no post was issued within this time limit, Time has expired |
Gotchas
The process calling DosWaitEventSem 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, WinWaitEventSem should be used instead of DosWaitEventSem. This will allow the message queue thread to continue processing.
Sample Code
#define INCL_DOSSEMAPHORES #include <os2.h> HEV hevMySemaphore; /* MySemaphore handle */ ULONG TimeOut= -1; /* the number of milliseconds the */ /* the caller will block for the sem */ /* this example will block forever */ /* access is gained to the semaphore in question */ /* either by DosCreateEventSem ... */ /* ... or by DosOpenEventSem */ /* its handle is placed in hevMySemaphore */ rc = DosWaitEventSem(hevMySemaphore, TimeOut); if (rc != 0) { /* We got an error to take care of. */ }
See Also
DosCloseEventSem, DosCreateEventSem, DosOpenEventSem, DosPostEventSem, DosQueryEventSem, DosResetEventSem, WinWaitEventSem