Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosMuxSemWait(pisemCleared, pmsxl, lTimeOut)
PUSHORT pisemCleared;   /* pointer to variable for cleared semaphore      */
PVOID pmsxl;            /* pointer to structure containing semaphore list */
LONG lTimeOut;          /* time-out value                                 */
 
The DosMuxSemWait function waits for one or more of the specified semaphores
to clear. The function first checks the semaphores specified in the list
pointed to by the pmsxl parameter. If any of the semaphores in this list are
clear, the function returns. Otherwise, the function waits until the time
specified by the lTimeOut parameter elapses or until one of the semaphores
in the list clears.
 
The semaphore list can contain up to 16 semaphores.
 
Parameter     Description
────────────────────────────────────────────────────────────────────────────
 
pisemCleared  Points to the variable that receives the index number of the
              most recently cleared semaphore.
 
pmsxl         Points to the MUXSEMLIST structure containing a semaphore list
              that defines the semaphores to be cleared. The semaphore list
              consists of one or more semaphore handles.
 
lTimeOut      Specifies how long to wait for the semaphores to become
              available. If the value is greater then zero, this parameter
              specifies the number of milliseconds to wait before returning.
              If it is SEM_IMMEDIATE_RETURN, the function returns
              immediately. If it is SEM_INDEFINITE_WAIT, the function waits
              indefinitely.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_EXCL_SEM_ALREADY_OWNED
     ERROR_INTERRUPT
     ERROR_INVALID_EVENT_COUNT
     ERROR_INVALID_LIST_FORMAT
     ERROR_SEM_TIMEOUT
     ERROR_TOO_MANY_MUXWAITERS
 
Comments
 
Although it is declared with the PVOID type, the second parameter of the
DosMuxSemWait function must point to a MUXSEMLIST structure. You can create
the structure by using the DEFINEMUXSEMLIST macro.
 
Unlike the other blocking semaphore functions (DosSemRequest, DosSemSetWait
and DosSemWait), DosMuxSemWait returns whenever one of the semaphores on its
list is cleared, regardless of how long that semaphore may remain cleared.
It is possible that the semaphore could be reset before the DosMuxSemWait
function returns.
 
The DosMuxSemWait function does not set or claim any of the semaphores.
 
The DosMuxSemWait function can be used in conjunction with one or more
semaphores as a triggering or synchronizing device. One or more threads can
use DosMuxSemWait to wait for a semaphore. When an event occurs, another
thread can clear that semaphore and immediately set it again. Any threads
that waited for that semaphore by using DosMuxSemWait will return. Threads
that were waiting by using one of the "level-triggered" functions
(DosSemRequest, DosSemSetWait, or DosSemWait) may or may not resume,
depending on the scheduler's dispatch order and the activity of other
threads in the system.
 
Example
 
This example creates a structure of system semaphore handles for use by the
DosMuxSemWait function. It sets the first element of the structure to the
number of handles stored and creates two semaphore handles. It then calls
DosMuxSemWait to wait until one of the semaphores is cleared. It uses the
value of the usSemIndex parameter to find out which semaphore is cleared,
and if it is semaphore 1, the example sets that semaphore.
 
DEFINEMUXSEMLIST(MuxList, 2)         /* creates structure array */
USHORT usSemIndex;
MuxList.cmxs = 2;
DosCreateSem(CSEM_PUBLIC, &MuxList.amxs[0].hsem,
    "\\sem\\timer0.sem");
DosCreateSem(CSEM_PUBLIC, &MuxList.amxs[1].hsem,
    "\\sem\\timer1.sem");
    .
    .
    .
DosMuxSemWait(&usSemIndex, &MuxList, 5000L);
if (usSemIndex == 1) {
    DosSemSet(MuxList.amxs[1].hsem);
 
See Also
 
DosCreateSem, DosSemRequest, DosSemSet, DosSemSetWait, DosSemWait,
WinMsgMuxSemWait, DEFINEMUXSEMLIST, MUXSEMLIST
 
                                      ♦