1 /*
2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.jdi;
27 import java.util.List;
28
29 /**
30 * A thread object from the target VM.
31 * A ThreadReference is an {@link ObjectReference} with additional
32 * access to thread-specific information from the target VM.
33 *
34 * @author Robert Field
35 * @author Gordon Hirsch
36 * @author James McIlree
37 * @since 1.3
38 */
39 public interface ThreadReference extends ObjectReference {
40 /** Thread status is unknown */
41 public final int THREAD_STATUS_UNKNOWN =-1;
42 /** Thread has completed execution */
43 public final int THREAD_STATUS_ZOMBIE = 0;
44 /** Thread is runnable */
45 public final int THREAD_STATUS_RUNNING = 1;
46 /** Thread is sleeping - Thread.sleep() or JVM_Sleep() was called */
47 public final int THREAD_STATUS_SLEEPING = 2;
48 /** Thread is waiting on a java monitor */
49 public final int THREAD_STATUS_MONITOR = 3;
50 /** Thread is waiting - Object.wait() or JVM_MonitorWait() was called */
51 public final int THREAD_STATUS_WAIT = 4;
52 /** Thread has not yet been started */
53 public final int THREAD_STATUS_NOT_STARTED = 5;
54
55 /**
56 * Returns the name of this thread.
57 *
58 * @return the string containing the thread name.
59 */
65 * {@link VirtualMachine#resume}.
66 * <p>
67 * Unlike {@link java.lang.Thread#suspend},
68 * suspends of both the virtual machine and individual threads are
69 * counted. Before a thread will run again, it must be resumed
70 * (through {@link #resume} or {@link ThreadReference#resume})
71 * the same number of times it has been suspended.
72 * <p>
73 * Suspending single threads with this method has the same dangers
74 * as {@link java.lang.Thread#suspend()}. If the suspended thread
75 * holds a monitor needed by another running thread, deadlock is
76 * possible in the target VM (at least until the suspended thread
77 * is resumed again).
78 * <p>
79 * The suspended thread is guaranteed to remain suspended until
80 * resumed through one of the JDI resume methods mentioned above;
81 * the application in the target VM cannot resume the suspended thread
82 * through {@link java.lang.Thread#resume}.
83 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
84 */
85 void suspend();
86
87 /**
88 * Resumes this thread. If this thread was not previously suspended
89 * through {@link #suspend} or through {@link VirtualMachine#suspend},
90 * or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then
91 * invoking this method has no effect. Otherwise, the count of pending
92 * suspends on this thread is decremented. If it is decremented to 0,
93 * the thread will continue to execute.
94 * Note: the normal way to resume from an event related suspension is
95 * via {@link com.sun.jdi.event.EventSet#resume}.
96 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
97 */
98 void resume();
99
100 /**
101 * Returns the number of pending suspends for this thread. See
102 * {@link #suspend} for an explanation of counted suspends.
103 * @return pending suspend count as an integer
104 */
105 int suspendCount();
106
107 /**
108 * Stops this thread with an asynchronous exception.
109 * A debugger thread in the target VM will stop this thread
110 * with the given {@link java.lang.Throwable} object.
111 *
112 * @param throwable the asynchronous exception to throw.
113 * @throws InvalidTypeException if <code>throwable</code> is not
114 * an instance of java.lang.Throwable in the target VM.
115 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
116 * @see java.lang.Thread#stop(Throwable)
117 */
118 void stop(ObjectReference throwable) throws InvalidTypeException;
119
120 /**
121 * Interrupts this thread unless the thread has been suspended by the
122 * debugger.
123 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
124 *
125 * @see java.lang.Thread#interrupt()
126 */
127 void interrupt();
128
129 /**
130 * Returns the thread's status. If the thread is not suspended the
131 * thread's current status is returned. If the thread is suspended, the
132 * thread's status before the suspension is returned (or
133 * {@link #THREAD_STATUS_UNKNOWN} if this information is not available.
134 * {@link #isSuspended} can be used to determine if the thread has been
135 * suspended.
136 *
137 * @return one of
372 * {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}.
373 *
374 * @throws IncompatibleThreadStateException if this
375 * thread is not suspended.
376 *
377 * @throws java.lang.IllegalArgumentException if <CODE>frame</CODE>
378 * is not on this thread's call stack.
379 *
380 * @throws NativeMethodException if one of the frames that would be
381 * popped is that of a native method or if the frame previous to
382 * <i>frame</i> is native.
383 *
384 * @throws InvalidStackFrameException if <CODE>frame</CODE> has become
385 * invalid. Once this thread is resumed, the stack frame is
386 * no longer valid. This exception is also thrown if there are no
387 * more frames.
388 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
389 *
390 * @since 1.4 */
391 void popFrames(StackFrame frame) throws IncompatibleThreadStateException;
392
393
394 /**
395 * Force a method to return before it reaches a return
396 * statement.
397 * <p>
398 * The method which will return early is referred to as the
399 * called method. The called method is the current method (as
400 * defined by the Frames section in the Java Virtual Machine
401 * Specification) for the specified thread at the time this
402 * method is called.
403 * <p>
404 * The thread must be suspended.
405 * The return occurs when execution of Java programming
406 * language code is resumed on this thread. Between the call to
407 * this method and resumption of thread execution, the
408 * state of the stack is undefined.
409 * <p>
410 * No further instructions are executed in the called
411 * method. Specifically, finally blocks are not executed. Note:
412 * this can cause inconsistent states in the application.
|
1 /*
2 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.jdi;
27
28 import java.util.List;
29
30 /**
31 * A thread object from the target VM.
32 * A ThreadReference is an {@link ObjectReference} with additional
33 * access to thread-specific information from the target VM.
34 *
35 * @author Robert Field
36 * @author Gordon Hirsch
37 * @author James McIlree
38 * @since 1.3
39 */
40 public interface ThreadReference extends ObjectReference {
41
42 /** Thread status is unknown */
43 public final int THREAD_STATUS_UNKNOWN =-1;
44 /** Thread has completed execution */
45 public final int THREAD_STATUS_ZOMBIE = 0;
46 /** Thread is runnable */
47 public final int THREAD_STATUS_RUNNING = 1;
48 /** Thread is sleeping - Thread.sleep() or JVM_Sleep() was called */
49 public final int THREAD_STATUS_SLEEPING = 2;
50 /** Thread is waiting on a java monitor */
51 public final int THREAD_STATUS_MONITOR = 3;
52 /** Thread is waiting - Object.wait() or JVM_MonitorWait() was called */
53 public final int THREAD_STATUS_WAIT = 4;
54 /** Thread has not yet been started */
55 public final int THREAD_STATUS_NOT_STARTED = 5;
56
57 /**
58 * Returns the name of this thread.
59 *
60 * @return the string containing the thread name.
61 */
67 * {@link VirtualMachine#resume}.
68 * <p>
69 * Unlike {@link java.lang.Thread#suspend},
70 * suspends of both the virtual machine and individual threads are
71 * counted. Before a thread will run again, it must be resumed
72 * (through {@link #resume} or {@link ThreadReference#resume})
73 * the same number of times it has been suspended.
74 * <p>
75 * Suspending single threads with this method has the same dangers
76 * as {@link java.lang.Thread#suspend()}. If the suspended thread
77 * holds a monitor needed by another running thread, deadlock is
78 * possible in the target VM (at least until the suspended thread
79 * is resumed again).
80 * <p>
81 * The suspended thread is guaranteed to remain suspended until
82 * resumed through one of the JDI resume methods mentioned above;
83 * the application in the target VM cannot resume the suspended thread
84 * through {@link java.lang.Thread#resume}.
85 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
86 */
87 @SuppressWarnings("javadoc")
88 void suspend();
89
90 /**
91 * Resumes this thread. If this thread was not previously suspended
92 * through {@link #suspend} or through {@link VirtualMachine#suspend},
93 * or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then
94 * invoking this method has no effect. Otherwise, the count of pending
95 * suspends on this thread is decremented. If it is decremented to 0,
96 * the thread will continue to execute.
97 * Note: the normal way to resume from an event related suspension is
98 * via {@link com.sun.jdi.event.EventSet#resume}.
99 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
100 */
101 void resume();
102
103 /**
104 * Returns the number of pending suspends for this thread. See
105 * {@link #suspend} for an explanation of counted suspends.
106 * @return pending suspend count as an integer
107 */
108 int suspendCount();
109
110 /**
111 * Stops this thread with an asynchronous exception.
112 * A debugger thread in the target VM will stop this thread
113 * with the given {@link java.lang.Throwable} object.
114 *
115 * @param throwable the asynchronous exception to throw.
116 * @throws InvalidTypeException if <code>throwable</code> is not
117 * an instance of java.lang.Throwable in the target VM.
118 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
119 * @see java.lang.Thread#stop(Throwable)
120 */
121 @SuppressWarnings("javadoc")
122 void stop(ObjectReference throwable) throws InvalidTypeException;
123
124 /**
125 * Interrupts this thread unless the thread has been suspended by the
126 * debugger.
127 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
128 *
129 * @see java.lang.Thread#interrupt()
130 */
131 void interrupt();
132
133 /**
134 * Returns the thread's status. If the thread is not suspended the
135 * thread's current status is returned. If the thread is suspended, the
136 * thread's status before the suspension is returned (or
137 * {@link #THREAD_STATUS_UNKNOWN} if this information is not available.
138 * {@link #isSuspended} can be used to determine if the thread has been
139 * suspended.
140 *
141 * @return one of
376 * {@link VirtualMachine#canPopFrames() VirtualMachine.canPopFrames()}.
377 *
378 * @throws IncompatibleThreadStateException if this
379 * thread is not suspended.
380 *
381 * @throws java.lang.IllegalArgumentException if <CODE>frame</CODE>
382 * is not on this thread's call stack.
383 *
384 * @throws NativeMethodException if one of the frames that would be
385 * popped is that of a native method or if the frame previous to
386 * <i>frame</i> is native.
387 *
388 * @throws InvalidStackFrameException if <CODE>frame</CODE> has become
389 * invalid. Once this thread is resumed, the stack frame is
390 * no longer valid. This exception is also thrown if there are no
391 * more frames.
392 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
393 *
394 * @since 1.4 */
395 void popFrames(StackFrame frame) throws IncompatibleThreadStateException;
396
397 /**
398 * Force a method to return before it reaches a return
399 * statement.
400 * <p>
401 * The method which will return early is referred to as the
402 * called method. The called method is the current method (as
403 * defined by the Frames section in the Java Virtual Machine
404 * Specification) for the specified thread at the time this
405 * method is called.
406 * <p>
407 * The thread must be suspended.
408 * The return occurs when execution of Java programming
409 * language code is resumed on this thread. Between the call to
410 * this method and resumption of thread execution, the
411 * state of the stack is undefined.
412 * <p>
413 * No further instructions are executed in the called
414 * method. Specifically, finally blocks are not executed. Note:
415 * this can cause inconsistent states in the application.
|