CmtNewThreadLocalVar
int CmtNewThreadLocalVar (size_t variableSize, const void *variableInitialValue, CmtTLVCallbackPtr discardCallbackFunction, void *callbackData, CmtTLVHandle *variableHandle);
Purpose
Creates a thread local variable.
You can use a thread local variable to store information that varies between threads in your application. When you are finished using the variable from all threads, you can call CmtDiscardThreadLocalVar to free the thread local variable. Alternatively, you can allow the threads to exit without calling CmtDiscardThreadLocalVar. The library automatically frees the thread local variable when each thread that accessed it exits.
Parameters
| Input | ||||
| Name | Type | Description | ||
| variableSize | size_t | The size of the data that you want to store in the thread local variable. The sizeof operator is useful for this. The function returns an error if this value is greater than INT_MAX. |
||
| variableInitialValue | const void * | A pointer to a variable containing the initial value for the thread local variable. When a thread accesses the thread local for the first time, its value is set to this default. Pass NULL to initialize the contents of the variable to 0. For array and structure variables, every element is initialized to 0.
|
||
| discardCallbackFunction | CmtTLVCallbackPtr | The function that you want the library to call when a thread local variable is discarded. You can use this callback to free resources that you allocated and stored in the thread local variable. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (void *threadLocalPtr, int event, void *callbackData, unsigned int threadID); Upon entry to the callback, the threadLocalPtr parameter contains a pointer to the thread local variable. The event parameter indicates the reason that the thread local variable is being discarded. The callbackData parameter contains the value you passed to the callbackData parameter of this function. The threadID parameter indicates which thread is associated with the thread local variable pointed to by the threadLocalPtr parameter. Under most circumstances you can free, directly in this callback, resources that are stored in your thread local variables. However, under certain circumstances, you must call PostDeferredCallToThread to ensure that your resources are freed from the appropriate thread. If both of the following conditions apply, you must post a deferred call to the thread indicated in the value of the threadID parameter:
The following list indicates the possible event values: Event: EVENT_TLV_DISCARD_THREAD_DETACH Value: The thread that accessed the thread local variable is exiting. Event: EVENT_TLV_DISCARD_FUNCTION_CALLED Value: CmtDiscardThreadLocalVar was called. |
||
| callbackData | void * | A value that you want to pass to your callback as the callbackData parameter. Do not pass the address of a local variable or any other variable that might not be valid when the function is executed. | ||
| Output | ||||
| Name | Type | Description | ||
| variableHandle | CmtTLVHandle | Returns a handle that you use to identify the thread local variable 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 CmtNewThreadLocalVar function:
- utility\threading\ThreadLocalVar\ThreadLocalVar.cws
Open example - utility\threading\ThreadPool\OnePanel\OnePanel.cws
Open example