WindowsApi:CreateThread

lastmod 2018-08-17created 2016-04-063 edits

Creates a thread to execute within the virtual address space of the calling process. To create a thread that runs in the virtual address space of another process, use the CreateRemoteThread function.

Prototype

Syntax:

HANDLE WINAPI CreateThread(
  __in_opt   LPSECURITY_ATTRIBUTES lpThreadAttributes,
  __in       SIZE_T dwStackSize,
  __in       LPTHREAD_START_ROUTINE lpStartAddress,
  __in_opt   LPVOID lpParameter,
  __in       DWORD dwCreationFlags,
  __out_opt  LPDWORD lpThreadId
);

Parameters:

Requirements:

If the function succeeds, it returns a handle to the new thread; if it fails, it returns NULL, and error information can be obtained through GetLastError(). As a caveat, when using threads in Visual Studio, you must set Project Properties > Configuration Properties > C/C++ > Code Generation > Runtime Library to multithreaded.

Simple Example

thread_handle = CreateThread(NULL, 0, (LPTHREAD_START_ROUTINE)ThreadFunc, NULL, 0, &thread_id);
CloseHandle(thread_handle);

CreateThread WARNING

• [Recommended] MSDN: C run-time library functions for thread control

Warning on using CreateThread(). Using the Win32 functions ExitThread() and CreateThread() is not recommended. Using SuspendThread() can cause a deadlock when more than one thread is blocked waiting for the suspended thread to complete its access to a C run-time data structure.

Proper way to terminate a thread

The preferred way to terminate a thread is described below.

Comparison of Win32 thread functions

CreateThread()

A Windows API function that creates a new thread. (Windows.h)

_beginthread()

C/C++ Runtime-Library (process.h).

Right after creating a new thread, it calls CloseHandle() to close the handle of the created thread, so communication between threads is impossible. The handle is closed immediately to hide the details of Win32, but this ended up making the function buggy. Its paired function is _endthread(), which is called automatically when the created thread ends. So this function is not called explicitly; doing so causes an error. On success it returns a handle to the new thread, and on error it returns an error code.

_beginthreadex()

C/C++ Runtime-Library (process.h).

Because it does not internally close the handle of the newly created thread, explicitly _endthreadex(), which is likewise called automatically when the created thread ends. So this function does not need to be called explicitly. Calling _endthreadex() explicitly does not cause an error the way _endthread() does. On success it returns a handle to the new thread, and on error it returns an error code.

Result

To call C run-time routines from a program built with Libcmt.lib, you must start threads with _beginthread() or _beginthreadex(). Using the Win32 functions ExitThread() and CreateThread() is not recommended. For the reason, see #CreateThread WARNING.

MSDN description

• See: [http://msdn.microsoft.com/ko-kr/library/7t9ha0zh(v=vs.110.aspx MSDN: C run-time library functions for thread control]
• The LIBCMT and MSVCRT C run-time libraries provide the _beginthread(), _beginthreadex() and _endthread(), _endthreadex() functions for creating and terminating threads. _beginthread() and beginthreadex() create a new thread and return a thread identifier if the operation succeeds. A thread terminates automatically when it finishes execution, or it can terminate itself by calling _endthread() or _endthreadex().
• Differences: _beginthread() and _beginthreadex() are similar to CreateThread() in the Win32 API, but differ as follows. These functions initialize certain C run-time library variables. This matters only if you use the C run-time library in your threads. CreateThread() provides control over security attributes. You can use this function to start a thread in a suspended state.
• The _beginthread() and _beginthreadex() functions create a new thread. A thread shares the code and data segments of a process with other threads in the process, but has its own unique register values, stack space, and current instruction address. The system gives CPU time to each thread, so all threads in a process can run concurrently.
• The _endthread() function terminates a thread created by _beginthread(), and likewise the _endthreadex() function terminates a thread created by _beginthreadex(). Threads terminate automatically when they finish their work. _endthread() and _endthreadex() are useful for conditional termination from within a thread. For example, a thread dedicated to communications processing can quit if it loses control of the communications port.

See also

• Windows Api
• TerminateThread()
• ExitThread()
• SuspendThread()
• ResumeThread()
• SetThreadPriority()
• GetThreadPriority()

LIBCMT & MSVCRT C

• _beginthread()
• _beginthreadex()
• _endthread()
• _endthreadex()

Favorite site

• [http://msdn.microsoft.com/en-us/library/windows/desktop/ms682453(v=vs.85.aspx MSDN CreateThread function reference]