DosSemRequest

This call obtains a semaphore and sets the semaphore as owned by the thread that requested it.

DosSemRequest

(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 owned by another thread. 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
  100
  ERROR_TOO_MANY_SEMAPHORES
  105
  ERROR_SEM_OWNER_DIED
  121
  ERROR_SEM_TIMEOUT
  Remarks

  Typically, DosSemRequest is called to set a semaphore for the purpose of accessing a protected resource. DosSemRequest checks the status of the semaphore. If the semaphore is not set (that is, not owned) by another thread, DosSemRequest sets the semaphore as owned by the current thread and returns immediately to the caller.

  If the semaphore is already owned by another thread, DosSemRequest optionally can block the requesting thread until the semaphore becomes available. The unblocking of a thread blocked by a DosSemRequest is level-triggered. That is, DosSemRequest does not return until the semaphore remains clear long enough for the affected thread to be redispatched and successfully claim the semaphore. Thus, if a number of threads are blocked indefinitely on DosSemRequest calls for the semaphore, only the thread that sets the semaphore is actually unblocked. If a milliseconds value is specified for the Timeout parameter, this places an upper limit on the amount of time the requesting thread remains blocked, waiting for the semaphore to become available.

  When a thread no longer requires the protected resource, it issues DosSemClear to clear the semaphore, so another thread may claim it with a successful DosSemRequest. If the semaphore is an exclusive system semaphore, it has a use count associated with it, which is incremented by a DosSemRequest and decremented by a DosSemClear. The semaphore is not actually cleared and made available to the next thread that wants to access the resource until the semaphore has been cleared the same number of times it has been requested. This means that exclusive system semaphores can be used in recursive routines. When the use count is 0, the semaphore is available to be claimed by the next user of the protected resource.

  If a process terminates while owning a nonexclusive system semaphore, ERROR_SEM_OWNER_DIED is returned to the thread that next gets the semaphore through DosSemRequest. That thread takes steps to ensure the integrity of the resource. The thread can release the resource by issuing a DosSemClear, or it can reset the ERROR_SEM_OWNER_DIED return code condition flagged in the semaphore data structure.

  Note: To request a Fast-Safe RAM semaphore, a thread calls DosFSRamSemRequest.

  ---

  [Back: DosSemClear]
  [Next: DosSemSet]