GetThreadWaitChain function (wct.h)

Retrieves the wait chain for the specified thread.


BOOL GetThreadWaitChain(
  [in]           HWCT                 WctHandle,
  [in, optional] DWORD_PTR            Context,
  [in]           DWORD                Flags,
  [in]           DWORD                ThreadId,
  [in, out]      LPDWORD              NodeCount,
  [out]          PWAITCHAIN_NODE_INFO NodeInfoArray,
  [out]          LPBOOL               IsCycle


[in] WctHandle

A handle to the WCT session created by the OpenThreadWaitChainSession function.

[in, optional] Context

A pointer to an application-defined context structure to be passed to the callback function for an asynchronous session.

[in] Flags

The wait chain retrieval options. This parameter can be one of more of the following values.

Value Meaning
Enumerates all threads of an out-of-proc MTA COM server to find the correct thread identifier.
Retrieves critical-section information from other processes.
Follows the wait chain into other processes. Otherwise, the function reports the first thread in a different process but does not retrieve additional information.

[in] ThreadId

The identifier of the thread.

[in, out] NodeCount

On input, a number from 1 to WCT_MAX_NODE_COUNT that specifies the number of nodes in the wait chain. On return, the number of nodes retrieved. If the array cannot contain all the nodes of the wait chain, the function fails, GetLastError returns ERROR_MORE_DATA, and this parameter receives the number of array elements required to contain all the nodes.

For asynchronous sessions, check the value that is passed to the callback function. Do not free the variable until the callback function has returned.

[out] NodeInfoArray

An array of WAITCHAIN_NODE_INFO structures that receives the wait chain.

For asynchronous sessions, check the value that is passed to the callback function. Do not free the array until the callback function has returned.

[out] IsCycle

If the function detects a deadlock, this variable is set to TRUE; otherwise, it is set to FALSE.

For asynchronous sessions, check the value that is passed to the callback function. Do not free the variable until the callback function has returned.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Return code Description
The caller did not have sufficient privilege to open a target thread.
One of the input parameters is invalid.
The WCT session was opened in asynchronous mode. The results will be returned through the WaitChainCallback callback function.
The NodeInfoArray buffer is not large enough to contain all the nodes in the wait chain. The NodeCount parameter contains the number of nodes in the chain. The wait chain returned is still valid.
The operating system is not providing this service.
The specified thread could not be located.
The number of nodes exceeds WCT_MAX_NODE_COUNT. The wait chain returned is still valid.


If the session is asynchronous, the function returns FALSE and GetLastError returns ERROR_IO_PENDING. To obtain the results, see the WaitChainCallback callback function.

If the specified thread is not blocked or is blocked on an unsupported synchronization element, the function returns a single item in NodeInfoArray.

The caller must have the SE_DEBUG_NAME privilege. If the caller has insufficient privileges, the function fails if the first thread cannot be accessed. Otherwise, the last node in the array will have its ObjectStatus member set to WctStatusNoAcces.

If any subset of nodes in the array forms a cycle, the function sets the IsCycle parameter to TRUE.

Wait chain information is dynamic; it was correct when the function was called but may be out-of-date by the time it is reviewed by the caller.


For an example, see Using WCT.


Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header wct.h
Library Advapi32.lib
DLL Advapi32.dll

See also



Wait Chain Traversal