javadoc improvements in concurrent package.

5 files changed, 32 insertions, 5 deletions

diff --git a/src/com/jogamp/opencl/util/concurrent/CLAbstractExecutorService.java b/src/com/jogamp/opencl/util/concurrent/CLAbstractExecutorService.java
index 843e08e0..b94aa85f 100644
--- a/src/com/jogamp/opencl/util/concurrent/CLAbstractExecutorService.java
+++ b/src/com/jogamp/opencl/util/concurrent/CLAbstractExecutorService.java
@@ -30,7 +30,10 @@
 package com.jogamp.opencl.util.concurrent;
 
 import com.jogamp.opencl.CLCommandQueue;
+import com.jogamp.opencl.CLContext;
+import com.jogamp.opencl.CLDevice;
 import com.jogamp.opencl.CLResource;
+import com.jogamp.opencl.CLSubDevice;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -44,7 +47,19 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
 /**
- * Common superclass for Executor services supporting OpenCL driven tasks.
+ * A {@link ExecutorService} specialized for OpenCL driven tasks.
+ * <p>
+ * Implementations will usually use one dedicated thread for every {@link CLCommandQueue} in the pool.
+ * Every queue will usually work on a different {@link CLDevice}, which may or may not be in the same {@link CLContext}.
+ * </p>
+ * <p>
+ * For optimal performance it can be better to not use the CPU device the host application (and the OpenCL driver)
+ * is running on in the executor. Another option is to split the CPU into {@link CLSubDevice}s to control the used computing
+ * units of the device.
+ * </p>
+ * <p>
+ * A CLExecutorService must be {@link #release()}d to free up OpenCL resources if no longer needed.
+ * </p>
  * @author Michael Bien
  */
 public abstract class CLAbstractExecutorService implements CLResource {
diff --git a/src/com/jogamp/opencl/util/concurrent/CLCommandQueuePool.java b/src/com/jogamp/opencl/util/concurrent/CLCommandQueuePool.java
index f6fadd66..d9025881 100644
--- a/src/com/jogamp/opencl/util/concurrent/CLCommandQueuePool.java
+++ b/src/com/jogamp/opencl/util/concurrent/CLCommandQueuePool.java
@@ -49,9 +49,11 @@ import java.util.concurrent.TimeUnit;
 
 /**
  * A multithreaded, fixed size pool of OpenCL command queues.
+ * <p>
  * CLCommandQueuePool serves as a multiplexer distributing tasks over N queues usually connected to N devices.
  * The usage of this pool is similar to {@link ExecutorService} but it uses {@link CLTask}s
  * instead of {@link Callable}s and provides a per-queue context for resource sharing across all tasks of one queue.
+ * </p>
  * @author Michael Bien
  */
 public class CLCommandQueuePool extends CLAbstractExecutorService {
diff --git a/src/com/jogamp/opencl/util/concurrent/CLForkJoinPool.java b/src/com/jogamp/opencl/util/concurrent/CLForkJoinPool.java
index bf253442..93c1dbc4 100644
--- a/src/com/jogamp/opencl/util/concurrent/CLForkJoinPool.java
+++ b/src/com/jogamp/opencl/util/concurrent/CLForkJoinPool.java
@@ -43,7 +43,11 @@ import java.util.concurrent.ForkJoinWorkerThread;
 import java.util.concurrent.Future;
 
 /**
- * JOCL implementation of the {@link ForkJoinPool}.
+ * A multithreaded, fixed size pool of OpenCL command queues supporting fork-join tasks.
+ * <p>
+ * The usage is similar to {@link ForkJoinPool} but uses {@link CLRecursiveTask}s.
+ * </p>
+ * @see CLRecursiveTask
  * @author Michael Bien
  */
 public class CLForkJoinPool extends CLAbstractExecutorService {
@@ -101,6 +105,7 @@ public class CLForkJoinPool extends CLAbstractExecutorService {
     /**
      * Returns an estimate of the total number of tasks stolen from
      * one thread's work queue by another.
+     * @see ForkJoinPool#getStealCount()
      */
     public long getStealCount() {
         return getExcecutor().getStealCount();
@@ -110,6 +115,7 @@ public class CLForkJoinPool extends CLAbstractExecutorService {
      * Returns an estimate of the number of tasks submitted to this
      * pool that have not yet begun executing. This method may take
      * time proportional to the number of submissions.
+     * @see ForkJoinPool#getQueuedSubmissionCount()
      */
     public int getQueuedSubmissionCount() {
         return getExcecutor().getQueuedSubmissionCount();
@@ -122,6 +128,7 @@ public class CLForkJoinPool extends CLAbstractExecutorService {
      * an approximation, obtained by iterating across all threads in
      * the pool. This method may be useful for tuning task
      * granularities.
+     * @see ForkJoinPool#getQueuedTaskCount()
      */
     public long getQueuedTaskCount() {
         return getExcecutor().getQueuedTaskCount();
@@ -130,6 +137,7 @@ public class CLForkJoinPool extends CLAbstractExecutorService {
     /**
      * Returns {@code true} if there are any tasks submitted to this
      * pool that have not yet begun executing.
+     * @see ForkJoinPool#hasQueuedSubmissions()
      */
     public boolean hasQueuedSubmissions() {
         return getExcecutor().hasQueuedSubmissions();
@@ -143,6 +151,7 @@ public class CLForkJoinPool extends CLAbstractExecutorService {
      * conservative; it might not return {@code true} immediately upon
      * idleness of all threads, but will eventually become true if
      * threads remain inactive.
+     * @see ForkJoinPool#isQuiescent()
      */
     public boolean isQuiescent() {
         return getExcecutor().isQuiescent();
diff --git a/src/com/jogamp/opencl/util/concurrent/CLRecursiveTask.java b/src/com/jogamp/opencl/util/concurrent/CLRecursiveTask.java
index 216a527e..14dd4494 100644
--- a/src/com/jogamp/opencl/util/concurrent/CLRecursiveTask.java
+++ b/src/com/jogamp/opencl/util/concurrent/CLRecursiveTask.java
@@ -35,6 +35,7 @@ import java.util.concurrent.RecursiveTask;
 
 /**
  * A recursive decomposable task executed on a {@link CLCommandQueue}.
+ * The two main operations are {@link #fork()} for decomposing and {@link #join()} to wait for a forked task.
  * @see RecursiveTask
  * @author Michael Bien
  */
diff --git a/src/com/jogamp/opencl/util/concurrent/CLTaskCompletionService.java b/src/com/jogamp/opencl/util/concurrent/CLTaskCompletionService.java
index 815ffc8b..a6d5f794 100644
--- a/src/com/jogamp/opencl/util/concurrent/CLTaskCompletionService.java
+++ b/src/com/jogamp/opencl/util/concurrent/CLTaskCompletionService.java
@@ -36,7 +36,7 @@ import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
 
 /**
- * A {@link CompletionService} for {@link CLTask}s executed in a {@link CLCommandQueuePool}.
+ * A {@link CompletionService} for {@link CLTask}s executed in a {@link CLAbstractExecutorService}.
  * It simplifies asynchronous execution of tasks with the same result type in a potentially shared pool.
  * @see CompletionService
  * @author Michael Bien
@@ -47,7 +47,7 @@ public class CLTaskCompletionService<R> {
     private final CLAbstractExecutorService executor;
 
     /**
-     * Creates an CLTaskCompletionService using the supplied pool for base
+     * Creates an CLTaskCompletionService using the supplied executor for base
      * task execution and a LinkedBlockingQueue with the capacity of {@link Integer#MAX_VALUE}
      * as a completion queue.
      */
@@ -57,7 +57,7 @@ public class CLTaskCompletionService<R> {
     }
 
     /**
-     * Creates an CLTaskCompletionService using the supplied pool for base
+     * Creates an CLTaskCompletionService using the supplied executor for base
      * task execution the supplied queue as its completion queue.
      */
     public CLTaskCompletionService(CLAbstractExecutorService pool, BlockingQueue<Future<R>> queue) {