Difference between revisions of "DosFSRamSemRequest"
m (Ak120 moved page OS2 API:CPI:LEGACY:DosFSRamSemRequest to DosFSRamSemRequest) |
m |
||
(3 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | + | This call obtains a Fast-Safe (FS) RAM semaphore and records the current owner for potential cleanup by a [[DosExitList]] routine. | |
− | This call obtains a Fast-Safe (FS) RAM semaphore and records the current owner for potential cleanup by a DosExitList routine. | + | |
==Syntax== | ==Syntax== | ||
− | + | DosFSRamSemRequest (FSRamSemStructure, Timeout) | |
− | DosFSRamSemRequest | + | |
− | + | ||
− | + | ||
− | + | ||
==Parameters== | ==Parameters== | ||
− | ; FSRamSemStructure (PDOSFSRSEM) - input : Address of the FS RAM Semaphore data structure. The content of this structure is: | + | ;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_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_ProcID (PID) : Owning process 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_ThrdID (TID) : Owning thread ID; 0 means the semaphore is not owned. | + | :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. | |
− | 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: | ; 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: | ||
+ | :-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. | ||
− | |||
− | |||
− | |||
− | |||
==Return Code== | ==Return Code== | ||
− | + | ;rc (USHORT) - return:Return code descriptions are: | |
− | + | *0 - NO_ERROR | |
− | Return code descriptions are: | + | *121 - ERROR_SEM_TIMEOUT |
− | + | ||
− | * 0 | + | |
− | * 121 | + | |
==Remarks== | ==Remarks== | ||
Line 46: | Line 28: | ||
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. | 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. | + | 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. | 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 | + | 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. |
− | 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. | + | |
− | == | + | ==Bindings== |
− | === C | + | === C === |
<PRE> | <PRE> | ||
− | typedef struct _DOSFSRSEM { | + | typedef struct _DOSFSRSEM { /* dosfsrs */ |
− | USHORT cb; | + | USHORT cb; /* Length of this structure (bytes) */ |
− | PID pid; | + | PID pid; /* Process ID of owner or zero */ |
− | TID tid; | + | TID tid; /* Thread ID of owner or zero */ |
− | USHORT cUsage; | + | USHORT cUsage; /* Reference count */ |
− | USHORT client; | + | USHORT client; /* 16 bit field for use by owner */ |
− | ULONG sem; | + | ULONG sem; /* OS/2 Ram Semaphore */ |
} DOSFSRSEM; | } DOSFSRSEM; | ||
Line 70: | Line 52: | ||
USHORT rc = DosFSRamSemRequest(FSRamSemStructure, Timeout); | USHORT rc = DosFSRamSemRequest(FSRamSemStructure, Timeout); | ||
− | PDOSFSRSEM | + | PDOSFSRSEM FSRamSemStructure; /* Address of structure */ |
− | LONG | + | LONG Timeout; /* Timeout (in milliseconds) */ |
+ | USHORT rc; /* return code */ | ||
+ | </PRE> | ||
− | + | ===MASM=== | |
− | < | + | <PRE> |
− | + | DOSFSRSEM struc | |
+ | |||
+ | dosfsrs_cb dw ? ;length of this structure (bytes) | ||
+ | dosfsrs_pid dw ? ;Process ID of owner or zero | ||
+ | dosfsrs_tid dw ? ;Thread ID of owner or zero | ||
+ | dosfsrs_cUsage dw ? ;reference count | ||
+ | dosfsrs_client dw ? ;16 bit field for use by owner | ||
+ | dosfsrs_sem dd ? ;OS/2 Ram Semaphore | ||
+ | |||
+ | DOSFSRSEM ends | ||
+ | |||
+ | EXTRN DosFSRamSemRequest:FAR | ||
+ | INCL_DOSSEMAPHORES EQU 1 | ||
+ | |||
+ | PUSH@ OTHER FSRamSemStructure ;FS Ram Semaphore data structure | ||
+ | PUSH DWORD Timeout ;Timeout (in milliseconds) | ||
+ | CALL DosFSRamSemRequest | ||
− | + | Returns WORD | |
+ | </PRE> | ||
+ | ==Example== | ||
+ | This example requests a FS RAM semaphore. | ||
<PRE> | <PRE> | ||
#define INCL_DOSSEMAPHORES | #define INCL_DOSSEMAPHORES | ||
Line 100: | Line 103: | ||
TIME_OUT); /* Timeout */ | TIME_OUT); /* Timeout */ | ||
</PRE> | </PRE> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | [[Category: | + | [[Category:Dos16]] |
Latest revision as of 21:39, 25 January 2020
This call obtains a Fast-Safe (FS) RAM semaphore and records the current owner for potential cleanup by a DosExitList routine.
Syntax
DosFSRamSemRequest (FSRamSemStructure, Timeout)
Parameters
- 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:
- -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.
Return Code
- 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.
Bindings
C
typedef struct _DOSFSRSEM { /* dosfsrs */ USHORT cb; /* Length of this structure (bytes) */ PID pid; /* Process ID of owner or zero */ TID tid; /* Thread ID of owner or zero */ USHORT cUsage; /* Reference count */ USHORT client; /* 16 bit field for use by owner */ ULONG sem; /* OS/2 Ram Semaphore */ } DOSFSRSEM; #define INCL_DOSSEMAPHORES USHORT rc = DosFSRamSemRequest(FSRamSemStructure, Timeout); PDOSFSRSEM FSRamSemStructure; /* Address of structure */ LONG Timeout; /* Timeout (in milliseconds) */ USHORT rc; /* return code */
MASM
DOSFSRSEM struc dosfsrs_cb dw ? ;length of this structure (bytes) dosfsrs_pid dw ? ;Process ID of owner or zero dosfsrs_tid dw ? ;Thread ID of owner or zero dosfsrs_cUsage dw ? ;reference count dosfsrs_client dw ? ;16 bit field for use by owner dosfsrs_sem dd ? ;OS/2 Ram Semaphore DOSFSRSEM ends EXTRN DosFSRamSemRequest:FAR INCL_DOSSEMAPHORES EQU 1 PUSH@ OTHER FSRamSemStructure ;FS Ram Semaphore data structure PUSH DWORD Timeout ;Timeout (in milliseconds) CALL DosFSRamSemRequest Returns WORD
Example
This example requests a FS RAM semaphore.
#define INCL_DOSSEMAPHORES #define NOT_OWNED 0 #define START 0 #define START_LONG 0L #define TIME_OUT 1000L DOSFSRSEM SemStruct; USHORT rc; SemStruct.cb = sizeof(SemStruct); /* Initialize FS Sem */ SemStruct.pid = NOT_OWNED; SemStruct.tid = NOT_OWNED; SemStruct.cUsage = START; SemStruct.client = START; SemStruct.sem = START_LONG; rc = DosFSRamSemRequest(&SemStruct, /* Address of structure */ TIME_OUT); /* Timeout */