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;
}

Related Functions

• WinPostMsg
• WinSendMsg