DosRequestMutexSem
From EDM2
DosRequestMutexSem blocks until ownership of a mutex semaphore may be obtained. Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner.
Syntax
DosRequestMutexSem( hmtxSemaphore, ulTimeOut )
Parameters
- HMTX hmtxSemaphore (input)
- The handle of the semaphore to be released.
- 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 free.
- Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained.
Returns
- APIRET rc
- The following values can be returned
0 | NO_ERROR | Successfully obtained semaphore ownership |
6 | ERROR_INVALID_HANDLE | Error, The value in phmtxSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question |
95 | ERROR_INTERRUPT | Error, The thread has become unblocked by an external event such as an exception, ownership has not been obtained |
103 | ERROR_TOO_MANY_SEM_REQUESTS | Error, The semaphore usage count system limit, of 65535, has been exceeded |
105 | ERROR_SEM_OWNER_DIED | Error, The semaphore owner has died without releasing the semaphore |
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 |
Gotchas
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.
Sample Code
#define INCL_DOSSEMAPHORES #include <os2.h> HMTX hmtxMySemaphore; /* 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 DosCreateMutexSem ... */ /* ... or by DosOpenMutexSem */ /* its handle is placed in hmtxMySemaphore */ rc = DosRequestMutexSem(hmtxMySemaphore, TimeOut); if (rc != 0) { /* We got an error to take care of. */ }