CDT/Archive/Debug/Catchpoints support

Note: The contents of this page refer to design documents reflecting work in progress of Eclipse CDT features and for some features that have never been implemented. Therefore they may not refer to the current state of CDT. Please visit CDT/designs for links to the maintained and up to date design documents.

Overview

This document describe design ideas of adding event breakpoints (catchpoints) support to CDT. Event Breakpoints are special breakpoints which are similar to event handlers in eclipse, they don't attach to resource like regular breakpoints; but instead they attach to debugger events. Event can be for example "catch exception" or something like "load library event".

bug 226689

Please leave your comments here: Talk:CDT:_Debug:_Catchpoints_support

Workflow & UI

• Adding an event breakpoint
  • From breakpoints view, invoke action Add Event Breakpoint...

    Dialog opens. Dialog contains type of event to catch and maybe additional argument field. User edit it press Ok.

    

    Creating extensible Add Breakpoint contributions is covered by bug 227394. It most likely not going to make Ganymede so for now I can just add it context menu or in view menu.

    If no contributions to event breakpoint types been made, action should be disabled or give appropriate error when attempt to run

  • From console, triggers adding breakpoints by backend - Breakpoint appears in the list
• Removing an event breakpoint
  • Removing event breakpoint from breakpoints view, select breakpoint, right click -> Delete
  • From console, triggers deleting breakpoint by backend
• Viewing/Editing
  
  
  • Event breakpoint is visible as Element in Breakpoints view. Label contains event type label and argument, followed by default cEventBreakpoint attributes
  • Select event breakpoint in breakpoints view, right click -> Show breakpoint properties
  • Event breakpoint properties contain common page, conditions and triggered actions.
  • Common tab is similar to a standard breakpoint except file/line stuff, and in addition it has event type and extra control for event argument (viewing or editing).

Event Breakpoint contributions

• Main Event Breakpoint attributes would consist of event type (String) and Extra argument (Object)
• We need the following contributions one way or another:
• 1) Label for event type. This will be visible in Breakpoints view as a part of element Label, in Add Breakpoint wizard/dialog, in Breakpoint Properties
• 2) Part of label for event argument, to be visible in Breakpoint view
• 3) Custom control for creating event argument, in Add Breakpoint wizard/dialog
• 4) Custom control for viewing/modifying event argument, for Common properties page

To implement 1 we need some sort of event breakpoint type registry.

To implement 2:

• 2a Use toString method of Argument type in event breakpoint label provider
• 2b Implement adapters mechanism for ILabelProvider (Breakpoints view does not support IElementLabelProvider yet)

To implement 3 and 4 we can use same control, which can contributed using extensions points

Now if we generalize it we can have:

• Mechanism to register a static label (text) for a new breakpoint attribute value

this allows to handle event type Label and Label for other breakpoint attributes such as hardware/software type

example: text for "gdb.catch" event type (value of org.eclipse.cdt.debug.breakpoint.type attribute) is "Exception Caught"

• Mechanism to register Label provider for a new breakpoint type element

this allows to show label for non-standard breakpoint type, like Event Breakpoint itself at the moment

example: register adapter for ILabelProvider on ICEventBreakpoint. getText() returns concatenation of event type label, extra argument, condition and count.

• Mechanism to register a list of supported values of a new breakpoint attribute

this would allow to register possible event breakpoint events.

example: extension that list contributes event types from gdb backend

• Mechanism to register extension Control for Common property page to show a new breakpoint attribute

this allows to actually view custom breakpoint attributes in Common page. If it is just one attribute added such as breakpoint type: hardware/software viewing them in separate property page is overkill

example: extension that contribute property page to create extra argument (C/C++ type) for exception event breakpoint

Implementation

• CBreakpoint already provides extensibility mechanism that can be used for catchpoint contributions (BreakpointExtention)?
• To represent event type there is two options: use marker type or use marker attribute. I will go with attribute for now.

Public API

• Add interface org.eclipse.cdt.debug.core.model.ICEventBreakpoint extends ICBreakpoint
  • In there define strings for 2 addition marker attributes: event type id and event argument
  • Define 2 getter methods for these attribute
• Add interface org.eclipse.cdt.debug.core.cdi.model.ICDIEventBreakpoint extends ICDIBreakpoint

Other changes

• Add class org.eclipse.cdt.debug.internal.core.breakpoints.CEventBreakpoint extends CBreakpoint implements ICEventBreakpoint
• Add org.eclipse.debug.core.breakpoints extension for breakpoint markers
• Add createEventBreakpoint method in CDTDebugModel
• Support in CBreakpointManager handleBreakpontCreatedEvent

...

Platform UI (or CDT) extension for marker attribute externalizable values

Schema: CDT: Debug: breakpointUiContributions

Examples:

<extension id="com.xyz.coolMarkerLabels" point="org.eclipse.cdt.debug.ui.breakpointContribution">
    <breakpointLabels markerId="com.xyz.coolMarker"> 
    <attribute name="owner" label="Resource Owner">
       <value value="harris.bob" label="Bob Harris"/>
       <value value="harris.mary" label="Mary Harris"/>
    </attribute> 
    </breakpointLabels>
</extension>

Actual example from CDI/MI implementation:

 <extension point="org.eclipse.cdt.debug.ui.breakpointContribution">
    <breakpointLabels markerId="org.eclipse.cdt.debug.core.cEventBreakpointMarker"> 
    <attribute name="org.eclipse.cdt.debug.core.eventbreakpoint_event_id" label="Breakpoint Event Type" type="enum">
       <value value="org.eclipse.cdt.debug.gdb.catch" label="Exception Caught">
           <attribute name="org.eclipse.cdt.debug.core.catchpoint_event_arg" label="C/C++ Type" 
                type="string" fieldEditor="org.eclipse.cdt.debug.ui.breakpoints.CTypeFieldEditor">
           </attribute>
       </value>
       <value value="org.eclipse.cdt.debug.gdb.throw" label="Exception Thrown"/>
       <value value="org.eclipse.cdt.debug.gdb.signal" label="Signal Caught">
           <attribute name="org.eclipse.cdt.debug.core.eventbreakpoint_event_arg" label="Signal Number" 
                type="integer" fieldEditor="org.eclipse.jface.preference.IntegerFieldEditor">
           </attribute>
       </value>
    </attribute> 
    </breakpointLabels>
</extension>