CmtGetLockEx
- Updated2023-02-21
- 2 minute(s) read
CmtGetLockEx
int CmtGetLockEx (CmtThreadLockHandle lockHandle, int processEvents, unsigned int timeout, int *obtainedLock);
Purpose
Gets ownership of the thread lock.
When you finish using the thread lock, you must release the lock by calling CmtReleaseLock from the same thread that called this function. Only one thread can get ownership of the thread lock at a time. If a thread requests the lock while another thread owns the lock, the calling thread waits in this function until the owning thread releases the lock. You can call this function from the same thread more than once, but you must call CmtReleaseLock once for each time that you called this function.
If you want this function to process events while waiting, the options parameter in the CmtNewLock function must be set to OPT_TL_PROCESS_EVENTS_WHILE_WAITING. If you did not use the OPT_TL_PROCESS_EVENTS_WHILE_WAITING option, and you pass a non-zero value in the processEvents parameter, then this function returns an error.
If you want this function to timeout after a finite interval, the options parameter in the CmtNewLock function must be set to OPT_TL_SUPPORT_TIMEOUT. If you did not use the OPT_TL_SUPPORT_TIMEOUT option, and you pass a value other than CMT_WAIT_FOREVER in the timeout parameter, then this function returns an error.
Parameters
| Input | ||
| Name | Type | Description |
| lockHandle | CmtThreadLockHandle | The handle you obtained from CmtNewLock to identify the thread lock. |
| processEvents | int | Pass a non-zero value if you want the thread to process events while waiting to acquire the lock. Otherwise, pass zero. If you want this function to process events while waiting, then you must pass the OPT_TL_PROCESS_EVENTS_WHILE_WAITING flag in the options parameter to CmtNewLock. If you did not use the above option, and you pass a non-zero value in the processEvents parameter, then this function will return an error. |
| timeout | unsigned int | Pass the number of milliseconds this function should wait. Pass CMT_WAIT_FOREVER if you want this function to wait forever. If you want this function to timeout after a finite interval, then you must pass the OPT_TL_SUPPORT_TIMEOUT flag in the options parameter to CmtNewLock. If you did not use the above option, and you pass a value other than CMT_WAIT_FOREVER in the timeout parameter, then this function will return an error. |
| Output | ||
| Name | Type | Description |
| obtainedLock | int | Returns 1 if you obtain the lock. Returns 0 if you fail to obtain the lock. |
Return Value
| Name | Type | Description |
| cmtStatus | int | The CmtStatus code that the function call returns. This function returns 0 to indicate success and negative values to indicate failure. Pass the CmtStatus code to CmtGetErrorMessage to get a description of the error code. |
Additional Information
Library: Utility Library
Include file: utility.h
LabWindows/CVI compatibility: LabWindows/CVI 2010 and later