Package net.bmahe.genetics4j.gpu.opencl

Interface OpenCLExecutionContext

All Known Implementing Classes:
ImmutableOpenCLExecutionContext
@Immutable public interface OpenCLExecutionContext
Encapsulates a complete OpenCL execution environment for a specific device with compiled kernels and runtime context.

OpenCLExecutionContext represents a fully initialized OpenCL execution environment tied to a specific device and containing all the resources needed for kernel execution. This includes the OpenCL context, command queue, compiled program, and kernel objects, along with associated metadata about platform and device capabilities.

The execution context serves as the primary interface between high-level fitness evaluation code and low-level OpenCL operations. It provides access to:

  • Device information: Platform and device metadata for optimization decisions
  • OpenCL runtime: Context and command queue for memory and execution management
  • Compiled kernels: Ready-to-execute kernel objects with associated metadata
  • Execution parameters: Kernel work group information for optimal kernel launch

Context lifecycle and management:

  1. Creation: Built by GPUFitnessEvaluator during initialization
  2. Usage: Passed to fitness functions for kernel execution and memory operations
  3. Cleanup: Resources automatically released by the fitness evaluator

Key usage patterns in fitness evaluation: 


 public CompletableFuture<List<Double>> compute(OpenCLExecutionContext context, 
         ExecutorService executor, long generation, List<Genotype> genotypes) {
     
     return CompletableFuture.supplyAsync(() -> {
         // Access device capabilities for optimization
         Device device = context.device();
         int maxWorkGroupSize = device.maxWorkGroupSize();
         
         // Get compiled kernel for execution
         cl_kernel fitnessKernel = context.kernels().get("fitness_evaluation");
         
         // Get kernel execution parameters
         KernelInfo kernelInfo = context.kernelInfo("fitness_evaluation");
         int preferredWorkGroupSize = kernelInfo.preferredWorkGroupSizeMultiple();
         
         // Execute kernel with optimal work group configuration
         executeKernel(context, fitnessKernel, genotypes.size(), preferredWorkGroupSize);
         
         // Extract results using the execution context
         return extractResults(context, genotypes.size());
     }, executor);
 }

Memory management considerations:

  • Context ownership: The execution context owns OpenCL resources
  • Thread safety: OpenCL contexts are not thread-safe; use appropriate synchronization
  • Resource lifecycle: Resources are managed by the parent fitness evaluator
  • Command queue usage: Use the provided command queue for all operations

Performance optimization capabilities:

  • Device-specific tuning: Access device capabilities for optimal kernel configuration
  • Kernel information: Use kernel metadata for work group size optimization
  • Memory hierarchy: Leverage device memory characteristics for data layout
  • Compute capabilities: Adapt algorithms based on device compute units and features

Error handling and robustness:

  • Resource validation: All OpenCL objects are validated during context creation
  • Device compatibility: Context ensures device supports required kernels
  • Kernel availability: All specified kernels are guaranteed to be compiled and available
  • Exception safety: Context provides consistent state even if operations fail
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    OpenCLExecutionContext.Builder
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static OpenCLExecutionContext.Builder
    builder()
    Creates a new builder for constructing OpenCL execution contexts.
    org.jocl.cl_command_queue
    clCommandQueue()
    Returns the OpenCL command queue for kernel execution and memory operations.
    org.jocl.cl_context
    clContext()
    Returns the OpenCL context for this execution environment.
    org.jocl.cl_program
    clProgram()
    Returns the compiled OpenCL program containing all kernels.
    Device
    device()
    Returns the OpenCL device associated with this execution context.
    default KernelInfo
    kernelInfo(String kernelName)
    Convenience method to retrieve kernel execution information by name.
    Map<String,KernelInfo>
    kernelInfos()
    Returns a map of kernel names to kernel execution information.
    Map<String,org.jocl.cl_kernel>
    kernels()
    Returns a map of kernel names to compiled kernel objects.
    Platform
    platform()
    Returns the OpenCL platform associated with this execution context.

  • Method Details

    • platform

      @Parameter Platform platform()
      Returns the OpenCL platform associated with this execution context.
      Returns:
      the platform containing the device for this context

    • device

      @Parameter Device device()
      Returns the OpenCL device associated with this execution context.
      Returns:
      the device on which kernels will be executed

    • clContext

      @Parameter org.jocl.cl_context clContext()
      Returns the OpenCL context for this execution environment.
      Returns:
      the OpenCL context for memory and resource management

    • clCommandQueue

      @Parameter org.jocl.cl_command_queue clCommandQueue()
      Returns the OpenCL command queue for kernel execution and memory operations.
      Returns:
      the command queue for submitting OpenCL operations

    • clProgram

      @Parameter org.jocl.cl_program clProgram()
      Returns the compiled OpenCL program containing all kernels.
      Returns:
      the compiled OpenCL program object

    • kernels

      @Parameter Map<String,org.jocl.cl_kernel> kernels()
      Returns a map of kernel names to compiled kernel objects.
      Returns:
      map from kernel names to executable kernel objects

    • kernelInfos

      @Parameter Map<String,KernelInfo> kernelInfos()
      Returns a map of kernel names to kernel execution information.
      Returns:
      map from kernel names to kernel metadata and execution parameters

    • kernelInfo

      default KernelInfo kernelInfo(String kernelName)
      Convenience method to retrieve kernel execution information by name.
      Parameters:
      kernelName - the name of the kernel to get information for
      Returns:
      the kernel execution information, or null if not found

    • builder

      static OpenCLExecutionContext.Builder builder()
      Creates a new builder for constructing OpenCL execution contexts.
      Returns:
      a new builder instance