AudioSink: Refine context locking where supported, have a more usable universal API interface

3 files changed, 33 insertions, 12 deletions

diff --git a/src/java/com/jogamp/common/av/AudioSink.java b/src/java/com/jogamp/common/av/AudioSink.java
index b4738b3..9c31244 100644
--- a/src/java/com/jogamp/common/av/AudioSink.java
+++ b/src/java/com/jogamp/common/av/AudioSink.java
@@ -123,16 +123,37 @@ public interface AudioSink {
     }
 
     /**
-     * Exclusively locks this instance for the calling thread, if implementation utilizes locking.
-     * @see #unlockExclusive()
+     * Makes the audio context current on the calling thread, if implementation utilizes context locking.
+     * <p>
+     * If implementation doesn't utilizes context locking, method always returns true.
+     * </p>
+     * <p>
+     * Recursive call to {@link #makeCurrent()} and hence {@link #release()} are supported.
+     * </p>
+     * <p>
+     * At any point in time one context can only be current by one thread,
+     * and one thread can only have one context current.
+     * </p>
+     * @param throwException if true, throws ALException if context is null, current thread holds another context or failed to natively make current
+     * @return true if current thread holds no other context and context successfully made current, otherwise false
+     * @see #release()
      */
-    public void lockExclusive();
+    public boolean makeCurrent(final boolean throwException);
 
     /**
-     * Releases the exclusive lock for the calling thread, if implementation utilizes locking.
-     * @see #lockExclusive()
+     * Releases control of this audio context from the current thread, if implementation utilizes context locking.
+     * <p>
+     * If implementation doesn't utilizes context locking, method always returns true.
+     * </p>
+     * <p>
+     * Recursive call to {@link #makeCurrent()} and hence {@link #release()} are supported.
+     * </p>
+     * @param throwException if true, throws ALException if context has not been previously made current on current thread
+     *                       or native release failed.
+     * @return true if context has previously been made current on the current thread and successfully released, otherwise false
+     * @see #makeCurrent()
      */
-    public void unlockExclusive();
+    public boolean release(final boolean throwException);
 
     /**
      * Returns the <code>available state</code> of this instance.
diff --git a/src/java/jogamp/common/av/JavaSoundAudioSink.java b/src/java/jogamp/common/av/JavaSoundAudioSink.java
index 7cd4310..d3ddda9 100644
--- a/src/java/jogamp/common/av/JavaSoundAudioSink.java
+++ b/src/java/jogamp/common/av/JavaSoundAudioSink.java
@@ -44,7 +44,7 @@ import com.jogamp.common.av.AudioSink;
  * audio capabilities
  * </p>
  */
-public class JavaSoundAudioSink implements AudioSink {
+public final class JavaSoundAudioSink implements AudioSink {
 
     // Chunk of audio processed at one time
     public static final int BUFFER_SIZE = 1000;
@@ -85,10 +85,10 @@ public class JavaSoundAudioSink implements AudioSink {
     }
 
     @Override
-    public final void lockExclusive() { }
+    public final boolean makeCurrent(final boolean throwException) { return true; }
 
     @Override
-    public final void unlockExclusive() { }
+    public final boolean release(final boolean throwException) { return true; }
 
     @Override
     public String toString() {
diff --git a/src/java/jogamp/common/av/NullAudioSink.java b/src/java/jogamp/common/av/NullAudioSink.java
index ca5e2f4..19b0acb 100644
--- a/src/java/jogamp/common/av/NullAudioSink.java
+++ b/src/java/jogamp/common/av/NullAudioSink.java
@@ -32,7 +32,7 @@ import java.nio.ByteBuffer;
 import com.jogamp.common.av.AudioFormat;
 import com.jogamp.common.av.AudioSink;
 
-public class NullAudioSink implements AudioSink {
+public final class NullAudioSink implements AudioSink {
 
     private volatile float playSpeed = 1.0f;
     private volatile boolean playRequested = false;
@@ -48,10 +48,10 @@ public class NullAudioSink implements AudioSink {
     }
 
     @Override
-    public final void lockExclusive() { }
+    public final boolean makeCurrent(final boolean throwException) { return true; }
 
     @Override
-    public final void unlockExclusive() { }
+    public final boolean release(final boolean throwException) { return true; }
 
     @Override
     public boolean isAvailable() {