DkmRuntimeInstructionBreakpoint Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger.Breakpoints

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

Package:

Microsoft.VisualStudio.Debugger.Engine v17.8.1101801

Low-level breakpoint which is set on an instruction address.

public ref class DkmRuntimeInstructionBreakpoint : Microsoft::VisualStudio::Debugger::Breakpoints::DkmRuntimeBreakpoint

[System.Runtime.InteropServices.Guid("4c0b1e65-9d9c-2a4b-9ea0-8b9ead27ca39")]
public class DkmRuntimeInstructionBreakpoint : Microsoft.VisualStudio.Debugger.Breakpoints.DkmRuntimeBreakpoint

[<System.Runtime.InteropServices.Guid("4c0b1e65-9d9c-2a4b-9ea0-8b9ead27ca39")>]
type DkmRuntimeInstructionBreakpoint = class
    inherit DkmRuntimeBreakpoint

Public Class DkmRuntimeInstructionBreakpoint
Inherits DkmRuntimeBreakpoint

Inheritance

Object

DkmDataContainer

DkmRuntimeBreakpoint

DkmRuntimeInstructionBreakpoint

Attributes

GuidAttribute

Properties

InstructionAddress	Abstract representation of an executable code location (ex: EIP value). If resolved, an Instruction Address will be within a particular module instance. An Instruction Address is always within a particular Runtime Instance.
IsBarrier	Indicates if this instruction breakpoint works as a barrier, used in GPU debugging scenarios.
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)
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 DkmRuntimeBreakpoint)
RuntimeInstance	The DkmRuntimeInstance class represents an execution environment which is loaded into a DkmProcess and which contains code to be debugged. (Inherited from DkmRuntimeBreakpoint)
SourceId	Identifies the source of an object. SourceIds are used to enable filtering in scenarios when multiple components may be creating instances of a class. For example, source ids can be used to determine if a breakpoint comes from the AD7 AL (ex: user breakpoint, or other breakpoint visible at the SDM level) instead of a breakpoint which may be created by another component (for example an internal breakpoint used for stepping). (Inherited from DkmRuntimeBreakpoint)
TagValue	DkmRuntimeBreakpoint is an abstract base class. This enum indicates which derived class this object is an instance of. (Inherited from DkmRuntimeBreakpoint)
Thread	[Optional] Thread on which this breakpoint should fire. If null, the breakpoint will fire on all threads. (Inherited from DkmRuntimeBreakpoint)
UniqueId	Guid which uniquely identifies this pending breakpoint object. (Inherited from DkmRuntimeBreakpoint)

Methods

ClearConditions()	Clear any compiled/evaluation condition associated with the specified DkmRuntimeBreakpoint. This method is implicitly called when the DkmRuntimeBreakpoint is closed. (Inherited from DkmRuntimeBreakpoint)
ClearConditions(DkmWorkList, DkmCompletionRoutine<DkmClearRuntimeBreakpointConditionsAsyncResult>)	Clear any compiled/evaluation condition associated with the specified DkmRuntimeBreakpoint. This method is implicitly called when the DkmRuntimeBreakpoint is closed. 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 DkmRuntimeBreakpoint)
ClearHitCountCondition(DkmBreakpointHitCountCondition, Int32)	Clears the hit count condition on a breakpoint. (Inherited from DkmRuntimeBreakpoint)
ClearHitCountCondition(DkmWorkList, DkmBreakpointHitCountCondition, DkmCompletionRoutine<DkmClearRuntimeBreakpointHitCountConditionAsyncResult>)	Clears the hit count condition on a breakpoint. 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 DkmRuntimeBreakpoint)
Close()	Closes the breakpoint object instance. This will release any resources associated with this object across all components. If the breakpoint is currently enabled, it will be implicitly disabled. DkmRuntimeBreakpoint objects are automatically closed when their associated DkmRuntimeInstance object is closed. This method may only be called by the component which created the object. (Inherited from DkmRuntimeBreakpoint)
Create(Guid, DkmThread, DkmInstructionAddress, Boolean, DkmDataItem)	Creates a new DkmRuntimeInstructionBreakpoint object. After creation, the breakpoint is in the disabled state, and must be explicitly enabled. The caller is responsible for closing the created object after they are done.
Disable()	Disables a breakpoint. Disabling a breakpoint is typically implemented by modifying the state of the target process so the breakpoint will no longer fire. For example, removing a previously inserted 'int3' from the instruction stream. If the breakpoint is already disabled, this operation has no effect. In addition to this method, a breakpoint is implicitly disabled when it is closed. If multiple breakpoints are set on the same instruction, disabling one breakpoint does not affect the other breakpoints set on this instruction. This method may only be called by the component which created the object. (Inherited from DkmRuntimeBreakpoint)
Disable(DkmWorkList, DkmCompletionRoutine<DkmDisableRuntimeBreakpointAsyncResult>)	Disables a breakpoint. Disabling a breakpoint is typically implemented by modifying the state of the target process so the breakpoint will no longer fire. For example, removing a previously inserted 'int3' from the instruction stream. If the breakpoint is already disabled, this operation has no effect. In addition to this method, a breakpoint is implicitly disabled when it is closed. If multiple breakpoints are set on the same instruction, disabling one breakpoint does not affect the other breakpoints set on this instruction. 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. This method may only be called by the component which created the object. (Inherited from DkmRuntimeBreakpoint)
Enable()	Enables a breakpoint. Breakpoints start off initially disabled, so this method must be called before the breakpoint can be set. Enabling a breakpoint is typically implemented in the debug monitor by modifying the state of the target process. For example inserting an 'int3' instruction into the code stream. If the breakpoint is already enabled, this operation has no effect. Once a breakpoint has been enabled, the debug monitor will raise a RuntimeBreakpoint event for this DkmRuntimeBreakpoint object whenever the trigger condition (ex: target instruction is executed) is met. Multiple DkmRuntimeBreakpoints may be set on the same instruction. In this case, the debug monitor will raise a different RuntimeBreakpoint event for each breakpoint object. Similarly, if a step complete and a breakpoint both complete on the same instruction, the debug monitor will raise both events. This method may only be called by the component which created the object. (Inherited from DkmRuntimeBreakpoint)
Enable(DkmWorkList, DkmCompletionRoutine<DkmEnableRuntimeBreakpointAsyncResult>)	Enables a breakpoint. Breakpoints start off initially disabled, so this method must be called before the breakpoint can be set. Enabling a breakpoint is typically implemented in the debug monitor by modifying the state of the target process. For example inserting an 'int3' instruction into the code stream. If the breakpoint is already enabled, this operation has no effect. Once a breakpoint has been enabled, the debug monitor will raise a RuntimeBreakpoint event for this DkmRuntimeBreakpoint object whenever the trigger condition (ex: target instruction is executed) is met. Multiple DkmRuntimeBreakpoints may be set on the same instruction. In this case, the debug monitor will raise a different RuntimeBreakpoint event for each breakpoint object. Similarly, if a step complete and a breakpoint both complete on the same instruction, the debug monitor will raise both events. 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. This method may only be called by the component which created the object. (Inherited from DkmRuntimeBreakpoint)
EvaluateConditionAndSelectThread(DkmThread)	The base debug monitor asks the breakpoint condition processor to evaluate on all stopped threads, and selects the thread whose condition is true. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 11 Update 1 (DkmApiVersion.VS11FeaturePack1). (Inherited from DkmRuntimeBreakpoint)
EvaluateConditionAndSelectThread(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmEvaluateConditionAndSelectThreadAsyncResult>)	The base debug monitor asks the breakpoint condition processor to evaluate on all stopped threads, and selects the thread whose condition is true. 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 a Monitor component (component level < 100,000). This API was introduced in Visual Studio 11 Update 1 (DkmApiVersion.VS11FeaturePack1). (Inherited from DkmRuntimeBreakpoint)
GetCompiledCondition(DkmInstructionAddress, DkmBreakpointConditionOperator)	Call back invoked from the breakpoint condition processor to the breakpoint manager (or other component which calls SetCompiledConditionPending) when the breakpoint condition needs to be re-compiled for a new instruction address. Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmRuntimeBreakpoint)
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)
GetHitCountConditionStatus(DkmWorkList, DkmCompletionRoutine<DkmGetRuntimeBreakpointHitCountConditionAsyncResult>)	Obtains the current hit count value for a DkmRuntimeBreakpoint which has a hit count condition. This function will fail if the DkmRuntimeBreakpoint does not currently have a hit count condition. 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 DkmRuntimeBreakpoint)
GetHitCountConditionStatus(Int32)	Obtains the current hit count value for a DkmRuntimeBreakpoint which has a hit count condition. This function will fail if the DkmRuntimeBreakpoint does not currently have a hit count condition. (Inherited from DkmRuntimeBreakpoint)
OnBreakpointConditionFailed(DkmILFailureReason)	Call back invoked from the breakpoint condition processor to the breakpoint manager when a breakpoint condition encounters a runtime error. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). (Inherited from DkmRuntimeBreakpoint)
OnBreakpointConditionFailed(DkmThread, String, DkmILFailureReason)	Raise a RuntimeBreakpointConditionFailed 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. This API was introduced in Visual Studio 16 Update 3 (DkmApiVersion.VS16Update3). (Inherited from DkmRuntimeBreakpoint)
OnBreakpointConditionFailed(String)	Call back invoked from the breakpoint condition processor to the breakpoint manager when a breakpoint condition encounters a runtime error. Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmRuntimeBreakpoint)
OnDataBreakpointHit(DkmThread, Boolean, String)	Raise a RuntimeDataBreakpointHit 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. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM). (Inherited from DkmRuntimeBreakpoint)
OnError(DkmBreakpointMessageLevel, String)	This method will be called when an breakpoint has been invalid and needs to inform the UI. Location constraint: This can be called from any component. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM). (Inherited from DkmRuntimeBreakpoint)
OnHit(DkmThread, Boolean)	Raise a RuntimeBreakpoint 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 DkmRuntimeBreakpoint)
OnHitWithError(DkmThread, Boolean, DkmBreakpointMessageLevel, String)	Raise a RuntimeBreakpointHitWithError 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. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM). (Inherited from DkmRuntimeBreakpoint)
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)
RequestBreakpointEventOnModifiedThread(DkmThread)	The breakpoint condition processor decides not to break on the given thread but another thread of the same warp, so the breakpoint condition processor instructs the base debug monitor to re-send the breakpoint event on the other thread. (Inherited from DkmRuntimeBreakpoint)
RequestBreakpointEventOnModifiedThread(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmRequestBreakpointEventOnModifiedThreadAsyncResult>)	The breakpoint condition processor decides not to break on the given thread but another thread of the same warp, so the breakpoint condition processor instructs the base debug monitor to re-send the breakpoint event on the other 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 DkmRuntimeBreakpoint)
SetCompiledCondition(DkmCompiledInspectionQuery, DkmBreakpointConditionOperator)	This sets an associated compiled condition on the specified runtime instruction breakpoint. The breakpoint condition processor will then test the condition whenever it is hit. This is used for languages which are evaluated in the IDE process (ex: C++).
SetCompiledCondition(DkmWorkList, DkmCompiledInspectionQuery, DkmBreakpointConditionOperator, DkmCompletionRoutine<DkmSetCompiledConditionAsyncResult>)	This sets an associated compiled condition on the specified runtime instruction breakpoint. The breakpoint condition processor will then test the condition whenever it is hit. This is used for languages which are evaluated in the IDE process (ex: C++). 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.
SetCompiledConditionPending()	This method is similar to SetCompiledCondition, but is used in cases where the instruction address is not known up front, such as data breakpoints. In these cases, when the breakpoint is first hit at a particular address, a call will be made to the breakpoint client to obtain a new compiled condition for this address (IDkmBreakpointConditionProcessorClient.GetCompiledCondition). This is used for languages which are evaluated in the IDE process (ex: C++). (Inherited from DkmRuntimeBreakpoint)
SetCompiledConditionPending(DkmWorkList, DkmCompletionRoutine<DkmSetCompiledConditionPendingAsyncResult>)	This method is similar to SetCompiledCondition, but is used in cases where the instruction address is not known up front, such as data breakpoints. In these cases, when the breakpoint is first hit at a particular address, a call will be made to the breakpoint client to obtain a new compiled condition for this address (IDkmBreakpointConditionProcessorClient.GetCompiledCondition). This is used for languages which are evaluated in the IDE process (ex: C++). 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 DkmRuntimeBreakpoint)
SetDataItem<T>(DkmDataCreationDisposition, T)	Place a new item in the data container. (Inherited from DkmDataContainer)
SetEvaluationCondition(DkmBreakpointCondition, String)	Sets a breakpoint condition which is evaluated on the target computer. This is used for .NET languages. (Inherited from DkmRuntimeBreakpoint)
SetEvaluationCondition(DkmWorkList, DkmBreakpointCondition, DkmCompletionRoutine<DkmSetEvaluationConditionAsyncResult>)	Sets a breakpoint condition which is evaluated on the target computer. This is used for .NET languages. 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 DkmRuntimeBreakpoint)
SetHitCountCondition(DkmBreakpointHitCountCondition, Int32)	Initialize or update the hit count condition/value on a breakpoint. If the same breakpoint has both a language-level condition, and a hit count condition, the language-level condition is applied first. The condition is implicitly removed if the DkmRuntimeBreakpoint is closed. (Inherited from DkmRuntimeBreakpoint)
SetHitCountCondition(DkmWorkList, DkmBreakpointHitCountCondition, Int32, DkmCompletionRoutine<DkmSetRuntimeBreakpointHitCountConditionAsyncResult>)	Initialize or update the hit count condition/value on a breakpoint. If the same breakpoint has both a language-level condition, and a hit count condition, the language-level condition is applied first. The condition is implicitly removed if the DkmRuntimeBreakpoint is closed. 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 DkmRuntimeBreakpoint)
Test()	Determines if the given DkmRuntimeBreakpoint could be enabled. This is used from within the breakpoints dialog to validate breakpoints before the dialog is closed. (Inherited from DkmRuntimeBreakpoint)
Test(DkmWorkList, DkmCompletionRoutine<DkmTestRuntimeBreakpointAsyncResult>)	Determines if the given DkmRuntimeBreakpoint could be enabled. This is used from within the breakpoints dialog to validate breakpoints before the dialog is closed. 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 DkmRuntimeBreakpoint)
TryClearConditionOnTargetDevice()	Clear any condition associated with the specified DkmRuntimeInstructionBreakpoint.
TryClearConditionOnTargetDevice(DkmWorkList, DkmCompletionRoutine<DkmTryClearConditionOnTargetDeviceAsyncResult>)	Clear any condition associated with the specified DkmRuntimeInstructionBreakpoint. 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.
TryPushConditionToTargetDevice(DkmCompiledInspectionQuery, DkmBreakpointConditionOperator)	This tries to push the associated condition on the specified runtime instruction breakpoint to the target. This is useful for GPU debugging since testing the condition on the target (GPU hardware or VSD3D ref) is much more efficient than doing it in the debugger. Once this method succeeds, breakpoint event will only be received by the debugger when the condition tests to be true on the debuggee; if it fails, the debugger can still test the condition.
TryPushConditionToTargetDevice(DkmWorkList, DkmCompiledInspectionQuery, DkmBreakpointConditionOperator, DkmCompletionRoutine<DkmTryPushConditionToTargetDeviceAsyncResult>)	This tries to push the associated condition on the specified runtime instruction breakpoint to the target. This is useful for GPU debugging since testing the condition on the target (GPU hardware or VSD3D ref) is much more efficient than doing it in the debugger. Once this method succeeds, breakpoint event will only be received by the debugger when the condition tests to be true on the debuggee; if it fails, the debugger can still test the condition. 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.

Explicit Interface Implementations

IDisposable.Dispose()

To be added. (Inherited from DkmRuntimeBreakpoint)