DosFSRamSemRequest
Bindings: C, MASM
This call obtains a Fast-Safe (FS) RAM semaphore and records the current
owner for potential cleanup by a DosExitList routine.
DosFSRamSemRequest (FSRamSemStructure, Timeout)
FSRamSemStructure (PDOSFSRSEM) - input
Address of the FS RAM Semaphore data structure. The content of this
structure is:
fs_Length (USHORT)
Length in bytes of the FSRamSemStructure; 14 is the only valid
value.
fs_ProcID (PID)
Owning process ID; 0 means the semaphore is not owned.
fs_ThrdID (TID)
Owning thread ID; 0 means the semaphore is not owned.
fs_UseCount (USHORT)
Use count. The number of times the owning thread has issued
DosFSRamSemRequest without issuing a corresponding
DosFSRamSemClear.
fs_Client (USHORT)
Is a 16-bit pattern used by the owner of a semaphore to record
maintenance information about the resource managed by the
semaphore.
fs_RAMSem (ULONG)
The RAM semaphore data structure used in this request.
Before the initial call to DosFSRamSemRequest, this entire
structure must be initialized to zero and its length set to 14.
Other than fs_Client, the caller should not modify any fields in
this structure.
Timeout (LONG) - input
The number of milliseconds to wait for the semaphore to be cleared
before resuming execution. The meaning of the specified values are:
Value Definition
-1 The requestor waits indefinitely when the semaphore is
owned. There is no time out.
0 There is an immediate return if the semaphore is owned.
>0 The value is the number of milliseconds to wait, if the
semaphore is owned.
rc (USHORT) - return
Return code descriptions are:
0 NO_ERROR
121 ERROR_SEM_TIMEOUT
Remarks
When DosFSRamSemRequest is called, it checks the status of the semaphore.
If it is unowned, then DosFSRamSemRequest sets it owned, increments
fs_UseCount, and returns immediately to the caller.
If the semaphore is owned, the caller has the option to block until the
semaphore is no longer owned. The unblocking of a DosFSRamSemRequest is
"level triggered" because it does not actually return unless the
semaphore remains clear until the affected thread can be redispatched to
claim it successfully. The Timeout parameter can be used to place an
upper bound on the amount of time to block before returning, even though
the semaphore remains owned.
When the thread is done with the protected resource, it calls
DosFSRamSemClear. DosFSRamSemClear decrements fs_UseCount. Recursive
requests for FS RAM semaphores are supported by the use count, which
keeps track of the number of times the owner has issued a
DosFSRamSemRequest without a corresponding DosFSRamSemClear. If the call
to DosFSRamSemClear decrements the use count to zero, the semaphore is
set unowned, and any threads that were blocked waiting for the semaphore
resume execution.
The 16-bit field fs_Client is not interpreted by the FS RAM semaphore
calls. Instead, it provides the caller with a means of identifying the
resource being accessed by the owner of the semaphore. This field is
initialized to zero when a FS RAM semaphore is first acquired. The owner
may place values into this field that describe the resource. These values
can be used by an exit list handler to determine the appropriate cleanup
action.
When a process terminates while owning a FS RAM semaphore, any routines
in the exit list maintained by DosExitList are given control. These
routines take appropriate steps to guarantee the integrity of resources
owned by the process. To clean up a resource protected by a FS RAM
semaphore, DosFSRamSemRequest is called to gain ownership of the
semaphore. When issued during exit list processing , DosFSRamSemRequest
examines the semaphore to determine if the semaphore is owned by the
active process. It then forces the owning thread ID to be equal to the
current thread ID and sets
fs_Count = 1. This allows the exit list routine to be programmed without
any FS RAM semaphore handling instructions. When the exit list routine
has completed its operations, it restores the resource for use by others
by issuing DosFSRamSemClear.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs