Ivi_LockSession
Usage
ViStatus Ivi_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.
You can use this function to protect a section of code which requires exclusive access to the instrument. This occurs when you take multiple actions that affect the instrument and you want to ensure that other execution threads do not disturb the instrument state until all of your actions execute. For example, if you set various instrument attributes and then trigger a measurement, you must guarantee that no other execution thread modifies the attribute values until you finish taking the measurement.
You can safely make nested calls to Ivi_LockSession within the same thread. To completely unlock the session, you must balance each call to Ivi_LockSession with a call to Ivi_UnlockSession. If, however, you use the Caller Has Lock parameter in all calls to Ivi_LockSession and Ivi_UnlockSession within a function, the IVI engine locks the session only once within the function regardless of the number of calls you make to Ivi_LockSession. This allows you to call Ivi_UnlockSession just once at the end of the function.
User applications, instrument drivers, and the IVI engine functions all have the ability to obtain a lock. The IVI engine functions always release the lock before they return. Instrument driver functions should do the same.
Instrument drivers export this function to the end-user through the PREFIX_LockSession function.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| 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. Initialize the local variable to VI_FALSE when you declare it. Pass the same address to any other calls you make to Ivi_LockSession or Ivi_UnlockSession in the same function. The parameter is an input/output parameter. Ivi_LockSession and Ivi_UnlockSession each inspect the current value and take the following actions:
Thus, you can, call Ivi_UnlockSession at the end of your function without worrying about whether you actually have the lock. Example: ViStatus PREFIX_Func (ViSession vi, ViInt32 flags){ ViStatus error = VI_SUCCESS; { { if (flags & BIT_3) viCheckErr( TakeAction3(vi)); } Error: /* At this point, you cannot really be sure that you have the lock. Fortunately, the haveLock variable takes care of that for you. */ } |
Return Value
Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.
Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.