Unify thread utilities

SpiNNaker-nmpiexec/pom.xml

@@ -48,6 +48,10 @@
 			<groupId>${project.groupId}</groupId>
 			<artifactId>SpiNNaker-nmpimodel</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>SpiNNaker-utils</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>org.ini4j</groupId>
 			<artifactId>ini4j</artifactId>

SpiNNaker-nmpiexec/src/main/java/uk/ac/manchester/spinnaker/nmpiexec/jobprocess/PyNNJobProcess.java

@@ -60,7 +60,7 @@
 import uk.ac.manchester.spinnaker.nmpi.model.job.Status;
 import uk.ac.manchester.spinnaker.nmpi.model.job.pynn.PyNNJobParameters;
 import uk.ac.manchester.spinnaker.nmpi.model.machine.SpinnakerMachine;
-import uk.ac.manchester.spinnaker.nmpiexec.utils.ThreadUtils;
+import uk.ac.manchester.spinnaker.utils.ThreadUtils;
 
 /**
  * A process for running PyNN jobs.

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/jobmanager/DockerExecutorFactory.java

@@ -18,7 +18,7 @@
 import static java.util.Objects.requireNonNull;
 import static java.util.UUID.randomUUID;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 import static uk.ac.manchester.spinnaker.nmpi.model.job.JobManagerInterface.JOB_PROCESS_MANAGER;
 
 import java.io.IOException;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/jobmanager/JobManager.java

@@ -34,7 +34,7 @@
 import static org.apache.commons.io.FileUtils.forceMkdirParent;
 import static org.apache.commons.io.FileUtils.listFiles;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 
 import java.io.File;
 import java.io.IOException;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/jobmanager/LocalJobExecuterFactory.java

@@ -25,7 +25,7 @@
 import static org.apache.commons.io.IOUtils.closeQuietly;
 import static org.apache.commons.io.IOUtils.copy;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 import static uk.ac.manchester.spinnaker.nmpi.model.job.JobManagerInterface.JOB_PROCESS_MANAGER;
 
 import java.io.BufferedReader;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/jobmanager/OutputManagerImpl.java

@@ -29,7 +29,7 @@
 import static javax.ws.rs.core.Response.Status.BAD_REQUEST;
 import static javax.ws.rs.core.Response.Status.NOT_FOUND;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 
 import java.io.File;
 import java.io.FileInputStream;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/jobmanager/XenVMExecuterFactory.java

@@ -26,8 +26,8 @@
 import static java.util.Objects.requireNonNull;
 import static java.util.UUID.randomUUID;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.sleep;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.sleep;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 import static uk.ac.manchester.spinnaker.nmpi.model.job.JobManagerInterface.JOB_PROCESS_MANAGER;
 
 import java.io.IOException;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/machinemanager/FixedMachineManagerImpl.java

@@ -16,7 +16,7 @@
 package uk.ac.manchester.spinnaker.nmpi.machinemanager;
 
 import static java.util.Objects.nonNull;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 
 import java.util.ArrayList;
 import java.util.HashSet;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/machinemanager/SpallocMachineManagerImpl.java

@@ -26,8 +26,8 @@
 import static org.apache.commons.io.IOUtils.buffer;
 import static org.apache.commons.io.IOUtils.closeQuietly;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.sleep;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.waitfor;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.sleep;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.waitfor;
 import static uk.ac.manchester.spinnaker.nmpi.machinemanager.responses.JobState.DESTROYED;
 import static uk.ac.manchester.spinnaker.nmpi.machinemanager.responses.JobState.READY;
 

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/nmpi/NMPIQueueManagerCompat.java

@@ -18,7 +18,7 @@
 import static java.util.Objects.nonNull;
 import static org.joda.time.DateTimeZone.UTC;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.sleep;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.sleep;
 
 import java.io.IOException;
 import java.io.PrintWriter;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/nmpi/NMPIQueueManagerV3.java

@@ -18,7 +18,7 @@
 import static java.util.Objects.nonNull;
 import static org.joda.time.DateTimeZone.UTC;
 import static org.slf4j.LoggerFactory.getLogger;
-import static uk.ac.manchester.spinnaker.nmpi.ThreadUtils.sleep;
+import static uk.ac.manchester.spinnaker.utils.ThreadUtils.sleep;
 
 import java.io.IOException;
 import java.io.PrintWriter;

SpiNNaker-nmpiserv/src/main/java/uk/ac/manchester/spinnaker/nmpi/package-info.java

@@ -15,5 +15,28 @@
  */
 /**
  * The NMPI service classes.
+ * <p>
+ * The actual key service APIs are:
+ * <ul>
+ * <li>{@link NMPIQueueManager} &mdash; Handles the queue of {@linkplain Job
+ * NMPI jobs}.
+ * <li>{@link JobExecuter} &mdash; Handles the running of a single NMPI job.
+ * Note that job executer implementations ask the queue manager for the job that
+ * they should run.
+ * <li>{@link JobExecuterFactory} &mdash; Creates job executers.
+ * <li>{@link MachineManager} &mdash; Handles the resources on which NMPI jobs
+ * run.
+ * </ul>
  */
+@UsedInJavadocOnly({
+	Job.class, JobExecuter.class, JobExecuterFactory.class,
+	MachineManager.class, NMPIQueueManager.class
+})
 package uk.ac.manchester.spinnaker.nmpi;
+
+import uk.ac.manchester.spinnaker.nmpi.jobmanager.JobExecuter;
+import uk.ac.manchester.spinnaker.nmpi.jobmanager.JobExecuterFactory;
+import uk.ac.manchester.spinnaker.nmpi.machinemanager.MachineManager;
+import uk.ac.manchester.spinnaker.nmpi.model.job.nmpi.Job;
+import uk.ac.manchester.spinnaker.nmpi.nmpi.NMPIQueueManager;
+import uk.ac.manchester.spinnaker.utils.UsedInJavadocOnly;

SpiNNaker-utils/src/main/java/uk/ac/manchester/spinnaker/utils/ThreadUtils.java

@@ -25,6 +25,10 @@
  * Utilities for working with threads.
  */
 public abstract class ThreadUtils {
+	/** Avoid creation. */
+	private ThreadUtils() {
+	}
+
 	/**
 	 * Produce a dump of what all threads are doing. Useful for debugging as it
 	 * means you can get a dump of threads programmatically at the time when the
@@ -36,4 +40,55 @@ public static String threadDump() {
 		return stream(getThreadMXBean().dumpAllThreads(true, true))
 				.map(ThreadInfo::toString).collect(joining());
 	}
+
+	/**
+	 * Recommended way of doing "quiet" sleeps.
+	 *
+	 * @param delay
+	 *            How long to sleep for, in milliseconds.
+	 * @see <a href="https://stackoverflow.com/q/1087475/301832">Stack Overflow
+	 *      Question: When does Java's Thread.sleep throw
+	 *      InterruptedException?</a>
+	 */
+	public static void sleep(final long delay) {
+		try {
+			Thread.sleep(delay);
+		} catch (final InterruptedException e) {
+			Thread.currentThread().interrupt();
+		}
+	}
+
+	/**
+	 * Wait for the given object.
+	 *
+	 * @param obj
+	 *            The object to wait for
+	 * @return True if the wait was interrupted, false otherwise
+	 */
+	public static boolean waitfor(final Object obj) {
+		try {
+			obj.wait();
+			return false;
+		} catch (final InterruptedException e) {
+			return true;
+		}
+	}
+
+	/**
+	 * Wait for the given object.
+	 *
+	 * @param obj
+	 *            The object to wait for
+	 * @param timeout
+	 *            The maximum time to wait, in milliseconds
+	 * @return True if the wait was interrupted, false otherwise
+	 */
+	public static boolean waitfor(final Object obj, final long timeout) {
+		try {
+			obj.wait(timeout);
+			return false;
+		} catch (final InterruptedException e) {
+			return true;
+		}
+	}
 }

SpiNNaker-utils/src/main/java/uk/ac/manchester/spinnaker/utils/UsedInJavadocOnly.java

@@ -18,6 +18,7 @@
 import static java.lang.annotation.ElementType.CONSTRUCTOR;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.SOURCE;
 
@@ -32,7 +33,7 @@
  * @author Donal Fellows
  */
 @Retention(SOURCE)
-@Target({ TYPE, METHOD, CONSTRUCTOR, FIELD })
+@Target({ TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE })
 public @interface UsedInJavadocOnly {
 	/**
 	 * Class or classes just used by the annotated thing in Javadoc generation.