WinRequestMutexSem

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.

• 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

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.

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 

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