DkmThread Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

DkmThread represents a thread running in the target process.

Derived classes: DkmGPUComputeThread, DkmVirtualThread

public ref class DkmThread : Microsoft::VisualStudio::Debugger::DkmDataContainer

[System.Runtime.InteropServices.Guid("ac420a23-b721-57c1-375d-a5053f90f94c")]
public class DkmThread : Microsoft.VisualStudio.Debugger.DkmDataContainer

[<System.Runtime.InteropServices.Guid("ac420a23-b721-57c1-375d-a5053f90f94c")>]
type DkmThread = class
    inherit DkmDataContainer

Public Class DkmThread
Inherits DkmDataContainer

Inheritance

MarshalByRefObject

DkmDataContainer

DkmThread

Derived

Microsoft.VisualStudio.Debugger.DkmVirtualThread

Microsoft.VisualStudio.Debugger.GPU.DkmGPUComputeThread

Attributes

GuidAttribute

Properties

Connection	This represents a connection between the monitor and the IDE. It can either be a local connection if the monitor is running in the same process as the IDE, or it can be a remote connection. In the monitor process, there is only one connection.
IsMainThread	True if this is the main thread of this process. The main thread is the first thread to start.
IsUnloaded	Returns true if a 'unloaded' event has been raised for this object (example: DkmThread::Unload is called) or if the object has been closed. Note that care must be used when checking this status as, without synchronization, the returned status may no longer be accurate the instruction after it is read. (Inherited from DkmDataContainer)
NativeStartAddress	If available, this is the Win32 start address of this thread (value passed to the CreateThread API). The value will not always be available, for example, it is generally not available in scenarios where the thread was started after the debugger attached, or in minidumps.
Process	DkmProcess represents a target process which is being debugged. The debugger debugs processes, so this is the basic unit of debugging. A DkmProcess can represent a system process or a virtual process such as minidumps.
SystemInformation	Contains information about the computer system that this thread is running under. If this thread is running under WOW (32-bit emulation on a 64-bit OS) this information will be for the 32-bit subsystem rather than the 64-bit subsystem.
SystemPart	[Optional] Describes traits of the thread which are relevant to a full Win32 thread. Currently, this value is required, and all threads will have a 'System' block. In the future, this value may be NULL if the DkmThread represents something other than a full Win32 thread.
TebAddress	Address within the target process, where the Win32 thread environment block is stored. See documentation on the TEB structure in MSDN for more information.
UniqueId	Guid which uniquely identifies this thread object.

Methods

BeginFuncEvalExecution(DkmFuncEvalFlags)	This method is used to resume the target process so that a function evaluation may occur. This function is called by a runtime debug monitor after it has setup a function evaluation in order to make the target process run. The runtime monitor will first update the thread context, update any necessary memory in the target process, and setup any detection that the function evaluation is completed. Callers of this method MUST always call EndFuncEvalExecution before returning from the operation that triggered the function evaluation. The behavior is undefined if a caller fails to do so. This method is implemented in the base debug monitor by first updating the target process to be in function evaluation mode (DkmThread.OnBeginFuncEvalExecution), then suspending and/or resuming threads as specified by the function evaluation flags and finally continuing the target process. This method may be called from any thread, however OnBeginFuncEvalExecution must be called from the stopping event thread, so the base debug monitor may need to perform as thread switch as part of the implementation of this method. The base debug monitor should not return from BeginFuncEvalExecution until after the target has been resumed.
CanBeginFuncEvalExecution(DkmFuncEvalFlags)	CanBeginFuncEvalExecution can be called to understand if the current state of the process allows for function evaluations. This will return false, for example, if the base DM has called StoppingEventProcessingBegin, but not StoppingEventProcessingContinue. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 16 Update 5 (DkmApiVersion.VS16Update5).
Create(DkmProcess, UInt64, UInt64, Boolean, DkmThread+System, DkmDataItem)	DkmThread is called by a debug monitor to create a new DkmThread instance. DkmThread objects for system threads are created by the base debug monitor. This method must be called on the event thread. This method will send a ThreadCreate event. Location constraint: API must be called from a Monitor component (component level < 100,000).
CreateFrameRegisters(DkmUnwoundRegister[], UInt32)	Convert an array of DkmUnwoundRegisters into an instance of DkmFrameRegisters containing a sorted DkmReadOnlyCollection of DkmUnwoundRegisters.
CreateRegistersObject(Byte[], DkmUnwoundRegister[], DkmUnwoundRegister[])	Creates a DkmFrameRegisters object from the supplied byte array containing a Win32 CONTEXT structure.
EndFuncEvalExecution(DkmFuncEvalFlags)	EndFuncEvalExecution is called by the runtime debug monitor on the event thread to exit function evaluation mode. EndFuncEvalExecution will update the internal state of the DkmProcess object to indicate that the function evaluation has ended. This will also send a FuncEvalEnded event and it will mark the process as stopped. This method may be called (1) while processing a 'received' stopping event notification -or- (2) while processing a non-stopping event such as thread exit, -or- (3) while the target is still stopped, for example if the function evaluation setup failed.
GetContext(Int32, Byte[])	Obtain the current context (register values) of a thread.
GetContext(Int32, Void*, Int32)	Obtain the current context (register values) of a thread.
GetCurrentFrameInfo(UInt64, UInt64, UInt64)	GetCurrentFrameInfo is used to obtain the frame base and return address for the current context of the thread. This takes into account Frame Pointer Omission and if the current instruction pointer is in a prolog, epilog etc... NOTE: In some cases this will get it wrong if the frame has Frame Pointer Omission and there are no symbols loaded. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetCurrentFuncEvalMode()	GetCurrentFuncEvalMode may be called by components as part of event processing to determine if function evaluation is enabled. This function may only be called as part of event processing.
GetCurrentLocation(DkmWorkList, DkmCompletionRoutine<DkmGetCurrentLocationAsyncResult>)	Provides the location of a thread, as visible in the threads window, or threads drop down in the debug location toolbar. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. Location constraint: API must be called from an IDE component (component level > 100,000).
GetCurrentRegisters(DkmUnwoundRegister[])	Returns a DkmFrameRegisters object containing the thread's current register values.
GetDataItem<T>()	Gets the instance of 'T' which has been added to this container instance. If this container does not contain a 'T', this function will return null. (Inherited from DkmDataContainer)
GetDebuggerSuspensionCount()	Return the total number of suspensions caused by the debugger (i.e. calls to DkmThread::Suspend without a call to DkmThread::Resume). This excludes any suspensions external to the debugger.
GetExtendedRegisters()	Gets the extended registers from the thread context.
GetManagedThreadProperties(DkmWorkList, DkmCompletionRoutine<DkmGetManagedThreadPropertiesAsyncResult>)	Get a managed thread's properties. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
GetManagedThreadProperties(Int32)	Get a managed thread's properties.
GetMinidumpThreadInfo(DkmMinidumpThreadInfo)
GetStackAddressRange()	Retrieves the stack limit/stack base of the given thread. Note that its possible for this value to change over time, for example, in the case of fibers.
GetSteppers()	GetSteppers enumerates the DkmStepper elements of this DkmThread object.
GetSuspensionCount(Boolean)	Return the current suspension count of this thread.
GetSuspensionCount(DkmWorkList, Boolean, DkmCompletionRoutine<DkmGetSuspensionCountAsyncResult>)	Return the current suspension count of this thread. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
GetThreadCurrentWinRtErrorInfo()	GetThreadCurrentWinRtErrorInfo is used to get the address of the current IErrorInfo object for this thread. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
GetTlsValue(Int32)	Retrieves the value in the debuggee thread's thread local storage (TLS) slot for the specified TLS index. Each thread of a process has its own slot for each TLS index.
GetTopStackFrame()	Returns the top call stack frame for a thread. This value is normally cached after the first stack walk and cleared on continue. This is only callable above the stack provider in the client process. To obtain the top frame in the server process, call GetTopStackWalkFrame. Location constraint: API must be called from an IDE component (component level > 100,000).
GetTopStackWalkFrame(DkmRuntimeInstance)	Return the top stack frame for a thread. This frame can come from a runtime instance, or a monitor unwinder. This can only be called from the server process. To obtain the top frame in the client process, use GetTopStackFrame. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetVolatileFlags()	Get volatile flags about a thread. For instance, return if a thread is a user-mode scheduled thread.
GetVolatileFlags(DkmWorkList, DkmCompletionRoutine<DkmGetVolatileFlagsAsyncResult>)	Get volatile flags about a thread. For instance, return if a thread is a user-mode scheduled thread. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
GetVolatileProperties(DkmWorkList, DkmCompletionRoutine<DkmGetVolatilePropertiesAsyncResult>)	Get a thread's dynamic properties. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
GetVolatileProperties(Int32, UInt64)	Get a thread's dynamic properties.
IsStoppingEventQueued(Boolean)	Indicates if the given thread has a stopping event in the queue. This information is used by the execution manager to decide if a thread may be slipped.
OnBeginFuncEvalExecution(DkmFuncEvalFlags)	OnBeginFuncEvalExecution is called by the base debug monitor on the event thread. This method is called as part of the implementation of IDkmBaseFuncEvalService.BeginFuncEvalExecution, which is called to resume the process for a function evaluation. OnBeginFuncEvalExecution will update the internal state of the DkmProcess object to indicate that a function evaluation is in progress. This will also send a FuncEvalStarting event and it will mark the process as running, so that no operations which require a stopped process will be allowed.
OnContinueExecution()	OnContinueExecution is called by the base debug monitor on the event thread. This method is called as part of the implementation of IDkmContinueExecution.ContinueExecution, which is what is used by the IDE to continue the target process. This method is used by the Dispatcher to either dispatch stopping events which could not be processed earlier, or to update the internal state of the DkmProcess object to indicate that the target process is now running. Before marking the process as running, the Dispatcher will send a Continue event. A base debug monitor should expect to be reentrantly called while it is in this method.
OnEmbeddedBreakpointHit(DkmInstructionAddress, Boolean)	Raise a EmbeddedBreakpointHit event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.
OnInterceptExceptionCompleted(UInt64)	Raise a InterceptExceptionCompleted event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.
OnThreadNameChange()	ThreadNameChange is sent by the dispatcher when DkmThread::NameChange is invoked by the monitor. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).
RaiseExecutionControlException(UInt32)	API which may be called from a IDkmSingleStepCompleteReceived or IDkmRuntimeBreakpointReceived implementation to force the base DM to fire the EXCEPTION_BREAKPOINT or EXCEPTION_SINGLE_STEP exception in the target process when execution is resumed. Normally, the breakpoint or single step exception is implicitly suppressed. This allows the EXCEPTION_BREAKPOINT/EXCEPTION_SINGLE_STEP to be handled by exception handlers within the target process. This API will fail if the thread is not currently sitting at a step complete or breakpoint event. Location constraint: API must be called from a Monitor component (component level < 100,000).
RemoveDataItem<T>()	Remove the instance of 'T' from this container. It is usually unnecessary to call this method as a data container will automatically be emptied when the object is closed. (Inherited from DkmDataContainer)
Resume(Boolean)	Resume this thread.
SetContext(Byte[])	Update the context (register values) of a thread.
SetDataItem<T>(DkmDataCreationDisposition, T)	Place a new item in the data container. (Inherited from DkmDataContainer)
SetExtendedRegisterValue(Int32, ReadOnlyCollection<Byte>)	Sets the value of the extended register in the thread's context.
SetTlsValue(Int32, UInt64)	Stores a value in the debuggee thread's thread local storage (TLS) slot for the specified TLS index. Each thread of a process has its own slot for each TLS index.
Suspend(Boolean)	Suspend this thread.
Unload(Int32)	ThreadExit is sent by the dispatcher when DkmThread::Unload is invoked by the monitor. This method may only be called by the component which created the object.