DosRequestMutexSem: Difference between revisions

Revision as of 15:39, 5 December 2016

Syntax

rc = 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

Include Info

#define INCL_DOSSEMAPHORES
#include <os2.h>

Usage Explanation

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.

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 

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