DosMuxSemWait

Bindings:  C, MASM 

This call blocks a current thread until one of the specified semaphores is 
cleared. 

 DosMuxSemWait     (IndexNbr, ListAddr, Timeout) 
 

 IndexNbr (PUSHORT) - output 
    Address of the index number of the semaphore in the list of semaphores 
    that satisfies the wait request. 

 ListAddr (PVOID) - input 
    Address of the structure for list of descriptors that define the 
    semaphores to be waited on. 

    semcount (USHORT) 
       Number of semaphores. 

    sementry (MUXSEM) 
       Array of MUXSEM structures: 

       reserved (USHORT) 
          Reserved; must be zero. 

       hsem (HSEM) 
          Reference to the semaphore. 

          For a system semaphore, this reference is the handle returned by 
          a DosCreateSem or DosOpenSem request that granted the requesting 
          thread access to the semaphore. 

          For a RAM semaphore, this reference is the address of a 
          doubleword of storage, allocated and initialized to zero by the 
          application. This sets the semaphore as unowned. Other than 
          initializing the doubleword to zero, an application must not 
          modify a RAM semaphore directly; instead it manipulates the 
          semaphore with semaphore function calls. 

 Timeout (LONG) - input 
    Action taken by the requesting thread when none of the semaphores in 
    the list is available.  The values that can be specified are: 

    Value     Definition 
      -1      The requesting thread waits indefinitely for a semaphore to 
              be cleared. 
      0       The requesting thread returns immediately. 
    > 0       The requesting thread waits the indicated number of 
              milliseconds for a semaphore to be cleared before resuming 
              execution. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    95        ERROR_INTERRUPT 
    101       ERROR_EXCL_SEM_ALREADY_OWNED 
    121       ERROR_SEM_TIMEOUT 
    151       ERROR_INVALID_EVENT_COUNT 
    152       ERROR_TOO_MANY_MUXWAITERS 
    153       ERROR_INVALID_LIST_FORMAT 
 
 Remarks 

 DosMuxSemWait checks a semaphore list.  If any of the semaphores are 
 clear, DosMuxSemWait returns.  If all are set, DosMuxSemWait blocks until 
 one of the semaphores is cleared or until the time out occurs. 

 Unlike other semaphore calls that block (DosSemRequest, DosSemWait, and 
 DosSemSetWait), DosMuxSemWait is an edge-triggered, rather than a 
 level-triggered, procedure.  This means it returns whenever one of the 
 semaphores on the list is cleared, regardless of how long that semaphore 
 may remain clear.  It is possible the semaphore may be reset before 
 DosMuxSemWait returns. If a semaphore is cleared and then set prior to 
 the thread's executing the DosMuxSemWait call, the event is lost.  Events 
 are only effective while a thread is in a DosMuxSemWait call. 

 This implementation allows DosMuxSemWait to be used in conjunction with 
 one or more semaphores as a triggering or synchronizing device.  One or 
 more threads can call DosMuxSemWait for a particular semaphore. When an 
 event occurs, another thread can clear the semaphore and then immediately 
 set it again, arming it for the next event.  Threads that were waiting on 
 that semaphore return from DosMuxSemWait and resume execution.