Share via


DkmVirtualThread Class

Definition

DkmVirtualThread represents a thread that does not physically exist in the debugged process.

This API was introduced in Visual Studio 16 Update 2 (DkmApiVersion.VS16Update2).

public ref class DkmVirtualThread : Microsoft::VisualStudio::Debugger::DkmThread
[System.Runtime.InteropServices.Guid("bec7987a-48f1-dd04-3001-8c296365a14f")]
public class DkmVirtualThread : Microsoft.VisualStudio.Debugger.DkmThread
[<System.Runtime.InteropServices.Guid("bec7987a-48f1-dd04-3001-8c296365a14f")>]
type DkmVirtualThread = class
    inherit DkmThread
Public Class DkmVirtualThread
Inherits DkmThread
Inheritance
Inheritance
DkmVirtualThread
Attributes

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.

(Inherited from DkmThread)
IsMainThread

True if this is the main thread of this process. The main thread is the first thread to start.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
UniqueId

Guid which uniquely identifies this thread object.

(Inherited from DkmThread)

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.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
Create(DkmProcess, DkmThread+System, DkmDataItem)

Create a new DkmVirtualThread object instance.

Location constraint: API must be called from a Monitor component (component level < 100,000).

This API was introduced in Visual Studio 16 Update 2 (DkmApiVersion.VS16Update2).

CreateFrameRegisters(DkmUnwoundRegister[], UInt32)

Convert an array of DkmUnwoundRegisters into an instance of DkmFrameRegisters containing a sorted DkmReadOnlyCollection of DkmUnwoundRegisters.

(Inherited from DkmThread)
CreateRegistersObject(Byte[], DkmUnwoundRegister[], DkmUnwoundRegister[])

Creates a DkmFrameRegisters object from the supplied byte array containing a Win32 CONTEXT structure.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
GetContext(Int32, Byte[])

Obtain the current context (register values) of a thread.

(Inherited from DkmThread)
GetContext(Int32, Void*, Int32)

Obtain the current context (register values) of a thread.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
GetCurrentRegisters(DkmUnwoundRegister[])

Returns a DkmFrameRegisters object containing the thread's current register values.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
GetExtendedRegisters()

Gets the extended registers from the thread context.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
GetManagedThreadProperties(Int32)

Get a managed thread's properties.

(Inherited from DkmThread)
GetMinidumpThreadInfo(DkmMinidumpThreadInfo)

Obtains thread state information stored in the Minidump.

This API was introduced in Visual Studio 17 RTM (DkmApiVersion.VS17RTM).

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
GetSteppers()

GetSteppers enumerates the DkmStepper elements of this DkmThread object.

(Inherited from DkmThread)
GetSuspensionCount(Boolean)

Return the current suspension count of this thread.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
GetVolatileFlags()

Get volatile flags about a thread. For instance, return if a thread is a user-mode scheduled thread.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
GetVolatileProperties(Int32, UInt64)

Get a thread's dynamic properties.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
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).

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
SetContext(Byte[])

Update the context (register values) of a thread.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)
Suspend(Boolean)

Suspend this thread.

(Inherited from DkmThread)
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.

(Inherited from DkmThread)

Applies to