# CmtNewThreadLocalVar

int CmtNewThreadLocalVar (int variableSize, const void *variableInitialValue, TLVCallbackPtr discardCallbackFunction, void *callbackData, int *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 | integer | The size of the data that you want to store in the thread local variable. The sizeof operator is useful for this.
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.
| Note This function does not support partial initialization of array and structure types. You must pass either NULL or a pointer to an entire instance of the type.
discardCallbackFunction | TLVCallbackPtr | 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); 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 resources you want to free must be freed from the thread that allocated them. For example, you must free an HWND that you obtained from the SDK function CreateWindow by calling DestroyWindow in the same thread that you called CreateWindow. The threadID parameter does not match the thread ID of the thread in which the callback is called. Use the CmtGetCurrentThreadID function to get the thread ID of the thread in which the callback is called. Keep in mind that when the callback returns, the library frees the thread local variable, so you must make copies of the resources that you want free in your deferred call. For example, if the thread local variable value is a pointer to an HWND, you must pass the HWND directly, not the pointer to the HWND, to your deferred function. 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 | integer (passed by reference) | 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 | 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.