Bug 1039 - Specify behavior of GLEventListener Exceptions occurring while GLAutoDrawable processing [part-3]

Add GLAnimatorControl.UncaughtGLAnimatorExceptionHandler interface to optionally handle
uncaught exception within an animator thread by the user.

Implementation also requires to flush all enqueued GLRunnable instances
via GLAutoDrawable.invoked(..) in case such exception occurs.
Hence 'GLAutoDrawable.flushGLRunnables()' has been added.

Only subsequent exceptions, which cannot be thrown are dumped to System.stderr.

+++

Handling of exceptions during dispose()

Exception in NEWT's disposeGL*() are also caught and re-thrown after
the NEWT window has been destroyed in WindowImpl.destroyAction:

  - GLEventListener.dispose(..)
    - GLDrawableHelper.disposeAllGLEventListener(..)
      - GLDrawableHelper.disposeGL(..)
        - GLAutoDrawableBase.destroyImplInLock(..)
          - GLWindow.GLLifecycleHook.destroyActionInLock(..)
            - WindowImpl.destroyAction on NEWT-EDT
              - WindowImpl.destroy

Further more, exceptions occuring in native windowing toolkit triggered destroy()
are ignored:
  - GLAutoDrawableBase.defaultWindowDestroyNotifyOp(..)

It has to be seen whether such exception handling for
dispose() shall be added to AWT/SWT.

+++

TestGLException01NEWT covers all GLEventListener exception cases
on-thread and off-thread (via animator).

+++

1 files changed, 17 insertions, 0 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index 5745e197f..bded88d20 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -229,6 +229,7 @@ public interface GLAutoDrawable extends GLDrawable {
 
   /**
    * Returns true if all added {@link GLEventListener} are initialized, otherwise false.
+   * @since 2.2
    */
   boolean areAllGLEventListenerInitialized();
 
@@ -458,6 +459,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * @see #display()
    * @see GLRunnable
    * @see #invoke(boolean, List)
+   * @see #flushGLRunnables()
    */
   public boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateException ;
 
@@ -469,9 +471,22 @@ public interface GLAutoDrawable extends GLDrawable {
    * @return <code>true</code> if the {@link GLRunnable}s has been processed or queued, otherwise <code>false</code>.
    * @throws IllegalStateException in case of a detected deadlock situation ahead, see {@link #invoke(boolean, GLRunnable)}.
    * @see #invoke(boolean, GLRunnable)
+   * @see #flushGLRunnables()
    */
   public boolean invoke(boolean wait, List<GLRunnable> glRunnables) throws IllegalStateException;
 
+  /**
+   * Flushes all {@link #invoke(boolean, GLRunnable) enqueued} {@link GLRunnable} of this {@link GLAutoDrawable}
+   * including notifying waiting executor.
+   * <p>
+   * The executor which might have been blocked until notified
+   * will be unblocked and all tasks removed from the queue.
+   * </p>
+   * @see #invoke(boolean, GLRunnable)
+   * @since 2.2
+   */
+  public void flushGLRunnables();
+
   /** Destroys all resources associated with this GLAutoDrawable,
       inclusive the GLContext.
       If a window is attached to it's implementation, it shall be closed.
@@ -602,6 +617,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * <p>
    * See <a href="#locking">GLAutoDrawable Locking</a>.
    * </p>
+   * @since 2.2
    */
   public RecursiveLock getUpstreamLock();
 
@@ -613,6 +629,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * whether {@link #display()} performs the OpenGL commands on the current thread directly
    * or spawns them on the dedicated OpenGL thread.
    * </p>
+   * @since 2.2
    */
   public boolean isThreadGLCapable();