DosSemRequest
Bindings: C, MASM
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:
0 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.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs