int CmtNewLock (const char *lockName, unsigned int options, int *lockHandle);
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 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.
Input | ||||
Name | Type | Description | ||
lockName | const |
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 with Terminal Services running, the lock name can have a Global\ or Local\ prefix to explicitly create the object in the global or session name space. The lock name can contain any character, but the backslash character (\) must be used only with these prefixes. 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 integer | Pass OPT_TL_PROCESS_EVENTS_WHILE_WAITING if you want threads to process events while waiting to acquire the lock in CmtGetLock. Pass 0 if you do not want threads to process events while waiting in CmtGetLock. 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 | integer (passed by reference) | Returns a handle that you use to identify the thread lock in subsequent function calls. The handle is never 0. |
Name | Type | Description |
CmtStatus | integer | 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. |