javolution.context

Class ComputeContext

java.lang.Object

javolution.context.AbstractContext

javolution.context.ComputeContext

public abstract class ComputeContext
extends AbstractContext

A context for executing and chaining calculations in parallel on computing devices such as CPUs/GPUs. ComputeContext keeps its buffers in device memory unless a buffer is exported (to the heap). Device operations are asynchronous and performed in parallel whenever possible (based on inputs parameters dependencies). Synchronization with host (java) is performed when buffers are read/exported (typically to retrieve the calculations results).

 FloatVector result;
 ComputeContext ctx = ComputeContext.enter();
 try {
     FloatVector x = new FloatVector(1.0, 2.0, 3.0);
     FloatVector y = new FloatVector(1.0, 2.0, 3.0);
     FloatVector z = new FloatVector(1.0, 2.0, 3.0);
     
     FloatVector sumXYZ = x.plus(y).plus(z);        // Both sum and product calculations   
     FloatVector productXYZ = x.times(y).times(z);  // are performed in parallel.
     
     result = sumXYZ.plus(productXYZ);
     result.export(); // Moves result to global memory (heap).
 } finally { 
     ctx.exit(); // Release all local resources (e.g. device buffers). 
 }
 
 class FloatVector implements ComputeContext.Local { 
     private final ComputeContext.Buffer buffer;
     public FloatVector(double... elements) { 
         buffer = ComputeContext.newBuffer(DoubleBuffer.wrap(elements));
     }
     private FloatVector(int length) {
         buffer = ComputeContext.newBuffer(length * 8L); // Size in bytes.
     }
     FloatVector plus(FloatVector that) {
         if (this.length() != that.length()) throw new DimensionMismatch();
         FloatVector result  = new FloatVector(this.length()); 
         ComputeContext.Kernel sum = ComputeContext.newKernel(VectorFP64.class, "sum");   
         sum.setArguments(this.buffer.readOnly(), that.buffer.readOnly(), result.buffer);
         sum.setGlobalWorkSize(length()); // Number of work-items.
         sum.execute(); // Executes in parallel with others kernels. 
         return result; 
     }
     @Override
     public void export() { // Moves to global memory. 
         buffer.export();
     }
     public int length() { return (int) buffer.getByteCount() / 8; }
 }
 class VectorFP64 implements Program { // All programs published as OSGi services are 
                                       // automatically loaded/compiled by Javolution.
     public String toOpenCL() {
         return  "__kernel void sum(__global const double *a, __global const double *b, __global double *c) {" +
                 "    int gid = get_global_id(0);" +
                 "    c[gid] = a[gid] + b[gid];" + "}";
 }
 

By default, the best GPU device with support for double precision floating-point is selected. If your GPU does not have such support, the CPU device is chosen. For complex data structures shared between OpenCL and Java, Struct is recommended.

Thread-Safety: As for any context, compute contexts are inherently thread-safe (each thread entering a context has its own context instance); but nesting a ConcurrentContext within a ComputeContext (already intrinsically parallel) is ill-advised (the reverse is fine though).

Version:

6.1, December 22, 2013

Author:

Jean-Marie Dautelle

See Also:

Wikipedia: OpenCL

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ComputeContext.Buffer A high speed memory buffer which can be created on a device.
static interface	ComputeContext.Kernel A function which can be executed on a device.
static interface	ComputeContext.Local An object which may be partially allocated in local device memory.
static interface	ComputeContext.Program A program which can be loaded/compiled on a device.

Field Summary

Fields

Modifier and Type	Field and Description
static Configurable<Boolean>	DOUBLE_PRECISION_REQUIRED Indicates if support for double precision floating-point is required (default true).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ComputeContext() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract ComputeContext.Buffer	createBuffer(Buffer init) Creates a buffer having the specified initial data in this context.
protected abstract ComputeContext.Buffer	createBuffer(long byteCount) Creates a memory buffer having the specified capacity in this context.
protected abstract ComputeContext.Kernel	createKernel(Class<? extends ComputeContext.Program> program, String kernelName) Creates the kernel from the specified program having the specified name in this context.
static ComputeContext	enter() Enters the scope of a local computing context; all the resources (kernels, buffers) allocated while in this context scope are released upon exit.
static void	load(ComputeContext.Program program) Explicitly loads the specified program.
protected abstract void	loadAndBuild(ComputeContext.Program program) Loads and builds the specified program.
static ComputeContext.Buffer	newBuffer(Buffer init) Returns a memory buffer having the specified initial data.
static ComputeContext.Buffer	newBuffer(long byteCount) Returns a memory buffer having the specified capacity.
static ComputeContext.Kernel	newKernel(Class<? extends ComputeContext.Program> program, String kernelName) Returns a kernel from the current context having the specified name.
static void	unload(ComputeContext.Program program) Explicitly unloads the specified program.
protected abstract void	unloadAndFree(ComputeContext.Program program) Unloads and free the specified program.

Methods inherited from class javolution.context.AbstractContext

current, current, enter, enterInner, exit, getOuter, inherit, inner

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DOUBLE_PRECISION_REQUIRED

public static final Configurable<Boolean> DOUBLE_PRECISION_REQUIRED

Indicates if support for double precision floating-point is required (default true). Running with the option -Djavolution.context.ComputeContext#DOUBLE_PRECISION_REQUIRED=false disables the requirement to select a device supporting double precision.

Constructor Detail

ComputeContext

protected ComputeContext()

Default constructor.

Method Detail

enter

public static ComputeContext enter()

Enters the scope of a local computing context; all the resources (kernels, buffers) allocated while in this context scope are released upon exit.

load

public static void load(ComputeContext.Program program)

Explicitly loads the specified program.

newBuffer

public static ComputeContext.Buffer newBuffer(Buffer init)

Returns a memory buffer having the specified initial data. Once created the buffer returned as no further link to the specified NIO buffer.

newBuffer

public static ComputeContext.Buffer newBuffer(long byteCount)

Returns a memory buffer having the specified capacity.

newKernel

public static ComputeContext.Kernel newKernel(Class<? extends ComputeContext.Program> program,
                              String kernelName)

Returns a kernel from the current context having the specified name. If the program has not yet been loaded, a new instance is allocated using the class default constructor and then loaded.

unload

public static void unload(ComputeContext.Program program)

Explicitly unloads the specified program.

createBuffer

protected abstract ComputeContext.Buffer createBuffer(Buffer init)

Creates a buffer having the specified initial data in this context.

createBuffer

protected abstract ComputeContext.Buffer createBuffer(long byteCount)

Creates a memory buffer having the specified capacity in this context.

createKernel

protected abstract ComputeContext.Kernel createKernel(Class<? extends ComputeContext.Program> program,
                                 String kernelName)

Creates the kernel from the specified program having the specified name in this context. If the specified program has not yet been loaded in this context or a parent context, a new instance is allocated using the class default constructor and then loaded in this context.

loadAndBuild

protected abstract void loadAndBuild(ComputeContext.Program program)

Loads and builds the specified program.

unloadAndFree

protected abstract void unloadAndFree(ComputeContext.Program program)

Unloads and free the specified program.