← Back to branch summary

~ubuntu-branches/debian/sid/eclipse-cdt/sid

« back to all changes in this revision

Viewing changes to dsf-gdb/org.eclipse.cdt.dsf.gdb/src/org/eclipse/cdt/dsf/gdb/service/IGDBBackend.java

  • Committer: Package Import Robot
  • Author(s): Jakub Adam
  • Date: 2011-10-06 21:15:04 UTC
  • mfrom: (1.1.4)
  • Revision ID: package-import@ubuntu.com-20111006211504-8dutmljjih0zikfv
Tags: 8.0.1-1
* New upstream release.
* Split the JNI packages into a separate architecture dependent
  package and made eclipse-cdt architecture independent.
* Install JNI libraries into multiarch aware location
* Bumped Standards-Version to 3.9.2.

Show diffs side-by-side

added added

removed removed

Lines of Context:
dsf-gdb/org.eclipse.cdt.dsf.gdb/src/org/eclipse/cdt/dsf/gdb/service/IGDBBackend.java
 
1
/*******************************************************************************
 
2
 * Copyright (c) 2008, 2010 Nokia Corporation.
 
3
 * All rights reserved. This program and the accompanying materials
 
4
 * are made available under the terms of the Eclipse Public License v1.0
 
5
 * which accompanies this distribution, and is available at
 
6
 * http://www.eclipse.org/legal/epl-v10.html
 
7
 *
 
8
 * Contributors:
 
9
 *    Nokia    - initial version
 
10
 *    Ericsson - Minor cleanup
 
11
 *******************************************************************************/
 
12
package org.eclipse.cdt.dsf.gdb.service;
 
13
 
 
14
import java.util.List;
 
15
import java.util.Properties;
 
16
 
 
17
import org.eclipse.cdt.dsf.concurrent.RequestMonitor;
 
18
import org.eclipse.cdt.dsf.mi.service.IMIBackend;
 
19
import org.eclipse.core.runtime.CoreException;
 
20
import org.eclipse.core.runtime.IPath;
 
21
 
 
22
/**
 
23
 * Service that manages back end GDB process, such as launching and monitoring
 
24
 * GDB process, managing certain GDB parameters/options. This service makes it
 
25
 * easy for debugger implementations to customize the way to start GDB process
 
26
 * and convert some parameters if needed. See bug 240092 for more.<br>
 
27
 * <br>
 
28
 * A base implementation {@link GDBBackend} is provided that should be
 
29
 * sufficient for most cases. But if you have special needs, it's recommended to
 
30
 * subclass the base implementation. <br>
 
31
 * <br>
 
32
 * Here are some special cases: <br>
 
33
 * Example #1: GDB is usually launched on the host machine where Eclipse is
 
34
 * running, but it can also be launched on a remote machine through, say, SSH. <br>
 
35
 * Example #2: GDB is usually launched in the host file system, but it can also
 
36
 * be launched in a chroot'ed file system such as Scratchbox (see
 
37
 * http://www.scratchbox.org)<br>
 
38
 *
 
39
 * @since 1.1
 
40
 */
 
41
public interface IGDBBackend extends IMIBackend {
 
42
 
 
43
        /** 
 
44
         * ID to use when requesting that the interruptAndWait call wait for an
 
45
         * implementation-specific default.
 
46
         * @since 3.0 */
 
47
        public final static int INTERRUPT_TIMEOUT_DEFAULT = 0;
 
48
 
 
49
        /**
 
50
         * Get path of the debugged program on host.
 
51
         * 
 
52
         * @return IPath
 
53
         */
 
54
        public IPath getProgramPath();
 
55
 
 
56
        /**
 
57
         * Get init file for GDB.
 
58
         * 
 
59
         * @return file name, may have relative or absolute path, or empty string ("") 
 
60
         *         indicating an init file is not specified.
 
61
         * @throws CoreException
 
62
         *             - error in getting the option.
 
63
         */
 
64
        public String getGDBInitFile() throws CoreException;
 
65
 
 
66
        /**
 
67
         * get arguments for the debugged program.
 
68
         * 
 
69
         * @return String
 
70
         * @throws CoreException
 
71
         *             - error in getting the option.
 
72
         */
 
73
        public String getProgramArguments() throws CoreException;
 
74
 
 
75
        /**
 
76
         * Get working directory for GDB. 
 
77
         * 
 
78
         * @return IPath - null if no meaningful value found.
 
79
         * @throws CoreException
 
80
         *             - if any error occurs.
 
81
         */
 
82
        public IPath getGDBWorkingDirectory() throws CoreException;
 
83
 
 
84
        /**
 
85
         * @throws CoreException
 
86
         *             - error in getting the option.
 
87
         */
 
88
        public List<String> getSharedLibraryPaths() throws CoreException;
 
89
 
 
90
        /**
 
91
         * Returns the list of user-specified variables.
 
92
         * If no variables are specified, should return an empty list.
 
93
         * Should not return null.
 
94
         * 
 
95
         *  @since 3.0 
 
96
         */
 
97
        public Properties getEnvironmentVariables() throws CoreException;
 
98
        
 
99
        /** 
 
100
         * Returns whether the native environment should be cleared before
 
101
         * setting the user-specified environment variables.
 
102
         * 
 
103
         * @since 3.0 */
 
104
        public boolean getClearEnvironment() throws CoreException;
 
105
        
 
106
        /**
 
107
         * Sends an interrupt signal to the GDB process.
 
108
         */
 
109
        public void interrupt();
 
110
        
 
111
        /**
 
112
         * Interrupts the backend and wait to confirm the interrupt 
 
113
         * succeeded.  The request monitor indicates to the caller if 
 
114
         * the interrupt succeeded or not.
 
115
         * 
 
116
         * @param timeout Maximum number of milliseconds to wait to confirm
 
117
         *                that the backend has been interrupted.  A value
 
118
         *                of INTERRUPT_TIMEOUT_DEFAULT specifies to use an 
 
119
         *                implementation-specific default value.
 
120
         *                Using a value of 0 or a negative value has unspecified
 
121
         *                behavior. 
 
122
         *
 
123
         * @since 3.0
 
124
         */
 
125
        public void interruptAndWait(int timeout, RequestMonitor rm);
 
126
 
 
127
        /**
 
128
         * Same as {@link #interruptAndWait(int, RequestMonitor)}, except the
 
129
         * inferior process is directly interrupted.
 
130
         *
 
131
         * @param pid the PID of the inferior
 
132
         * @since 3.0
 
133
         */
 
134
        public void interruptInferiorAndWait(long pid, int timeout, RequestMonitor rm);
 
135
 
 
136
        /**
 
137
         * @return The type of the session currently ongoing with the backend
 
138
         */
 
139
        public SessionType getSessionType();
 
140
 
 
141
        /**
 
142
         * @return true if the ongoing session is attaching to a program locally or remotely.
 
143
         */     
 
144
        public boolean getIsAttachSession();
 
145
 
 
146
        /**
 
147
         * Indicates whether the CDT debugger should ask gdb for the target
 
148
         * program's thread list on each suspend event (breakpoint-hit, step, etc).
 
149
         * Normally, this isn't necessary, as GDB sends notifications in realtime
 
150
         * when a thread is created or destroyed. However, some lightweight GDB
 
151
         * remote stubs won't send these notifications. As such, the CDT debugger
 
152
         * doesn't find out about new or destroyed threads unless it polls gdb. The
 
153
         * user will enable this behavior if he is debugging such a target
 
154
         * (typically an embedded one)
 
155
         * 
 
156
         * @since 3.0
 
157
         */
 
158
        public boolean getUpdateThreadListOnSuspend() throws CoreException;
 
159
}