WinRequestMutexSem

Syntax

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