Wait chain traversal

Wait chain traversal (WCT) allows debuggers to diagnose application hangs and deadlocks.

A wait chain is an alternating sequence of threads and synchronization objects where each thread waits for the object that follows. Each object that follows is, in turn, owned by the subsequent thread in the chain.

A thread waits for a synchronization object from the time the thread requests the object until it's acquired. This lock is owned by a thread from the time the thread acquires it, until the thread releases it. In other words, when thread 1 waits for a lock that's owned by thread 2, thread 1 is waiting for thread 2.

WCT supports the following synchronization primitives:

To retrieve the wait chain for one or more threads, create a WCT session by using the OpenThreadWaitChainSession and GetThreadWaitChain functions. WCT sessions are represented by a handle of type HWCT.

Sessions can be synchronous or asynchronous

You can't cancel synchronous sessions, and block the calling thread, until a wait chain has been retrieved.

Asynchronous sessions don't block the calling thread, and can be canceled by the application using the CloseThreadWaitChainSession function. Results from asynchronous operations are made available through a WaitChainCallback callback function provided by the application.

For asynchronous sessions, the caller can specify a pointer to a context data structure through GetThreadWaitChain. This same pointer is passed to the WaitChainCallback callback function.

The context data structure is user defined and opaque to WCT. The context data structure can be used by the application to communicate context between a WCT query and a callback function. Typically, you pass an event handle through this structure and, when the callback is executed, this event is signalled and a monitoring thread is informed that the query has been completed.

For an example of wait chain traversal, see Using WCT.

See also