[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

WinRequestMutexSem

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

rc = WinRequestMutexSem( 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.

Returns

APIRET rc
The following values can be returned
0NO_ERRORSuccessfully obtained semaphore ownership
6ERROR_INVALID_HANDLEError, The value in phmtxSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question
95ERROR_INTERRUPTError, The thread has become unblocked by an external event such as an exception, ownership has not been obtained
103ERROR_TOO_MANY_SEM_REQUESTSError, The semaphore usage count system limit, of 65535, has been exceeded
105ERROR_SEM_OWNER_DIEDError, The semaphore owner has died without releasing the semaphore
640ERROR_TIMEOUTError, The caller was blocked for ulTimeout milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired

Include Info

#define INCL_WINMESSAGEMGR
#include <os2.h>

Usage Explanation

WinRequestMutexSem 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.

WinRequestMutexSem is intended to be used in Presentation Manager applications rather than the DosRequestMutexSem counterpart to avoid hanging the PM Message Queue.

Relevant Structures

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_WINMESSAGEMGR #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 */ APIRET rc; /* return code */ /* access is gained to the semaphore in question */ /* either by DosCreateMutexSem ... */ /* ... or by DosOpenMutexSem */ /* its handle is placed in hmtxMySemaphore */ rc = WinRequestMutexSem(hmtxMySemaphore, TimeOut); if (rc != 0) { /* We got an error to take care of. */ }

See Also

DosCloseMutexSem, DosCreateMutexSem, DosOpenMutexSem, DosQueryMutexSem, DosReleaseMutexSem, DosRequestMutexSem

Author

Joe Phillips - jaiger@eng2.uconn.edu

Additions

Last modified October 19/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

WinRequestMutexSem