DosMuxSemWait

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:
• 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.

  ---

  [Back: DosMove]
  [Next: DosNewSize]