CmtTerminateThreadPoolThread
- Updated2023-02-21
- 2 minute(s) read
CmtTerminateThreadPoolThread
int CmtTerminateThreadPoolThread (CmtThreadPoolHandle poolHandle, unsigned int threadID, int exitCode);
Purpose
Terminates thread pool threads.
 |
Caution Use extreme caution when calling this function. Terminating a thread prevents it from properly freeing resources. Call this function only when you know exactly what operations the thread you want to terminate is performing. If you terminate a thread that is executing operating system code, your system could become unstable. |
If you terminate a thread pool thread that is executing a Thread Function that is being waited on by other threads that called CmtWaitForThreadPoolFunctionCompletion or CmtWaitForThreadPoolFunctionCompletionEx, those threads do not receive notification that the Thread Function's thread has been terminated. The waiting threads wait indefinitely and are not destroyed until the process exits.
To safely terminate the thread, call CmtExitThreadPoolThread from within the thread that you want to terminate. If you need to initiate the exit from another thread, you can use PostDeferredCallToThread to notify the thread that it must exit. From within the thread pool thread, call CmtExitThreadPoolThread to ensure that the thread is returned to the pool safely. If your Thread Function does not process events, then your Thread Function must periodically check a flag that is set by another thread to indicate that your Thread Function must exit.
Parameters
| Input | ||
| Name | Type | Description |
| poolHandle | CmtThreadPoolHandle | The handle you obtained from CmtNewThreadPool to identify the thread pool. Pass DEFAULT_THREAD_POOL_HANDLE to specify the default thread pool. |
| threadID | unsigned int | The threadID of the thread pool thread that you want to terminate. Call CmtGetThreadPoolFunctionAttribute with the ATTR_TP_FUNCTION_THREAD_ID attribute to obtain a thread pool thread's thread ID. |
| exitCode | int | The exit code for the thread. If the thread is executing a Thread Function when you terminate it, you can call CmtGetThreadPoolFunctionAttribute with the ATTR_TP_FUNCTION_RETURN_VALUE attribute to retrieve the Exit Code from other threads. If the thread is idle in the pool when you terminate it, you can retrieve the exit code in other threads with the Windows SDK function GetExitCodeThread. Refer to www.msdn.com for more information. |
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