Home | Overview | How Do I | Sample
Two normal situations cause a thread to terminate: The controlling function exits or the thread is not allowed to run to completion. If a word processor used a thread for background printing, the controlling function would terminate normally if printing completed successfully. Should the user wish to cancel the printing, however, the background printing thread would have to be terminated prematurely. This article explains both how to implement each situation and how to get the exit code of a thread after it terminates.
For a worker thread, normal thread termination is simple: Exit the controlling function and return a value that signifies the reason for termination. You can use either the AfxEndThread function or a return statement. Typically, 0 signifies successful completion, but that is up to you.
For a user-interface thread, the process is just as simple: from within the user-interface thread, call ::PostQuitMessage in the Win32 Programmer’s Reference, Volume 4. The only parameter that ::PostQuitMessage takes is the exit code of the thread. As for worker threads, 0 typically signifies successful completion.
Terminating a thread prematurely is almost as simple: Call AfxEndThread from within the thread. Pass the desired exit code as the only parameter. This stops execution of the thread, deallocates the thread’s stack, detaches all DLLs attached to the thread, and deletes the thread object from memory.
AfxEndThread must be called from within the thread to be terminated. If you want to terminate a thread from another thread, you must set up a communication method between the two threads.
To get the exit code of either the worker or the user-interface thread, call the ::GetExitCodeThread function. For information about this function, see the Win32 Programmer’s Reference, Volume 3. This function takes the handle to the thread (stored in the m_hThread data member of CWinThread objects) and the address of a DWORD.
If the thread is still active, ::GetExitCodeThread will place STILL_ACTIVE in the supplied DWORD address; otherwise, the exit code is placed in this address.
Retrieving the exit code of CWinThread objects takes an extra step. By default, when a CWinThread thread terminates, the thread object is deleted. This means you cannot access the m_hThread data member because the CWinThread object no longer exists. To avoid this situation, do one of the following two things:
m_bAutoDelete data member to FALSE. This allows the CWinThread object to survive after the thread has been terminated. You can then access the m_hThread data member after the thread has been terminated. If you use this technique, however, you are responsible for destroying the CWinThread object as the framework will not automatically delete it for you. This is the preferred method.-or-
m_hThread data member (using ::DuplicateHandle) to another variable and access it through that variable. This way the object is deleted automatically upon termination and you can still find out why the thread terminated. Be careful that the thread does not terminate before you can duplicate the handle. The safest way to do this is to pass CREATE_SUSPENDED to AfxBeginThread, store the handle, and then resume the thread by calling ResumeThread. Either method allows you to determine why a CWinThread object terminated.
See Also _endthreadex, _beginthreadex, ::ExitThread