SingletonInstance Enhancements / Minor Lock/LockExt API Change (isLocked moved up)

We learned that FileChannel.lock() is not reliable on at least GNU/Linux + Sun's JVM implementation,
hence we need a ServerSocket implementation.

Since this code may be useful to others, it has been promoted to GlueGen.

- Abstract SingletonInstance
- Implement Lock interface
- SingletonInstance Spezialisation: FileLock and ServerSocket

Minor API Change: LockExt.isLocked() -> Lock.isLocked()

3 files changed, 75 insertions, 109 deletions

diff --git a/src/java/com/jogamp/common/util/locks/Lock.java b/src/java/com/jogamp/common/util/locks/Lock.java
index 4ea8bf4..ad379ef 100644
--- a/src/java/com/jogamp/common/util/locks/Lock.java
+++ b/src/java/com/jogamp/common/util/locks/Lock.java
@@ -74,4 +74,6 @@ public interface Lock {
      * @throws RuntimeException in case the lock is not acquired by this thread.
      */
     void unlock() throws RuntimeException;
+    
+    boolean isLocked();
 }
diff --git a/src/java/com/jogamp/common/util/locks/LockExt.java b/src/java/com/jogamp/common/util/locks/LockExt.java
index 42a01c6..860c03a 100644
--- a/src/java/com/jogamp/common/util/locks/LockExt.java
+++ b/src/java/com/jogamp/common/util/locks/LockExt.java
@@ -38,8 +38,6 @@ public interface LockExt extends Lock {
      */
     Thread getOwner();
 
-    boolean isLocked();
-
     boolean isLockedByOtherThread();
 
     boolean isOwner();
diff --git a/src/java/com/jogamp/common/util/locks/SingletonInstance.java b/src/java/com/jogamp/common/util/locks/SingletonInstance.java
index f69641f..c085371 100644
--- a/src/java/com/jogamp/common/util/locks/SingletonInstance.java
+++ b/src/java/com/jogamp/common/util/locks/SingletonInstance.java
@@ -1,16 +1,16 @@
 /**
- * Copyright 2010 JogAmp Community. All rights reserved.
+ * Copyright 2011 JogAmp Community. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, are
  * permitted provided that the following conditions are met:
- * 
+ *
  *    1. Redistributions of source code must retain the above copyright notice, this list of
  *       conditions and the following disclaimer.
- * 
+ *
  *    2. Redistributions in binary form must reproduce the above copyright notice, this list
  *       of conditions and the following disclaimer in the documentation and/or other materials
  *       provided with the distribution.
- * 
+ *
  * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
@@ -20,145 +20,111 @@
  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- * 
+ *
  * The views and conclusions contained in the software and documentation are those of the
  * authors and should not be interpreted as representing official policies, either expressed
  * or implied, of JogAmp Community.
  */
- 
+
 package com.jogamp.common.util.locks;
 
 import java.io.File;
-import java.io.IOException;
-import java.io.RandomAccessFile;
-import java.nio.channels.FileLock;
-import java.util.Date;
 
-public class SingletonInstance {
+import jogamp.common.util.locks.SingletonInstanceFileLock;
+import jogamp.common.util.locks.SingletonInstanceServerSocket;
 
-    static final boolean DEBUG = true;
-    static final String temp_file_path;
+public abstract class SingletonInstance implements Lock {
 
-    static {
-        String s = null;
-        try {
-            File tmpFile = File.createTempFile("TEST", "tst");
-            String absTmpFile = tmpFile.getCanonicalPath();
-            tmpFile.delete();
-            s = absTmpFile.substring(0, absTmpFile.lastIndexOf(File.separator));
-        } catch (IOException ex) {
-            ex.printStackTrace();
-        }
-        temp_file_path = s;
-    }
+    protected static final boolean DEBUG = true;
 
-    public static String getCanonicalTempPath() {
-        return temp_file_path;
+    public static SingletonInstance createFileLock(long poll_ms, String lockFileBasename) {
+        return new SingletonInstanceFileLock(poll_ms, lockFileBasename);
     }
 
-    public static String getCanonicalTempLockFilePath(String basename) {
-        return getCanonicalTempPath() + File.separator + basename;
+    public static SingletonInstance createFileLock(long poll_ms, File lockFile) {
+        return new SingletonInstanceFileLock(poll_ms, lockFile);
     }
-
-    public SingletonInstance(String name, String lockFileBasename) {
-        this.name = name;
-        this.file = new File ( getCanonicalTempLockFilePath ( lockFileBasename ) );
-        setupFileCleanup();
-    }
-
-    public SingletonInstance(String name, File lockFile) {
-        this.name = name;
-        this.file = lockFile ;
-        setupFileCleanup();
+    
+    /**
+     * A user shall use <b>ephemeral ports</b>:
+     * <ul>
+     *  <li>IANA suggests 49152 to 65535 as "dynamic and/or private ports".</li>
+     *  <li>Many GNU/Linux kernels use 32768 to 61000.</li>
+     *  <li>FreeBSD >= 4.6 uses the IANA port range.</li>
+     *  <li>FreeBSD < 4.6 and BSD use ports 1024 through 4999.</li>
+     *  <li>Microsoft Windows operating systems through Server 2003 use the range 1025 to 5000</li>
+     *  <li>Windows Vista, Windows 7, and Server 2008 use the IANA range.</li>
+     * </ul> 
+     * @param pollPeriod
+     * @param portNumber to be used for this single instance server socket. 
+     */
+    public static SingletonInstance createServerSocket(long poll_ms, int portNumber) {
+        return new SingletonInstanceServerSocket(poll_ms, portNumber);
     }
-
-    public String getName() { return name; }
     
-    void setupFileCleanup() {
-        file.deleteOnExit();
-        Runtime.getRuntime().addShutdownHook(new Thread() {
-            public void run() {
-                unlock();
-            }
-        });        
+    protected SingletonInstance(long poll_ms) {
+        this.poll_ms = Math.max(10, poll_ms);
     }
-
-    public synchronized void lock(long timeout_ms, long poll_ms) {
-        long i=0;
+    
+    public final long getPollPeriod() { return poll_ms; }
+    public abstract String getName();
+    public final String toString() { return getName(); }
+    
+    public synchronized void lock() throws RuntimeException {
         try {
             do {
-                if(tryLock()) {
+                if(tryLock(TIMEOUT)) {
                     return;
                 }
-                if(DEBUG && 0==i) {
-                    System.err.println("SLOCK "+System.currentTimeMillis()+" ??? "+name+" - Wait for lock " + file);
-                }
-                i++;
-                Thread.sleep(poll_ms);
-            } while ( i < timeout_ms / poll_ms ) ;
-        } catch ( InterruptedException ie ) {
+            } while ( true ) ;
+        } catch ( RuntimeException ie ) {
             throw new  RuntimeException(ie);
         }
-        throw new RuntimeException("SLOCK "+System.currentTimeMillis()+" EEE "+name+" - couldn't get lock within "+timeout_ms+"ms");
     }
 
-    public synchronized boolean tryLock() {
-        try {
-            randomAccessFile = new RandomAccessFile(file, "rw");
-            fileLock = randomAccessFile.getChannel().tryLock();
-
-            if (fileLock != null) {
-                locked = true;
-                if(DEBUG) {
-                    System.err.println("SLOCK "+System.currentTimeMillis()+" +++ "+name+" - Locked " + file);
-                }
-                return true;
-            }
-        } catch (Exception e) {
-            System.err.println("SLOCK "+System.currentTimeMillis()+" EEE "+name+" - Unable to create and/or lock file: " + file);
-            e.printStackTrace();
+    public synchronized boolean tryLock(long maxwait) throws RuntimeException {
+        if(locked) {
+            return true;
         }
-        return false;
-    }
-
-    public synchronized boolean unlock() {
+        int i=0;
         try {
-            if(null != fileLock) {
+            do {
+                locked = tryLockImpl();
                 if(locked) {
-                    fileLock.release();
                     if(DEBUG) {
-                        System.err.println("SLOCK "+System.currentTimeMillis()+" --- "+name+" - Unlocked " + file);
-                    }        
+                        System.err.println("SLOCK "+System.currentTimeMillis()+" +++ "+getName()+" - Locked ");
+                    }            
+                    return true;
                 }
-                fileLock = null;
-            }
-            if(null != randomAccessFile) {
-                randomAccessFile.close();
-                randomAccessFile = null;
-            }
-            if(null != file) {
-                file.delete();
-                file = null;
-            }
-            return true;
-        } catch (Exception e) {
-            System.err.println("SLOCK "+System.currentTimeMillis()+" EEE "+name+" - Unable to remove lock file: " + file);
-            e.printStackTrace();
-        } finally {
-            fileLock = null;
-            randomAccessFile = null;
-            locked = false;
+                if(DEBUG && 0==i) {
+                    System.err.println("SLOCK "+System.currentTimeMillis()+" ??? "+getName()+" - Wait for lock");
+                }
+                Thread.sleep(poll_ms);
+                maxwait -= poll_ms;
+                i++;
+            } while ( 0 < maxwait ) ;
+        } catch ( InterruptedException ie ) {
+            throw new RuntimeException("SLOCK "+System.currentTimeMillis()+" EEE "+getName()+" - couldn't get lock", ie);            
         }
         return false;
+    }    
+    protected abstract boolean tryLockImpl();
+    
+    public void unlock() throws RuntimeException {
+        if(locked) {
+            locked = !unlockImpl();
+            if(DEBUG) {
+                System.err.println("SLOCK "+System.currentTimeMillis()+" --- "+getName()+" - Unlock " 
+                                   + ( locked ? "failed" : "ok" ) );
+            }
+        }
     }
+    protected abstract boolean unlockImpl();
 
     public synchronized boolean isLocked() {
         return locked;
     }
 
-    String name;
-    File file = null;
-    RandomAccessFile randomAccessFile = null;
-    FileLock fileLock = null;
-    boolean locked = false;
+    private final long poll_ms;
+    private boolean locked = false;
 }