diff options
Diffstat (limited to 'src/com/jogamp/opencl/util')
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) { |