01: /*
02: * Copyright 1998-2005 Sun Microsystems, Inc. All Rights Reserved.
03: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
04: *
05: * This code is free software; you can redistribute it and/or modify it
06: * under the terms of the GNU General Public License version 2 only, as
07: * published by the Free Software Foundation. Sun designates this
08: * particular file as subject to the "Classpath" exception as provided
09: * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22: * CA 95054 USA or visit www.sun.com if you need additional information or
23: * have any questions.
24: */
25:
26: package com.sun.jdi.event;
27:
28: import com.sun.jdi.*;
29:
30: /**
31: * Manager of incoming debugger events for a target VM.
32: * Events are always grouped in {@link EventSet}s.
33: * EventSets generated by the debugger back end can be read
34: * here. There is one instance of EventQueue assigned to a particular
35: * {@link com.sun.jdi.VirtualMachine VirtualMachine}.
36: * <P>
37: * Some events cause the suspension of the target VM - event requests
38: * ({@link com.sun.jdi.request}) with a
39: * {@link com.sun.jdi.request.EventRequest#suspendPolicy() suspend policy}
40: * of {@link com.sun.jdi.request.EventRequest#SUSPEND_ALL SUSPEND_ALL}
41: * or {@link com.sun.jdi.request.EventRequest#SUSPEND_EVENT_THREAD
42: * SUSPEND_EVENT_THREAD} and sometimes
43: * {@link VMStartEvent}.
44: * If these suspensions are not resumed the target VM will hang.
45: * Thus, it is always good policy to
46: * {@link #remove() remove()} every EventSet from the
47: * event queue until an EventSet containing a
48: * {@link VMDisconnectEvent} is read.
49: * Unless {@link com.sun.jdi.VirtualMachine#resume() resume} is
50: * being handled in another way, each EventSet should invoke
51: * {@link EventSet#resume()}.
52: *
53: * @see EventSet
54: * @see VirtualMachine
55: *
56: * @author Robert Field
57: * @since 1.3
58: */
59:
60: public interface EventQueue extends Mirror {
61:
62: /**
63: * Waits forever for the next available event.
64: *
65: * @return the next {@link EventSet}.
66: * @throws InterruptedException if any thread has interrupted
67: * this thread.
68: * @throws com.sun.jdi.VMDisconnectedException if the connection
69: * to the target VM is no longer available. Note this will always
70: * be preceded by a {@link com.sun.jdi.event.VMDisconnectEvent}.
71: */
72: EventSet remove() throws InterruptedException;
73:
74: /**
75: * Waits a specified time for the next available event.
76: *
77: * @param timeout Time in milliseconds to wait for the next event
78: * @return the next {@link EventSet}, or null if there is a timeout.
79: * @throws InterruptedException if any thread has interrupted
80: * this thread.
81: * @throws com.sun.jdi.VMDisconnectedException if the connection
82: * to the target VM is no longer available. Note this will always
83: * be preceded by a {@link com.sun.jdi.event.VMDisconnectEvent}.
84: * @throws IllegalArgumentException if the timeout argument
85: * contains an illegal value.
86: */
87: EventSet remove(long timeout) throws InterruptedException;
88: }
|