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, 22 insertions, 14 deletions

diff --git a/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java b/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
index fce5c1fcc..605c3fce8 100644
--- a/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
+++ b/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
@@ -57,9 +57,11 @@ import com.jogamp.opengl.GLStateKeeper;
 
 
 /**
- * Abstract common code for GLAutoDrawable implementations.
+ * Abstract common code for GLAutoDrawable implementations
+ * utilizing multithreading, i.e. {@link #isThreadGLCapable()} always returns <code>true</code>.
  *
  * @see GLAutoDrawable
+ * @see GLAutoDrawable#getThreadingMode()
  * @see GLAutoDrawableDelegate
  * @see GLOffscreenAutoDrawable
  * @see GLOffscreenAutoDrawableImpl
@@ -123,9 +125,6 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
         helper.setSharedAutoDrawable(this, sharedAutoDrawable);
     }
 
-    /** Returns the recursive lock object of the upstream implementation, which synchronizes multithreaded access on top of {@link NativeSurface#lockSurface()}. */
-    protected abstract RecursiveLock getLock();
-
     @Override
     public final GLStateKeeper.Listener setGLStateKeeperListener(final Listener l) {
         final GLStateKeeper.Listener pre = glStateKeeperListener;
@@ -240,7 +239,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
                 System.err.println("GLAutoDrawableBase.sizeChanged: ("+getThreadName()+"): "+newWidth+"x"+newHeight+" - surfaceHandle 0x"+Long.toHexString(surfaceHandle));
             }
             if( ! _drawable.getChosenGLCapabilities().isOnscreen() ) {
-                final RecursiveLock _lock = getLock();
+                final RecursiveLock _lock = getUpstreamLock();
                 _lock.lock();
                 try {
                     final GLDrawableImpl _drawableNew = GLDrawableHelper.resizeOffscreenDrawable(_drawable, context, newWidth, newHeight);
@@ -332,7 +331,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
      * Calls {@link #destroyImplInLock()} while claiming the lock.
      */
     protected final void defaultDestroy() {
-        final RecursiveLock lock = getLock();
+        final RecursiveLock lock = getUpstreamLock();
         lock.lock();
         try {
             destroyImplInLock();
@@ -380,7 +379,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
     }
 
     public final void defaultSwapBuffers() throws GLException {
-        final RecursiveLock _lock = getLock();
+        final RecursiveLock _lock = getUpstreamLock();
         _lock.lock();
         try {
             if(null != drawable) {
@@ -421,7 +420,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
             destroy();
             return;
         }
-        final RecursiveLock _lock = getLock();
+        final RecursiveLock _lock = getUpstreamLock();
         _lock.lock();
         try {
             if( null == context ) {
@@ -452,7 +451,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
     }
 
     protected final GLEventListener defaultDisposeGLEventListener(final GLEventListener listener, final boolean remove) {
-        final RecursiveLock _lock = getLock();
+        final RecursiveLock _lock = getUpstreamLock();
         _lock.lock();
         try {
             return helper.disposeGLEventListener(GLAutoDrawableBase.this, drawable, context, listener, remove);
@@ -473,7 +472,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
 
     @Override
     public final GLContext setContext(final GLContext newCtx, final boolean destroyPrevCtx) {
-        final RecursiveLock lock = getLock();
+        final RecursiveLock lock = getUpstreamLock();
         lock.lock();
         try {
             final GLContext oldCtx = context;
@@ -571,12 +570,12 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
     }
 
     @Override
-    public final boolean invoke(final boolean wait, final GLRunnable glRunnable) {
+    public final boolean invoke(final boolean wait, final GLRunnable glRunnable) throws IllegalStateException {
         return helper.invoke(this, wait, glRunnable);
     }
 
     @Override
-    public boolean invoke(final boolean wait, final List<GLRunnable> glRunnables) {
+    public boolean invoke(final boolean wait, final List<GLRunnable> glRunnables) throws IllegalStateException {
         return helper.invoke(this, wait, glRunnables);
     }
 
@@ -604,6 +603,15 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
         return additionalCtxCreationFlags;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Implementation always supports multithreading, hence method always returns <code>true</code>.
+     * </p>
+     */
+    @Override
+    public final boolean isThreadGLCapable() { return true; }
+
     //
     // FPSCounter
     //
@@ -664,7 +672,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
 
     @Override
     public final GLContext createContext(final GLContext shareWith) {
-        final RecursiveLock lock = getLock();
+        final RecursiveLock lock = getUpstreamLock();
         lock.lock();
         try {
             if(drawable != null) {
@@ -680,7 +688,7 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
 
     @Override
     public final void setRealized(final boolean realized) {
-        final RecursiveLock _lock = getLock();
+        final RecursiveLock _lock = getUpstreamLock();
         _lock.lock();
         try {
             final GLDrawable _drawable = drawable;