|
Purpose |
Close a Windows thread, or release the handle of a running thread. |
|
Syntax |
THREAD CLOSE hThread TO lResult& |
|
Remarks |
THREAD CLOSE releases the thread handle of the thread identified by the DWORD value hThread (see THREAD CREATE). If successful, lResult& is TRUE (non-zero); otherwise, it is FALSE (zero). If a thread is not closed once it has completed, it will continue to take up memory and CPU resources. Note that THREAD CLOSE does not stop a thread if it is still running; it simply releases the thread's handle (i.e., the resources used to track the thread), and the thread itself will continue to run. Once a thread handle is released, the value stored in hThread becomes undefined. On this basis, thread handles should not be released until there is no further need to test the thread status or change the suspend count for a thread. If a thread does not need to be monitored, its handle can be released immediately after the THREAD CREATE statement, and the threads resources will be freed automatically when the thread terminates naturally. Best practice suggests that after releasing a thread handle, the thread handle variable should be set to 0, to set it apart from other valid thread handle variables. Once a thread has exited, it is not possible to restart the same thread (as identified by hThread). However, a fresh thread can be executed, using the same target thread Function, and resulting in a new thread handle which will identify the new thread. |
|
Restrictions |
THREAD CLOSE will always execute successfully provided hThread contains a valid thread handle value. THREAD CLOSE generates no run-time errors; all exceptions are reported in the return value lResult&. The WaitForSingleObject API function can be used wait until a nominated thread has finished executing. Similarly, the WaitForMultipleObjects API can be used to wait for one, two, or all secondary threads (to a maximum of 64 or % MAXIMUM_WAIT_OBJECTS) to complete before continuing on. Such functions can be very useful when a program creates a set of "worker" threads to process data, and the primary thread can then sit idle until all the worker threads have completed all their work. At that point, the primary thread may gather the results of the worker threads, etc. It is also useful to understand that these kind of wait functions are very efficient and use almost no CPU time or resources while they are waiting; however, care must be exercised to avoid a deadlock or circular suspension. For example, a deadlock condition could occur if thread A is halted while it waits for thread B, which in turn has a suspend count that might only be adjustable by Thread A. Similarly, an infinite loop in one thread may also halt any other thread that is waiting for it to terminate. THREADCOUNT continues to report a thread tally that will include threads whose handle has already been released. A thread ID value may not be used interchangeably with a thread handle value. |
|
See also |
FUNCTION/END FUNCTION, THREAD CREATE, THREAD RESUME, THREAD STATUS, THREAD SUSPEND, THREADCOUNT, THREADED variables, THREADID |