JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
EDTUtil.java
Go to the documentation of this file.
1/**
2 * Copyright 2010 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.newt.util;
30
31import jogamp.newt.DisplayImpl;
32import com.jogamp.newt.event.NEWTEvent;
33
34/**
35 * EDT stands for Event Dispatch Thread.
36 * <p>
37 * EDTUtil comprises the functionality of:
38 * <ul>
39 * <li> Periodically issuing an event dispatch command on the EDT.</li>
40 * <li> Ability to enqueue tasks, executed on the EDT.</li>
41 * <li> Controlling the EDT, ie start and stop in a sane manner.</li>
42 * </ul>
43 * The EDT pattern is a common tool to comply with todays windowing toolkits,
44 * where the common denominator in regards to multithreading is to:
45 * <ul>
46 * <li> Create a Window on one thread </li>
47 * <li> Modify the Window within the same thread </li>
48 * <li> Handle incoming events from within the same thread </li>
49 * </ul>
50 * Note: This is not true on MacOSX, where all these actions have to be
51 * performed by a unique, so called main thread.<br>
52 */
53public interface EDTUtil {
54
55 public static final long defaultEDTPollPeriod = 10; // 10ms, 1/100s
56
57 /**
58 * @return poll period in milliseconds
59 */
60 public long getPollPeriod();
61
62 /**
63 * @param ms poll period in milliseconds
64 */
65 public void setPollPeriod(long ms);
66
67 /**
68 * Starts the EDT after it's creation or after {@link #invokeStop(boolean, Runnable) stopping}.
69 * <p>
70 * If the EDT is running, it must be {@link #invokeStop(boolean, Runnable) stopped} first
71 * and the caller should wait {@link #waitUntilStopped() until it's stopped}.
72 * </p>
73 *
74 * @throws IllegalStateException if EDT is running and not subject to be stopped, i.e. {@link #isRunning()} returns true
75 * @throws RuntimeException if EDT could not be started
76 *
77 * @see #invokeStop(boolean, java.lang.Runnable)
78 * @see #waitUntilStopped()
79 */
80 public void start() throws IllegalStateException;
81
82 /**
83 * Returns true if the current thread is the event dispatch thread (EDT).
84 * <p>
85 * The EDT is the platform specific thread dispatching toolkit-events
86 * and executing toolkit-tasks enqueued via {@link #invoke(boolean, Runnable)}.
87 * </p>
88 * <p>
89 * Usually it is the same thread as used to dequeue informal {@link NEWTEvent}s (NEDT), see {@link #isCurrentThreadNEDT()},
90 * however, this may differ, e.g. SWT and AWT implementation.
91 * </p>
92 */
93 public boolean isCurrentThreadEDT();
94
95 /**
96 * Returns true if the current thread is the internal NEWT event dequeue thread (NEDT).
97 * <p>
98 * The NEDT is the NEWT thread used to dequeue informal {@link NEWTEvent}s enqueued internally
99 * via {@link DisplayImpl#enqueueEvent(boolean, NEWTEvent)}.
100 * </p>
101 * <p>
102 * Usually it is the same thread as the EDT, see {@link #isCurrentThreadEDT()},
103 * however, this may differ, e.g. SWT and AWT implementation.
104 * </p>
105 */
106 public boolean isCurrentThreadNEDT();
107
108 /**
109 * Returns <code>true</code> if either {@link #isCurrentThreadEDT()} or {@link #isCurrentThreadNEDT()} is <code>true</code>,
110 * otherwise <code>false</code>.
111 */
112 public boolean isCurrentThreadEDTorNEDT();
113
114 /**
115 * @return True if EDT is running and not subject to be stopped.
116 */
117 public boolean isRunning();
118
119 /**
120 * Append the final task to the EDT task queue,
121 * signals EDT to stop.
122 * <p>
123 * If <code>wait</code> is <code>true</code> methods
124 * blocks until EDT is stopped.
125 * </p>
126 * <p>
127 * <code>task</code> maybe <code>null</code><br/>
128 * Due to the nature of this method:
129 * <ul>
130 * <li>All previous queued tasks will be finished.</li>
131 * <li>No new tasks are allowed, an Exception is thrown.</li>
132 * <li>Can be issued from within EDT, ie from within an enqueued task.</li>
133 * <li>{@link #start()} may follow immediately, ie creating a new EDT</li>
134 * </ul>
135 * </p>
136 * @return true if <code>task</code> has been executed or queued for later execution, otherwise false
137 */
138 public boolean invokeStop(boolean wait, Runnable finalTask);
139
140 /**
141 * Appends task to the EDT task queue if current thread is not EDT,
142 * otherwise execute task immediately.
143 * <p>
144 * Wait until execution is finished if <code>wait == true</code>.
145 * </p>
146 * Can be issued from within EDT, ie from within an enqueued task.<br>
147 * @return true if <code>task</code> has been executed or queued for later execution, otherwise false
148 */
149 public boolean invoke(boolean wait, Runnable task);
150
151 /**
152 * Wait until the EDT task queue is empty.<br>
153 * The last task may still be in execution when this method returns.
154 * @return true if waited for idle, otherwise false, i.e. in case of current thread is EDT or NEDT
155 */
156 public boolean waitUntilIdle();
157
158 /**
159 * Wait until EDT task is stopped.<br>
160 * No <code>stop</code> action is performed, {@link #invokeStop(boolean, java.lang.Runnable)} should be used before.
161 * <p>
162 * If caller thread is EDT or NEDT, this call will not block.
163 * </p>
164 * @return true if stopped, otherwise false, i.e. in case of current thread is EDT or NEDT
165 */
166 public boolean waitUntilStopped();
167}
168
EDT stands for Event Dispatch Thread.
Definition: EDTUtil.java:53
boolean isCurrentThreadNEDT()
Returns true if the current thread is the internal NEWT event dequeue thread (NEDT).
boolean isCurrentThreadEDT()
Returns true if the current thread is the event dispatch thread (EDT).
static final long defaultEDTPollPeriod
Definition: EDTUtil.java:55
boolean invokeStop(boolean wait, Runnable finalTask)
Append the final task to the EDT task queue, signals EDT to stop.
void start()
Starts the EDT after it's creation or after stopping.
boolean waitUntilIdle()
Wait until the EDT task queue is empty.
boolean isCurrentThreadEDTorNEDT()
Returns true if either isCurrentThreadEDT() or isCurrentThreadNEDT() is true, otherwise false.
boolean invoke(boolean wait, Runnable task)
Appends task to the EDT task queue if current thread is not EDT, otherwise execute task immediately.
boolean waitUntilStopped()
Wait until EDT task is stopped.