DosRequestMutexSem

From EDM2
Jump to: navigation, search

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. */
	}

See Also