Version 1.5.2 - Added Windows support and Javadoc for all public methods.

peter-lawrey · peter-lawrey · commit 68b6673aeb38 · 2012-02-19T10:09:18.000Z
diff --git a/README b/README
@@ -4,6 +4,8 @@ https://www.ohloh.net/p/Java-Thread-Affinity
 
 [ Version History ]
 
+Version 1.5.2 - Added Windows support and Javadoc for all public methods.
+
 Version 1.5.1 - Add changes to support i386 and Intel i3
 https://github.com/peter-lawrey/Java-Thread-Affinity/issues/9
 https://github.com/peter-lawrey/Java-Thread-Affinity/issues/10
diff --git a/pom.xml b/pom.xml
@@ -22,7 +22,7 @@
 
     <groupId>vanilla.java</groupId>
     <artifactId>affinity</artifactId>
-    <version>1.5.1</version>
+    <version>1.5.2</version>
     <packaging>jar</packaging>
 
     <licenses>
diff --git a/src/main/java/vanilla/java/affinity/AffinityLock.java b/src/main/java/vanilla/java/affinity/AffinityLock.java
@@ -27,6 +27,8 @@
 import java.util.logging.Logger;
 
 /**
+ * This utility class support locking a thread to a single core, or reserving a whole core for a thread.
+ *
  * @author peter.lawrey
  */
 public class AffinityLock {
@@ -61,6 +63,14 @@ public class AffinityLock {
         }
     }
 
+    /**
+     * Set the CPU layout for this machine.  CPUs which are not mentioned will be ignored.
+     * <p/>
+     * Changing the layout will have no impact on thread which have already been assigned.
+     * It only affects subsequent assignments.
+     *
+     * @param cpuLayout for this application to use for this machine.
+     */
     public static void cpuLayout(CpuLayout cpuLayout) {
         synchronized (AffinityLock.class) {
             AffinityLock.cpuLayout = cpuLayout;
@@ -84,6 +94,9 @@ private static int coreForId(int id) {
         return cpuLayout.socketId(id) * cpuLayout.coresPerSocket() + cpuLayout.coreId(id);
     }
 
+    /**
+     * @return The current CpuLayout for the application.
+     */
     public static CpuLayout cpuLayout() {
         return cpuLayout;
     }
@@ -95,18 +108,46 @@ private static long getReservedAffinity0() {
         return Long.parseLong(reservedAffinity, 16);
     }
 
+    /**
+     * Assign any free cpu to this thread.
+     *
+     * @return A handle for the current AffinityLock.
+     */
     public static AffinityLock acquireLock() {
         return acquireLock(true);
     }
 
+    /**
+     * Assign any free core to this thread.
+     * <p/>
+     * In reality, only one cpu is assigned, the rest of the threads for that core are reserved so they are not used.
+     *
+     * @return A handle for the current AffinityLock.
+     */
     public static AffinityLock acquireCore() {
         return acquireCore(true);
     }
 
+    /**
+     * Assign a cpu which can be bound to the current thread or another thread.
+     * <p/>
+     * This can be used for defining your thread layout centrally and passing the handle via dependency injection.
+     *
+     * @param bind if true, bind the current thread, if false, reserve a cpu which can be bound later.
+     * @return A handle for an affinity lock.
+     */
     public static AffinityLock acquireLock(boolean bind) {
         return acquireLock(bind, -1, AffinityStrategies.ANY);
     }
 
+    /**
+     * Assign a core(and all its cpus) which can be bound to the current thread or another thread.
+     * <p/>
+     * This can be used for defining your thread layout centrally and passing the handle via dependency injection.
+     *
+     * @param bind if true, bind the current thread, if false, reserve a cpu which can be bound later.
+     * @return A handle for an affinity lock.
+     */
     public static AffinityLock acquireCore(boolean bind) {
         return acquireCore(bind, -1, AffinityStrategies.ANY);
     }
@@ -152,6 +193,9 @@ private static AffinityLock acquireCore(boolean bind, int cpuId, AffinityStrateg
     }
 
 
+    /**
+     * @return All the current locks as a String.
+     */
     public static String dumpLocks() {
         return dumpLocks0(LOCKS);
     }
@@ -193,10 +237,18 @@ private void assignCurrentThread(boolean bind, boolean wholeCore) {
             bind(wholeCore);
     }
 
+    /**
+     * Bind the current thread to this reserved lock.
+     */
     public void bind() {
         bind(false);
     }
 
+    /**
+     * Bind the current thread to this reserved lock.
+     *
+     * @param wholeCore if true, also reserve the whole core.
+     */
     public void bind(boolean wholeCore) {
         if (bound && assignedThread != null && assignedThread.isAlive())
             throw new IllegalStateException("cpu " + id + " already bound to " + assignedThread);
@@ -239,10 +291,19 @@ private boolean canReserve() {
         return true;
     }
 
+    /**
+     * Give another affinity lock relative to this one based on a list of strategies.
+     *
+     * @param strategies To dertemine if you want the same/different core/socket.
+     * @return A matching AffinityLock.
+     */
     public AffinityLock acquireLock(AffinityStrategy... strategies) {
         return acquireLock(false, id, strategies);
     }
 
+    /**
+     * Release the current AffinityLock which can be discarded.
+     */
     public void release() {
         Thread t = Thread.currentThread();
         synchronized (AffinityLock.class) {
@@ -262,4 +323,13 @@ public void release() {
         }
         AffinitySupport.setAffinity(BASE_AFFINITY);
     }
+
+    @Override
+    protected void finalize() throws Throwable {
+        if (reserved) {
+            LOGGER.warning("Affinity lock for " + assignedThread + " was discarded rather than release()d in a controlled manner.");
+            release();
+        }
+        super.finalize();
+    }
 }
diff --git a/src/main/java/vanilla/java/affinity/AffinityStrategies.java b/src/main/java/vanilla/java/affinity/AffinityStrategies.java
@@ -17,35 +17,56 @@
 package vanilla.java.affinity;
 
 /**
+ * Pre-defined strategies for determining which thread to pick next.
+ *
  * @author peter.lawrey
  */
 public enum AffinityStrategies implements AffinityStrategy {
+    /**
+     * Any free cpu.
+     */
     ANY {
         @Override
         public boolean matches(int cpuId, int cpuId2) {
             return true;
         }
-    }, SAME_CORE {
+    },
+    /**
+     * Must be a cpu on the same core.
+     */
+    SAME_CORE {
         @Override
         public boolean matches(int cpuId, int cpuId2) {
             CpuLayout cpuLayout = AffinityLock.cpuLayout();
             return cpuLayout.socketId(cpuId) == cpuLayout.socketId(cpuId2) &&
                     cpuLayout.coreId(cpuId) == cpuLayout.coreId(cpuId2);
         }
-    }, SAME_SOCKET {
+    },
+    /**
+     * Must be a cpu on the same socket/chip.
+     */
+    SAME_SOCKET {
         @Override
         public boolean matches(int cpuId, int cpuId2) {
             CpuLayout cpuLayout = AffinityLock.cpuLayout();
             return cpuLayout.socketId(cpuId) == cpuLayout.socketId(cpuId2);
         }
-    }, DIFFERENT_CORE {
+    },
+    /**
+     * Must be a cpu on any other core (or socket)
+     */
+    DIFFERENT_CORE {
         @Override
         public boolean matches(int cpuId, int cpuId2) {
             CpuLayout cpuLayout = AffinityLock.cpuLayout();
             return cpuLayout.socketId(cpuId) != cpuLayout.socketId(cpuId2) ||
                     cpuLayout.coreId(cpuId) != cpuLayout.coreId(cpuId2);
         }
-    }, DIFFERENT_SOCKET {
+    },
+    /**
+     * Must be a cpu on any other socket.
+     */
+    DIFFERENT_SOCKET {
         @Override
         public boolean matches(int cpuId, int cpuId2) {
             CpuLayout cpuLayout = AffinityLock.cpuLayout();
diff --git a/src/main/java/vanilla/java/affinity/AffinityStrategy.java b/src/main/java/vanilla/java/affinity/AffinityStrategy.java
@@ -17,6 +17,8 @@
 package vanilla.java.affinity;
 
 /**
+ * Allow you define a strategy for find the a cpu relative to another select cpu.
+ *
  * @author peter.lawrey
  */
 public interface AffinityStrategy {
diff --git a/src/main/java/vanilla/java/affinity/AffinitySupport.java b/src/main/java/vanilla/java/affinity/AffinitySupport.java
@@ -25,6 +25,8 @@
 import java.util.logging.Logger;
 
 /**
+ * Library to wrap low level JNI or JNA calls.  Can be called without needing to know the actual implementation used.
+ *
  * @author peter.lawrey
  */
 public enum AffinitySupport {
diff --git a/src/main/java/vanilla/java/affinity/AffinityThreadFactory.java b/src/main/java/vanilla/java/affinity/AffinityThreadFactory.java
@@ -19,6 +19,10 @@
 import java.util.concurrent.ThreadFactory;
 
 /**
+ * This is a ThreadFactory which assigns threads based the strategies provided.
+ * <p/>
+ * If no strategies are provided AffinityStrategies.ANY is used.
+ *
  * @author peter.lawrey
  */
 public class AffinityThreadFactory implements ThreadFactory {
@@ -35,7 +39,7 @@ public AffinityThreadFactory(String name, AffinityStrategy... strategies) {
     public AffinityThreadFactory(String name, boolean daemon, AffinityStrategy... strategies) {
         this.name = name;
         this.daemon = daemon;
-        this.strategies = strategies;
+        this.strategies = strategies.length == 0 ? new AffinityStrategy[]{AffinityStrategies.ANY} : strategies;
     }
 
     @Override
