Creating Threads

The CreateThread function creates a new thread for a process. The creating thread must specify the starting address of the code that the new thread is to execute. Typically, the starting address is the name of a function defined in the program code (for more information, see ThreadProc). This function takes a single parameter and returns a DWORD value. A process can have multiple threads simultaneously executing the same function.

The following is a simple example that demonstrates how to create a new thread that executes the locally defined function, MyThreadFunction .

The calling thread uses the WaitForMultipleObjects function to persist until all worker threads have terminated. The calling thread blocks while it is waiting; to continue processing, a calling thread would use WaitForSingleObject and wait for each worker thread to signal its wait object. Note that if you were to close the handle to a worker thread before it terminated, this does not terminate the worker thread. However, the handle will be unavailable for use in subsequent function calls.

The MyThreadFunction function avoids the use of the C run-time library (CRT), as many of its functions are not thread-safe, particularly if you are not using the multithreaded CRT. If you would like to use the CRT in a ThreadProc function, use the _beginthreadex function instead.

It is risky to pass the address of a local variable if the creating thread exits before the new thread, because the pointer becomes invalid. Instead, either pass a pointer to dynamically allocated memory or make the creating thread wait for the new thread to terminate. Data can also be passed from the creating thread to the new thread using global variables. With global variables, it is usually necessary to synchronize access by multiple threads. For more information about synchronization, see Synchronizing Execution of Multiple Threads.

The creating thread can use the arguments to CreateThread to specify the following:

• The security attributes for the handle to the new thread. These security attributes include an inheritance flag that determines whether the handle can be inherited by child processes. The security attributes also include a security descriptor, which the system uses to perform access checks on all subsequent uses of the thread’s handle before access is granted.
• The initial stack size of the new thread. The thread’s stack is allocated automatically in the memory space of the process; the system increases the stack as needed and frees it when the thread terminates. For more information, see Thread Stack Size.
• A creation flag that enables you to create the thread in a suspended state. When suspended, the thread does not run until the ResumeThread function is called.

You can also create a thread by calling the CreateRemoteThread function. This function is used by debugger processes to create a thread that runs in the address space of the process being debugged.

View threads and tasks in the Parallel Stacks window (C#, Visual Basic, C++)

The Parallel Stacks window is useful for debugging multithreaded applications. It has several views:

Threads view shows call stack information for all threads in the app. You can navigate between threads and stack frames on those threads.

Tasks view shows task-centered call stack information.

• In managed code, Tasks view shows call stacks of System.Threading.Tasks.Task objects.
• In native code, Tasks view shows call stacks of task groups, parallel algorithms, asynchronous agents, and lightweight tasks.

Method View pivots the call stack on a selected method.

Use the Parallel Stacks window

To open the Parallel Stacks window, you must be in a debugging session. Select Debug > Windows > Parallel Stacks.

Toolbar controls

The Parallel Stacks window has the following toolbar controls:

Icon	Control	Description
	Threads/Tasks combo box	Switches the view between call stacks of threads and call stacks of tasks. For more information, see Tasks view and Threads view.
	Show Only Flagged	Shows call stacks only for the threads that are flagged in other debugger windows, such as the GPU Threads window and the Parallel Watch window.
	Toggle Method View	Switches between call stack views and Method View. For more information, see Method View.
	Auto Scroll To Current Stack Frame	Autoscrolls the graph so that the current stack frame is in view. This feature is useful when you change the current stack frame from other windows, or when you hit a new breakpoint in large graphs.
	Toggle Zoom Control	Shows or hides the zoom control at the left of the window. Regardless of the visibility of the zoom control, you can also zoom by pressing Ctrl and turning the mouse wheel, or by pressing Ctrl+Shift++ to zoom in and Ctrl+Shift+— to zoom out.

Stack Frame icons

The following icons provide information about the active and current stack frames in all views:

Icon	Description
	Indicates the current location (active stack frame) of the current thread.
	Indicates the current location (active stack frame) of a non-current thread.
	Indicates the current stack frame (the current debugger context). The method name is bold wherever it appears.

Context menu items

The following shortcut menu items are available when you right-click a method in Threads view or Tasks view. The last six items are the same as in the Call Stack window.

Menu item	Description
Flag	Flags the selected item.
Unflag	Unflags the selected item.
Freeze	Freezes the selected item.
Thaw	Thaws the selected item.
Switch To Frame	Same as the corresponding menu command in the Call Stack window. However, in the Parallel Stacks window, one method may be in several frames. You can select the frame you want in the submenu for this item. If one of the stack frames is on the current thread, that frame is selected by default in the submenu.
Go to Task or Go to Thread	Switches to the Task or Threads view, and keeps the same stack frame highlighted.
Go To Source Code	Goes to the corresponding location in the source code window.
Go To Disassembly	Goes to the corresponding location in the Disassembly window.
Show External Code	Shows or hides external code.
Hexadecimal Display	Toggles between decimal and hexadecimal display.
Show Threads in Source	Flags the location of the thread in the source code window.
Symbol Load Information	Opens the Symbol Load Information dialog box.
Symbol Settings	Opens the Symbol Settings dialog box.

Threads view

In Threads view, the stack frame and call path of the current thread are highlighted in blue. The current location of the thread is shown by the yellow arrow.

To change the current stack frame, double-click a different method. This might also switch the current thread, depending on whether the method you select is part of the current thread or another thread.

When the Threads view graph is too large to fit into the window, a Bird’s Eye View control appears in the window. You can move the frame in the control to navigate to different parts of the graph.

The following illustration shows one thread that goes from Main to a Managed to Native code transition. Six threads are in the current method. One continues to Thread.Sleep, and another continues to Console.WriteLine and then to SyncTextWriter.WriteLine.

The following table describes the main features of the Threads view:

Callout	Element name	Description
1	Call stack segment or node	Contains a series of methods for one or more threads. If the frame has no arrow lines connected to it, the frame shows the entire call path for the thread(s).
2	Blue highlight	Indicates the call path of the current thread.
3	Arrow lines	Connect nodes to make up the entire call path for the thread(s).
4	Node header	Shows the number of processes and threads for the node.
5	Method	Represents one or more stack frames in the same method.
6	Tooltip on method	Appears when you hover over a method. In Threads view, the tooltip shows all threads, in a table similar to the Threads window.

Tasks view

If your app uses System.Threading.Tasks.Task objects (managed code) or task_handle objects (native code) to express parallelism, you can use Tasks view. Tasks view shows call stacks of tasks instead of threads.

In Tasks view:

• Call stacks of threads that aren’t running tasks aren’t shown.
• Call stacks of threads that are running tasks are visually trimmed at the top and bottom, to show the most relevant frames for tasks.
• When several tasks are on one thread, the call stacks of those tasks are shown in separate nodes.

To see an entire call stack, switch back to Threads view by right-clicking in a stack frame and selecting Go to Thread.

The following illustration shows the Threads view at the top and the corresponding Tasks view at the bottom.

Hover over a method to show a tooltip with additional information. In Tasks view, the tooltip shows all the tasks in a table similar to the Tasks window.

The following image shows the tooltip for a method in the Threads view at the top and for the corresponding Tasks view at the bottom.

Method View

From either Threads view or Tasks view, you can pivot the graph on the current method by selecting the Toggle Method View icon on the toolbar. Method View shows at a glance all methods on all threads that either call or are called by the current method. The following illustration shows how the same information looks in Threads view on the left and in Method View on the right.

If you switch to a new stack frame, you make that method the current method, and Method View shows all callers and callees for the new method. This may cause some threads to appear or disappear from the view, depending on whether that method appears on their call stacks. To return to the call stack view, select the Method View toolbar icon again.

Controlling Processes and Threads in WinDbg

In WinDbg, the Processes and Threads window displays information about the systems, processes, and threads that are being debugged. This window also enables you to select a new system, process, and thread to be active.

Opening the Processes and Threads Window

To open the Processes and Threads window, choose Processes and Threads from the View menu. (You can also press ALT+9 or select the Processes and Threads button () on the toolbar. ALT+SHIFT+9 closes the Processes and Threads window.)

The following screen shot shows an example of a Processes and Threads window.

The Processes and Threads window displays a list of all processes that are currently being debugged. The threads in the process appear under each process. If the debugger is attached to multiple systems, the systems are shown at the top level of the tree, with the processes subordinate to them, and the threads subordinate to the processes.

Each system listing includes the server name and the protocol details. The system that the debugger is running on is identified as .

Each process listing includes the internal decimal process index that the debugger uses, the hexadecimal process ID, and the name of the application that is associated with the process.

Each thread listing includes the internal decimal thread index that the debugger uses and the hexadecimal thread ID.

Using the Processes and Threads Window

In the Processes and Threads window, the current or active system, process, and thread appear in bold type. To make a new system, process, or thread active, select its line in the window.

The Processes and Threads window has a shortcut menu with additional commands. To access the menu, select and hold (or right-click) the title bar or select the icon near the upper-right corner of the window (). The following list describes some of the menu commands:

Move to new dock closes the Processes and Threads window and opens it in a new dock.

Always floating causes the window to remain undocked even if it is dragged to a docking location.

Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked.

Additional Information

For other methods of displaying or controlling systems, see Debugging Multiple Targets. For other methods of displaying or controlling processes and threads, see Controlling Processes and Threads.