DosSemSetWait

This call sets a semaphore if the semaphore is not already set and waits until another thread clears the semaphore with a DosSemClear call.

DosSemSetWait

(SemHandle, Timeout)

SemHandle (HSEM) - input

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 the semaphore is set. The values that can be specified are:

Value

Definition
-1
The requesting thread waits indefinitely for the semaphore to be cleared.
0
The requesting thread returns immediately.
> 0
The requesting thread waits the indicated number of milliseconds for the 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
  103
  ERROR_TOO_MANY_SEM_REQUESTS
  121
  ERROR_SEM_TIMEOUT
  Remarks

  DosSemSetWait combines the functions of DosSemSet and DosSemWait and is used when there is a chance the semaphore may be be cleared by a thread that gets an intervening time slice between calls by the current thread to set the semaphore and wait until it is cleared.

  A DosSemSetWait request differs from a DosSemWait request in that it ensures that the semaphore is set so that it can block on it. Issuing DosSemWait on a semaphore that has been cleared has no effect. Instead of blocking, the caller continues to execute.

  The unblocking of a thread blocked by a DosSemSetWait is level-triggered. That is, DosSemSetWait does not return until the semaphore remains clear long enough for the affected thread to be redispatched and determine that the semaphore is clear.

  DosSemSetWait cannot be issued against a system semaphore owned by another thread unless the NoExclusive option was selected on the DosCreateSem request that created the semaphore.

  ---

  [Back: DosSemSet]
  [Next: DosSemWait]