CmtNewLock
int CmtNewLock (const char lockName[], unsigned int options, CmtThreadLockHandle *lockHandle);
Purpose
Creates a thread lock.
Use a thread lock in applications with multiple threads to prevent multiple threads from performing some action at the same time.
CmtGetLock, CmtGetLockEx, and CmtReleaseLock take longer to execute if you name the lock or choose to process messages in CmtGetLock.
When you finish using the lock in all threads, you must call CmtDiscardLock to uninitialize the lock.
Parameters
| Input | ||||
| Name | Type | Description | ||
| lockName | const char [] | The name you want to give to the lock you are creating. Pass NULL if you do not want to name the lock. Unnamed locks provide better performance than named locks. You must name the lock if you plan to use the lock across multiple processes. The lock name must not be longer than MAX_PATHNAME_LEN characters.
Under Windows systems without Terminal Services running, the Global\ and Local\ prefixes are ignored. The lock name can contain any character, but the backslash character must only be used with these prefixes. |
||
| options | unsigned int | Pass OPT_TL_PROCESS_EVENTS_WHILE_WAITING if you want threads to process events while waiting to acquire the lock in CmtGetLock or CmtGetLockEx. Pass OPT_TL_SUPPORT_TIMEOUT if you want to wait for finite intervals when trying to acquire the lock - if you do not pass this option, then threads will wait forever when trying to acquire the lock. You can pass the bitwise OR of the above flags to apply both options. Pass 0 if you do not want to apply any of the above options. To avoid hanging the system, pass OPT_TL_PROCESS_EVENTS_WHILE_WAITING if threads might wait for more than a fraction of a second to acquire the lock or if threads that get the lock send messages or display panels or dialog boxes while they have the lock. You do not need to pass OPT_TL_PROCESS_EVENTS_WHILE_WAITING if you hold the lock for short periods of time and do not perform any user interface or messaging actions while you own the lock.
|
||
| Output | ||||
| Name | Type | Description | ||
| lockHandle | CmtThreadLockHandle | Returns a handle that you use to identify the thread lock in subsequent function calls. The handle is never 0. | ||
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 5.5 and later
Examples
Refer to the following examples that use the CmtNewLock function:
- utility\threading\ThreadedGuessers\ThreadedGuessers.cws
Open example - utility\threading\ThreadLockTimeout\ThreadLockTimeout.cws
Open example - utility\threading\ThreadPool\ParallelTestInit\ParallelTestInit.cws
Open example