Bug 1033: Guarantee atomicity of high-level GLAutoDrawable operations, avoiding race conditions.

GLAutoDrawable (API CHANGE) allowing atomic operations:
  - Add class API-doc chapter about 'GLAutoDrawable Locking'

  - Add method invoke(..) API-doc description about throwing IllegalStateException in case of a detected deadlock situation ahead
    (Note: Implemented in GLDrawableHelper.invoke(..) for all implementations)

  - Add new methods for proper multithread handling:
    - public RecursiveLock getUpstreamLock();
    - public boolean isThreadGLCapable();

+++

GLEventListenerState/GLDrawableUtil:

  - Perform operation in a atomic fashion,
    i.e. lock GLAutoDrawable during whole operations:
      - GLDrawableUtil.swapGLContext(..)
      - GLDrawableUtil.swapGLContextAndAllGLEventListener(..)
      - GLEventListenerState.moveFrom(..)
      - GLEventListenerState.moveTo(..)

  - ReshapeGLEventListener:
    - Moved from GLEventListenerState.ReshapeGLEventListener -> GLDrawableUtil.ReshapeGLEventListener
    - Takes 'displayAfterReshape' case into account.

+++

javax.media.opengl.Threading Clarifications:
  - Public 'enum Mode', i.e. Threading.Mode

  - Public getMode()

  - Clarified 'isOpenGLThread()':
    - Take 'singleThreaded' into account directly,
      i.e. always return 'true' if singleThreaded == false

1 files changed, 14 insertions, 2 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index e58d8c64a..eae5948ed 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -638,6 +638,9 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
    }
 
    @Override
+   public final RecursiveLock getUpstreamLock() { return lock; }
+
+   @Override
    public int getSurfaceWidth() {
       return clientArea.width;
    }
@@ -755,12 +758,12 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
    }
 
    @Override
-   public boolean invoke(final boolean wait, final GLRunnable runnable) {
+   public boolean invoke(final boolean wait, final GLRunnable runnable) throws IllegalStateException {
       return helper.invoke(this, wait, runnable);
    }
 
    @Override
-   public boolean invoke(final boolean wait, final List<GLRunnable> runnables) {
+   public boolean invoke(final boolean wait, final List<GLRunnable> runnables) throws IllegalStateException {
       return helper.invoke(this, wait, runnables);
    }
 
@@ -879,6 +882,15 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
    }
 
    /**
+    * {@inheritDoc}
+    * <p>
+    * Implementation always supports multithreading, hence method always returns <code>true</code>.
+    * </p>
+    */
+   @Override
+   public final boolean isThreadGLCapable() { return true; }
+
+   /**
     * Runs the specified action in an SWT compatible thread, which is:
     * <ul>
     *   <li>Mac OSX