WinWaitMuxWaitSem

Syntax

rc = WinWaitMuxWaitSem( 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_WINMESSAGEMGR
#include <os2.h>

Usage Explanation

WinWaitMuxWaitSem blocks until the specified muxwait semaphore clears. 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.

WinWaitMuxWaitSem is intended to be used in Presentation Manager applications in place of the DosWaitMuxWaitSem counterpart to avoid hanging the PM Message Queue.

Gotchas

The process calling WinWaitMuxWaitSem 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 not a PM thread, DosWaitMuxWaitSem should be used instead of WinWaitMuxWaitSem.

Sample Code

 
#define INCL_WINMESSAGEMGR
#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 */
APIRET rc;                 /* return code */

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

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

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

See Also

DosAddMuxWaitSem, DosCloseMuxWaitSem, DosCreateMuxWaitSem, DosDeleteMuxWaitSem, DosOpenMuxWaitSem, DosQueryMuxWaitSem, DosWaitMuxWaitSem