Proposals

CDI: Flexible and Extensible

Objective

The goal of this document is to propose the CDI changes and enhancements that reflect the needs of the debugger vendors and take advantages of the enhancements in the Eclipse Platform Debug Framework (Eclipse version 3.2). The document assumes the familiarity of the reader with these features. The target release for this proposal is CDT 4.0.

Note: there are CDI enhancement requests that are not covered in this document, but should be also considered for 4.0.

Overview

C/C++ Debugger Interface (CDI) is a Java API that provides access to the state of a running program, control over the program execution and the ability to inspect the threads, stack, variables, etc. It also defines a set of events to provide a notification mechanism to the CDI clients.

Currently all CDI interfaces can be divided into the following categories:

- The extensions of ICDIObject represent the entities in the process being debugged (threads, stack frames, variables, registers, etc). The elements of this group form what is called the CDI debug model.

- The extensions of ICDISessionObject describe the elements that belong to the debug session. Sometimes the difference between this group and the previous is not obvious, but it becomes clear if the session is running in a different process, see for details the gdb/mi implementation.

- The “management” interfaces define the structural relations between the elements of the CDI debug model. For example, the object that exposes ICDSharedLibraryManagement is the parent of the ICDISharedLibrary objects.

- The “action” interfaces describe the functionalities exposed by objects. For example, ICDISuspend, ICDIExecuteStep, etc.

- The “event” interfaces define the events that can be fired by the back ends to notify the clients of the changes in the state of the process being debugged.

Some of these groups are not complete. For example, there are “action” interfaces for the suspend/resume operations, but no interfaces for terminate and disconnect. There are “management” interfaces for shared libraries and memory blocks, but the management methods for stack frames and threads are the parts of ICDIThread and ICDIThreadGroup respectively, though the ICDIThreadManagement interface have been discussed, but never added.

The following are the proposed changed in the CDI.

- Refactor the “action” methods from the ICDIObject extensions into the separate interfaces. This will NOT affect the existing implementations.

For example, moving the “isTerminated()” and “terminate()” methods from ICDITarget to the new ICDITerminate interface and add ICDITerminate to the list of interfaces that ICDITarget extends will not affect the implementations of ICDITarget.

- Refactor the “management” methods into the corresponding management interfaces. No changes in the current implementations required.

- Make ICDIObject and ICDISessionObject adaptable to allow more flexibility and avoid numerous instanceof. The issue has been widely discussed in the mailing list.

The internal CDT changes:

- Eliminate dependencies on the old Eclipse Debug Model and the CDT extension of it.

- Provide implementations of the label, content, action adapters and model proxies based directly on the CDI interfaces.

The following rules are important for this implementation.

1. The implementations of the content adapters (IAsynchronousContentAdapter) should use ONLY “management” interfaces. For example, in the “retrieveChildren()” method of IAsynchronousContentAdapter instead of :

if ( parent instanceof ICDTarget )

   ((ICDITarget)parent).getThreads()

if ( parent instanceof ICDThread )

   ((ICDIThread)parent).getStackFrames()

use the following:

if ( parent instanceof IAdaptable ) {

   ICDIThreadManagement tm = (ICDIThreadManagement)parent.getAdapter( ICDIThreadManagement );

   if ( tm != null ) {

       tm.getThreads();

   }

   ICDIStackManagement sm = (ICDIStackManagement)parent.getAdapter( ICDIStackManagement );

   if ( sm != null ) {

       sm.getStackFrames();

   }

}

2. The implementations of the action adapters should use ONLY “action” interfaces. For example, the “terminate()” method of IAsynchronousTerminateAdapter should be:

if ( parent instanceof IAdaptable ) {

   ICDITerminate t = (ICDITerminate)parent.getAdapter( ICDITerminate);

   if ( t != null ) {

       // create an asynchronous request monitor with “t”

   }

}

The advantages of these proposals are:

- Support of the flexible debug model hierarchies.

- Extensibility of the debug model.

See the following use cases.

Use Cases

1. Multicore targets

The required hierarchy of the debug model is following:

Target

Core

Thread

Stack frame

The implementers need to add a new “management” interface for cores, new action interfaces to define core-specific actions and combine these and some existing interfaces to implement the ICDIObject that represents a core.

The new content adapter (or an extension of the default content adapter) should be registered to display the core objects in the Debug view.

2. No threads

Hierarchy:

Target

Stack frame

This case is covered by the default implementation. See the example of the content adapter above.

3. Thread groups

Hierarchy:

Target

Thread group

Thread

The new ICDIThreadGroupManagement interface needs to be introduced and the content adapter should be adjusted.

Conclusion

The API changes required to implement these proposal have minimal impact on the existing implementation. Simple refactoring is needed to cover most of the cases. Making the CDI object adaptable is the only requirement that will affect the existing implementations.