Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosFSRamSemRequest(pdosfsrs, lTimeout)
PDOSFSRSEM pdosfsrs;    /* pointer to structure for semaphore */
LONG lTimeout;          /* time to wait for semaphore         */
 
The DosFSRamSemRequest function obtains a fast-safe RAM semaphore and
records the current owner for potential cleanup by a DosExitList function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
pdosfsrs   Points to the DOSFSRSEM structure containing information about a
           fast-safe RAM semaphore.
 
lTimeout   Specifies how long to wait for the semaphore to become available.
           If the value is greater then zero, this parameter specifies the
           number of milliseconds to wait before returning. If the value is
           SEM_IMMEDIATE_RETURN, the function returns immediately. If the
           value is SEM_INDEFINITE_WAIT, the function waits indefinitely.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value.
 
Comments
 
When the DosFSRamSemRequest function is called, it checks the status of the
semaphore. If the semaphore is not owned, DosFSRamSemRequest sets it to
owned, increases the use count, and returns immediately to the calling
function. If the semaphore is owned, DosFSRamSemRequest may block the thread
until the semaphore is not owned, then try again. The lTimeout parameter is
used to place an upper limit on the amount of time to block before
returning.
 
When the thread is finished with the protected resource, it calls the
DosFSRamSemClear function. DosFSRamSemClear decreases the use count and, if
the count is zero, sets the semaphore to unowned and starts any threads that
were blocked while waiting for the semaphore.
 
Recursive requests for fast-safe RAM semaphores are supported by a use count
of the number of times the owning process has issued a DosFSRamSemRequest
function without issuing a corresponding DosFSRamSemClear function.
 
The DosFSRamSemRequest function does not return unless the specified
semaphore remains clear long enough for the calling thread to obtain it.
 
Fast-safe RAM semaphores operate by using the DOSFSRSEM structure. Before
the initial call to the DosFSRamSemRequest function, this structure must be
initialized to zero and the cb field must be set to 14. The client field is
provided to allow the calling process a means of identifying which resource
is currently owned by the owner of the semaphore. This field is initialized
to zero when a fast-safe RAM semaphore is first acquired. The owning process
may use this field to describe the resource currently being accessed. The
values in the client field may be useful to an DosExitList function handler
in determining the appropriate cleanup action.
 
When a process terminates that owns a fast-safe RAM semaphore, the
DosExitList functions of that process (if any) will be given control. If
important resources are protected by fast-safe RAM semaphores, the
DosExitList function should call the DosFSRamSemRequest function to gain
ownership of these semaphores. When called during the processing of
DosExitList termination functions, the DosFSRamSemRequest function will
examine the indicated fast-safe RAM semaphore and, if it is owned by the
active process, force the identifier of the owning thread to be equal to the
identifier of the current thread and set the use count to one. This allows
the DosExitList function to be used without requiring any handling
instructions for fast-safe RAM semaphores. When the execution of the
DosExitList function is finished, it should call the DosFSRamSemClear
function.
 
Except for the client field, the calling process should not modify any
fields in the DOSFSRSEM structure after the DosFSRamSemRequest function
returns.
 
See Also
 
DosExitList, DosFSRamSemClear, DOSFSRSEM
 
                                      ♦