NEWT EDTUtil: Exposed weakness of EDTUtil usage due to usage of WeakReference, i.e. higher retention of Display instances.

- WeakReference Change 99479bf3197cde8e89c5b499d135417863d521c7

- Refines commits:
  feb352145af1643a57eaae99c0342e6f5e0f2a2e
  dec4b02fe4b93028c85de6a56b6af79601042d6e
  433e3914324b90c910b018bb7d9d80e814c67123

Reviews EDTUtil API and usage:
  - less confusing / more determined EDTUtil API
  - EDTUtil's thread shall only be reset and started when required (-> lazy)
  - EDTUtil's instance in Display shall be handled thread safe w/o extra blocking
  - EDTUtil's implementations (Default, SWT and AWT) shall be aligned / similar as much as possible

Further note: SWT's EDTUtil (NewtCanvasSWT) shall not use a reused Display instance due to it's
              custom SWTEDTUtil. We may need to disable the ref. cache if custom EDTUtil (setEDTUtil)
              is intended (used).

3 files changed, 35 insertions, 29 deletions

diff --git a/src/newt/classes/com/jogamp/newt/Display.java b/src/newt/classes/com/jogamp/newt/Display.java
index 4f5df6c70..c618405c2 100644
--- a/src/newt/classes/com/jogamp/newt/Display.java
+++ b/src/newt/classes/com/jogamp/newt/Display.java
@@ -154,26 +154,25 @@ public abstract class Display {
     /**
      * Sets a new {@link EDTUtil} and returns the previous one.
      * <p>
-     * If <code>newEDTUtil</code> is <code>null</code>, 
+     * If <code>usrEDTUtil</code> is <code>null</code>, 
      * the device's default EDTUtil is created and used.
      * </p>
      * <p>
-     * If a previous one exists and it differs from the new one, 
-     * it's being stopped, wait-until-idle and reset to allow a restart at a later time.
+     * If a previous one exists and it differs from <code>usrEDTUtil</code>, 
+     * it's being stopped, wait-until-idle.
      * </p>
      * <p>
-     * If <code>newEDTUtil</code> is not null and equals the previous one,
+     * If <code>usrEDTUtil</code> is not null and equals the previous one,
      * no change is being made.
      * </p>
-     * <p>
-     * Note that <code>newEDTUtil</code> will be started by this method,
-     * if it is not running yet.
-     * </p>
      */
-    public abstract EDTUtil setEDTUtil(EDTUtil newEDTUtil);
+    public abstract EDTUtil setEDTUtil(EDTUtil usrEDTUtil);
     
     public abstract EDTUtil getEDTUtil();
 
+    /**
+     * @return true if EDT is running and not subject to be stopped, otherwise false.
+     */
     public abstract boolean isEDTRunning();
 
     public abstract void dispatchMessages();
diff --git a/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java b/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
index dbe7c0d98..47dfca0f3 100644
--- a/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
+++ b/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
@@ -345,7 +345,9 @@ public class NewtCanvasSWT extends Canvas implements WindowClosingProtocol {
             // set SWT EDT and start it
             {
                 final Display newtDisplay = newtChild.getScreen().getDisplay();
-                newtDisplay.setEDTUtil( new SWTEDTUtil(newtDisplay, getDisplay()) );
+                final EDTUtil edtUtil = new SWTEDTUtil(newtDisplay, getDisplay());
+                edtUtil.restart();
+                newtDisplay.setEDTUtil( edtUtil );
             }
             
             newtChild.setSize(w, h);            
diff --git a/src/newt/classes/com/jogamp/newt/util/EDTUtil.java b/src/newt/classes/com/jogamp/newt/util/EDTUtil.java
index 75848785c..e86df2084 100644
--- a/src/newt/classes/com/jogamp/newt/util/EDTUtil.java
+++ b/src/newt/classes/com/jogamp/newt/util/EDTUtil.java
@@ -65,18 +65,19 @@ public interface EDTUtil {
     public void setPollPeriod(long ms);
     
     /**
-     * Resets the stopped EDT, i.e. prepares it for a restart via
-     * the next <code>invoke(..)</code>  call.
+     * Starts or restarts the EDT.
      * <p>
-     * One must stop the EDT first via {@link #invokeStop(boolean, Runnable)}
-     * and wait until it's stopped via {@link #waitUntilStopped()}.
+     * If the EDT is running, it must be stopped first via {@link #invokeStop(boolean, Runnable)}
+     * and the caller should wait until it's stopped via {@link #waitUntilStopped()}.
      * </p>
-     *
-     * @see #invoke(boolean, java.lang.Runnable)
+     * 
+     * @return true if EDT has been successfully restarted, otherwise false
+     * @throws IllegalStateException if EDT is running and not subject to be stopped, i.e. {@link #isRunning()} returns true
+     *  
      * @see #invokeStop(boolean, java.lang.Runnable)
-     * @throws IllegalStateException if stop has not been issued, or EDT is still running (caller thread not being EDT or NEDT). 
+     * @see #waitUntilStopped()
      */
-    public void reset() throws IllegalStateException;
+    public boolean restart() throws IllegalStateException;
 
     /**
      * Returns true if the current thread is the event dispatch thread (EDT).
@@ -111,7 +112,7 @@ public interface EDTUtil {
     public boolean isCurrentThreadEDTorNEDT();
     
     /**
-     * @return True if EDT is running
+     * @return True if EDT is running and not subject to be stopped.
      */
     public boolean isRunning();
 
@@ -129,27 +130,30 @@ public interface EDTUtil {
      *   <li>All previous queued tasks will be finished.</li>
      *   <li>No new tasks are allowed, an Exception is thrown.</li>
      *   <li>Can be issued from within EDT, ie from within an enqueued task.</li>
-     *   <li>{@link #reset()} may follow immediately, ie creating a new EDT</li>
+     *   <li>{@link #restart()} may follow immediately, ie creating a new EDT</li>
      * </ul>
      * </p>
+     * @return true if <code>task</code> has been executed or queued for later execution, otherwise false 
      */
-    public void invokeStop(boolean wait, Runnable finalTask);
+    public boolean invokeStop(boolean wait, Runnable finalTask);
 
     /** 
-     * Shall start the thread if not running, <code>task</code> maybe null for this purpose.<br>
-     * Append task to the EDT task queue.<br>
-     * Wait until execution is finished if <code>wait == true</code>.<br>
+     * Appends task to the EDT task queue if current thread is not EDT,
+     * otherwise execute task immediately. 
+     * <p>
+     * Wait until execution is finished if <code>wait == true</code>.
+     * </p>
      * Can be issued from within EDT, ie from within an enqueued task.<br>
-     *
-     * @throws RuntimeException in case EDT is stopped and not {@link #reset()}
+     * @return true if <code>task</code> has been executed or queued for later execution, otherwise false 
      */
-    public void invoke(boolean wait, Runnable task);
+    public boolean invoke(boolean wait, Runnable task);
 
     /** 
      * Wait until the EDT task queue is empty.<br>
      * The last task may still be in execution when this method returns.
+     * @return true if waited for idle, otherwise false, i.e. in case of current thread is EDT or NEDT
      */
-    public void waitUntilIdle();
+    public boolean waitUntilIdle();
 
     /**
      * Wait until EDT task is stopped.<br>
@@ -157,7 +161,8 @@ public interface EDTUtil {
      * <p>
      * If caller thread is EDT or NEDT, this call will not block.
      * </p>
+     * @return true if stopped, otherwise false, i.e. in case of current thread is EDT or NEDT
      */
-    public void waitUntilStopped();
+    public boolean waitUntilStopped();
 }