DosWaitMuxWaitSem

From EDM2
Jump to: navigation, search

DosWaitMuxWaitSem blocks until the specified muxwait semaphore clears.

Syntax

rc = DosWaitMuxWaitSem( hmuxSemaphore,
                        ulTimeOut,
                        pulUserField );

Parameters

HEV hevSemaphore (input)
The handle of the semaphore to block on.
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 posted.
  • Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore is posted.
PULONG pulUserField (output)
A pointer to a ULONG that will contain the value of the user field from the SEMRECORD structure. If the MuxWait semaphore was created with the

DCMW_WAIT_ALL flag, this will contain the user field of the last semaphore that was posted or released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY flag, this will contain the user field of the semaphore that was posted or released. If the thread did not block, this will contain the user field of the last semaphore in the MuxWait list.

Returns

APIRET rc

The following values can be returned

0 NO_ERROR Operation

successful

6 ERROR_INVALID_HANDLE Error, The value in phmuxSemaphore does not point to a valid

semaphore

8 ERROR_NOT_ENOUGH_MEMORY Error, The system memory limit has been exceeded
87 ERROR_INVALID_PARAMETER Error, One or more parameters is not recognized, See parameters above,

Both pszSemaphoreName and phmuxSemaphore may be NULL

95 ERROR_INTERRUPT Error,

The thread has become unblocked by an external event such as an exception

103 ERROR_TOO_MANY_SEM_REQUESTS Error
105 ERROR_SEM_OWNER_DIED Error, The owner of a mutex semaphore in the muxwait list has died

without freeing the semaphore

286 ERROR_EMPTY_MUXWAIT Error, The MuxWait semaphore hmuxSemaphore is empty
287 ERROR_MUTEX_OWNED Error, A mutex semaphore in the muxwait list is currently owned
292 ERROR_WRONG_TYPE Error
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

MuxWait semaphores are edge triggered. This means that if a muxwait semaphore consists of a number of event semaphores and all have posted except for one, if one of the semaphores resets before the last hold-out posts then it will need to wait for the reset semaphore to post again.

If the MuxWait semaphore consists of mutex semaphores and was created with the DCMW_WAIT_ALL attribute, the process obtains ownership of all mutex semaphores only when all semaphores have been released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY attribute, the process obtains ownership of the first mutex semaphore to release.

Gotchas

The process calling DosWaitMuxWaitSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.

If the thread to be blocked, waiting on an event semaphore, is a PM thread, WinWaitMuxWaitSem should be used instead of DosWaitMuxWaitSem. This will allow the message queue thread to continue processing.

Sample Code

 
#define INCL_DOSSEMAPHORES
#include 

HMUX  hmuxMySemaphore;     /* MySemaphore handle */
ULONG TimeOut= -1;         /* the number of milliseconds the */
                           /* the caller will block for the sem */
                           /* this example will block forever */
ULONG ulUserField;         /* to be filled with useful info */

	/* access is gained to the semaphore in question */
	/* either by DosCreateEventSem ... */
	/* ... or by DosOpenEventSem */
	/* its handle is placed in hevMySemaphore */

	rc = DosWaitMuxWaitSem(hevMySemaphore, TimeOut,&ulUserField);

	if (rc != 0)
	{
	  /* We got an error to take care of. */
	}

See Also