WinWaitMuxWaitSem
This function waits for a muxwait semaphore to clear or for a Presentation Manager message.
Syntax
WinWaitMuxWaitSem(hmux, ulTimeout, pulUser);
Parameters
- hmux (HMUX) - input
- The handle of the muxwait semaphore to wait for.
- ulTimeout (ULONG) - input
- Time-out in milliseconds.
- This is the maximum amount of time the user wants to allow the thread to be blocked.
- SEM_IMMEDIATE_RETURN (0): WinWaitMuxWaitSem returns without blocking the calling thread.
- SEM_INDEFINITE_WAIT (-1): WinWaitMuxWaitSem blocks the calling thread indefinitely.
- pulUser (PULONG) - output
- Pointer to receive the user field.
- A pointer to receive the user field (from the muxwait semaphore data structure) of the semaphore that was posted or released.
- If DCMW_WAIT_ANY was specified in the flAttr parameter when the muxwait semaphore was created, this will be the user field of the semaphore that was posted or released. If the muxwait semaphore consists of mutex semaphores, any mutex semaphore that is released is owned by the caller.
- If DCMW_WAIT_ALL was specified in the flAttr parameter when the muxwait semaphore was created, this will be the user field of the last semaphore that was posted or released. (If the thread did not block, the last semaphore that was posted or released will also be the last semaphore in the muxwait-semaphore list.) If the muxwait semaphore consists of mutex semaphores, all of the mutex semaphores that are released are owned by the caller.
Returns
- ulrc (APIRET) - returns
- Return Code.
- 0: NO_ERROR
- 6: ERROR_INVALID_HANDLE
- 8: ERROR_NOT_ENOUGH_MEMORY
- 87: ERROR_INVALID_PARAMETER
- 95: ERROR_INTERRUPT
- 103: ERROR_TOO_MANY_SEM_REQUESTS
- 105: ERROR_SEM_OWNER_DIED
- 286: ERROR_EMPTY_MUXWAIT
- 287: ERROR_MUTEX_OWNED
- 292: ERROR_WRONG_TYPE
- 640: ERROR_TIMEOUT
Errors
Possible returns from WinGetLastError
- 0 (NO_ERROR)
- Successful completion.
- 6 (ERROR_INVALID_HANDLE)
- An invalid handle was specified.
- 8 (ERROR_NOT_ENOUGH_MEMORY)
- Not enough memory was available.
- 87 (ERROR_INVALID_PARAMETER)
- An invalid parameter was specified.
- 95 (ERROR_INTERRUPT)
- The call was interrupted.
- 103 (ERROR_TOO_MANY_SEM_REQUESTS)
- Too many semaphore requests were made.
- 105 (ERROR_SEM_OWNER_DIED)
- The semaphore owner died.
- 286 (ERROR_EMPTY_MUXWAIT)
- The muxwait semaphore list was empty.
- 287 (ERROR_MUTEX_OWNED)
- The mutex semaphore is already owned.
- 292 (ERROR_WRONG_TYPE)
- The semaphore type was incorrect.
- 640 (ERROR_TIMEOUT)
- The call timed out.
Remarks
WinWaitMuxWaitSem is similar to DosWaitMuxWaitSem and enables a thread to wait for a muxwait semaphore to clear or for a window message sent by the WinSendMsg function from another thread to be received.
This function can be issued by any thread in the process that created the semaphore. Threads in other processes can also issue this function, but they must first gain access to the semaphore by issuing DosOpenMuxWaitSem.
Since the processing of a window message may take longer than the value specified by the ulTimeout parameter, this function may not return within the time specified by that value.
If the main thread (which normally processes messages) is waiting on a semaphore for a prolonged period of time, messages will not be processed, and the "Bad App" dialog can occur. This is expected behavior. To avoid this, a message-box can be displayed telling the user that the window is being initialized. While the window loads, that message box can process the incoming system messages.
Example Code
Declaration:
#define INCL_WINMESSAGEMGR #include <os2.h> HMUX hmux; /* The handle of the muxwait semaphore to wait for. */ ULONG ulTimeout; /* Time-out in milliseconds. */ PULONG pulUser; /* Pointer to receive the user field. */ APIRET ulrc; /* Return Code. */ ulrc = WinWaitMuxWaitSem(hmux, ulTimeout, pulUser);
This example waits for a muxwait semaphore to clear. The handle of the semaphore is assumed to be in hmux. The ulTimeout is the number of milliseconds that the calling thread will wait for the muxwait semaphore to clear. If the specified muxwait semaphore is not cleared during this time interval, the request times out.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#define INCL_WINMESSAGEMGR
#include <os2.h>
#include <stdio.h>
#ifndef ERROR_TIMEOUT
#define ERROR_TIMEOUT 640
#define ERROR_INTERRUPT 95
#endif
HMUX hmux; /* Muxwait semaphore handle */
ULONG ulTimeout; /* Number of milliseconds to wait */
ULONG ulUser; /* User field for the semaphore that was posted or released (returned) */
ULONG rc; /* Return code */
ulTimeout = 60000; /* Wait for a maximum of 1 minute */
rc = WinWaitMuxWaitSem(hmux, ulTimeout, &ulUser);
/* On successful return, the ulUser variable contains the user identifier of the semaphore that caused the wait to terminate. */
/* If the caller had to wait for all the semaphores within the muxwait semaphore to clear, then the value corresponds to the last semaphore within the muxwait semaphore to clear. */
/* If the caller had to wait for any semaphore with the muxwait semaphore to clear, then the value corresponds to that semaphore. */
if (rc == ERROR_TIMEOUT)
{
printf("WinWaitMuxWaitSem call timed out\n");
return;
}
if (rc == ERROR_INTERRUPT)
{
printf("WinWaitMuxWaitSem call was interrupted\n");
return;
}
if (rc != 0)
{
printf("WinWaitMuxWaitSem error: return code = %ld\n", rc);
return;
}