Multithreading: Terminating Threads

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

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. If the user wants to cancel the printing, however, the background printing thread has to be terminated prematurely. This topic explains both how to implement each situation and how to get the exit code of a thread after it terminates.

• Normal Thread Termination

• Premature Thread Termination

• Retrieving the Exit Code of a Thread

Normal Thread Termination

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 Windows SDK. The only parameter that PostQuitMessage takes is the exit code of the thread. As for worker threads, 0 typically signifies successful completion.

Premature Thread Termination

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.

Retrieving the Exit Code of a Thread

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 Windows SDK. 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 places 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:

• Set the 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 because the framework will not automatically delete it for you. This is the preferred method.

• Store the thread's handle separately. After the thread is created, copy its m_hThread data member (using ::DuplicateHandle) to another variable and access it through that variable. This way the object is deleted automatically when termination occurs 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

Multithreading with C++ and MFC
_endthread, _endthreadex
_beginthread, _beginthreadex
ExitThread