niSwitch_LockSession
Specific Function
C Function Prototype
ViStatus niSwitch_LockSession (ViSession vi, ViBoolean* callerHasLock);
Purpose
This function obtains a multithread lock on the instrument session. Before it does so, it waits until all other execution threads have released their locks on the instrument session. Other threads might have obtained a lock on this session in the following ways:
- Your application called niSwitch_LockSession.
- A call to the instrument driver locked the session.
- A call to the IVI engine locked the session.
After your call to niSwitch_LockSession returns successfully, no other threads can access the instrument session until you call niSwitch_UnlockSession. Use niSwitch_LockSession and niSwitch_UnlockSession around a sequence of calls to NI-SWITCH functions if you require that the instrument retain its settings through the end of the sequence. You can safely make nested calls to niSwitch_LockSession within the same thread. To completely unlock the session, balance each call to niSwitch_LockSession with a call to niSwitch_UnlockSession. If, however, you use the callerHasLock parameter in all calls to niSwitch_LockSession and niSwitch_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to niSwitch_LockSession. This allows you to call niSwitch_UnlockSession just once at the end of the function.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession | A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls. |
| callerHasLock | ViBoolean | This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep track of whether you obtain a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to niSwitch_LockSession or niSwitch_UnlockSession in the same function. The parameter is an input/output parameter. niSwitch_LockSession and niSwitch_UnlockSession each inspect the current value and take the following actions:
Example: |