1 package net.bmahe.genetics4j.gpu.opencl; 2 3 import java.util.Map; 4 5 import org.immutables.value.Value; 6 import org.jocl.cl_command_queue; 7 import org.jocl.cl_context; 8 import org.jocl.cl_kernel; 9 import org.jocl.cl_program; 10 11 import net.bmahe.genetics4j.gpu.opencl.model.Device; 12 import net.bmahe.genetics4j.gpu.opencl.model.KernelInfo; 13 import net.bmahe.genetics4j.gpu.opencl.model.Platform; 14 15 /** 16 * Encapsulates a complete OpenCL execution environment for a specific device with compiled kernels and runtime context. 17 * 18 * <p>OpenCLExecutionContext represents a fully initialized OpenCL execution environment tied to a specific 19 * device and containing all the resources needed for kernel execution. This includes the OpenCL context, 20 * command queue, compiled program, and kernel objects, along with associated metadata about platform 21 * and device capabilities. 22 * 23 * <p>The execution context serves as the primary interface between high-level fitness evaluation code 24 * and low-level OpenCL operations. It provides access to: 25 * <ul> 26 * <li><strong>Device information</strong>: Platform and device metadata for optimization decisions</li> 27 * <li><strong>OpenCL runtime</strong>: Context and command queue for memory and execution management</li> 28 * <li><strong>Compiled kernels</strong>: Ready-to-execute kernel objects with associated metadata</li> 29 * <li><strong>Execution parameters</strong>: Kernel work group information for optimal kernel launch</li> 30 * </ul> 31 * 32 * <p>Context lifecycle and management: 33 * <ol> 34 * <li><strong>Creation</strong>: Built by {@link net.bmahe.genetics4j.gpu.GPUFitnessEvaluator} during initialization</li> 35 * <li><strong>Usage</strong>: Passed to fitness functions for kernel execution and memory operations</li> 36 * <li><strong>Cleanup</strong>: Resources automatically released by the fitness evaluator</li> 37 * </ol> 38 * 39 * <p>Key usage patterns in fitness evaluation: 40 * <pre>{@code 41 * public CompletableFuture<List<Double>> compute(OpenCLExecutionContext context, 42 * ExecutorService executor, long generation, List<Genotype> genotypes) { 43 * 44 * return CompletableFuture.supplyAsync(() -> { 45 * // Access device capabilities for optimization 46 * Device device = context.device(); 47 * int maxWorkGroupSize = device.maxWorkGroupSize(); 48 * 49 * // Get compiled kernel for execution 50 * cl_kernel fitnessKernel = context.kernels().get("fitness_evaluation"); 51 * 52 * // Get kernel execution parameters 53 * KernelInfo kernelInfo = context.kernelInfo("fitness_evaluation"); 54 * int preferredWorkGroupSize = kernelInfo.preferredWorkGroupSizeMultiple(); 55 * 56 * // Execute kernel with optimal work group configuration 57 * executeKernel(context, fitnessKernel, genotypes.size(), preferredWorkGroupSize); 58 * 59 * // Extract results using the execution context 60 * return extractResults(context, genotypes.size()); 61 * }, executor); 62 * } 63 * }</pre> 64 * 65 * <p>Memory management considerations: 66 * <ul> 67 * <li><strong>Context ownership</strong>: The execution context owns OpenCL resources</li> 68 * <li><strong>Thread safety</strong>: OpenCL contexts are not thread-safe; use appropriate synchronization</li> 69 * <li><strong>Resource lifecycle</strong>: Resources are managed by the parent fitness evaluator</li> 70 * <li><strong>Command queue usage</strong>: Use the provided command queue for all operations</li> 71 * </ul> 72 * 73 * <p>Performance optimization capabilities: 74 * <ul> 75 * <li><strong>Device-specific tuning</strong>: Access device capabilities for optimal kernel configuration</li> 76 * <li><strong>Kernel information</strong>: Use kernel metadata for work group size optimization</li> 77 * <li><strong>Memory hierarchy</strong>: Leverage device memory characteristics for data layout</li> 78 * <li><strong>Compute capabilities</strong>: Adapt algorithms based on device compute units and features</li> 79 * </ul> 80 * 81 * <p>Error handling and robustness: 82 * <ul> 83 * <li><strong>Resource validation</strong>: All OpenCL objects are validated during context creation</li> 84 * <li><strong>Device compatibility</strong>: Context ensures device supports required kernels</li> 85 * <li><strong>Kernel availability</strong>: All specified kernels are guaranteed to be compiled and available</li> 86 * <li><strong>Exception safety</strong>: Context provides consistent state even if operations fail</li> 87 * </ul> 88 * 89 * @see net.bmahe.genetics4j.gpu.GPUFitnessEvaluator 90 * @see net.bmahe.genetics4j.gpu.spec.fitness.OpenCLFitness 91 * @see Platform 92 * @see Device 93 * @see KernelInfo 94 */ 95 @Value.Immutable 96 public interface OpenCLExecutionContext { 97 98 /** 99 * Returns the OpenCL platform associated with this execution context. 100 * 101 * @return the platform containing the device for this context 102 */ 103 @Value.Parameter 104 Platform platform(); 105 106 /** 107 * Returns the OpenCL device associated with this execution context. 108 * 109 * @return the device on which kernels will be executed 110 */ 111 @Value.Parameter 112 Device device(); 113 114 /** 115 * Returns the OpenCL context for this execution environment. 116 * 117 * @return the OpenCL context for memory and resource management 118 */ 119 @Value.Parameter 120 cl_context clContext(); 121 122 /** 123 * Returns the OpenCL command queue for kernel execution and memory operations. 124 * 125 * @return the command queue for submitting OpenCL operations 126 */ 127 @Value.Parameter 128 cl_command_queue clCommandQueue(); 129 130 /** 131 * Returns the compiled OpenCL program containing all kernels. 132 * 133 * @return the compiled OpenCL program object 134 */ 135 @Value.Parameter 136 cl_program clProgram(); 137 138 /** 139 * Returns a map of kernel names to compiled kernel objects. 140 * 141 * @return map from kernel names to executable kernel objects 142 */ 143 @Value.Parameter 144 Map<String, cl_kernel> kernels(); 145 146 /** 147 * Returns a map of kernel names to kernel execution information. 148 * 149 * @return map from kernel names to kernel metadata and execution parameters 150 */ 151 @Value.Parameter 152 Map<String, KernelInfo> kernelInfos(); 153 154 /** 155 * Convenience method to retrieve kernel execution information by name. 156 * 157 * @param kernelName the name of the kernel to get information for 158 * @return the kernel execution information, or null if not found 159 */ 160 default KernelInfo kernelInfo(final String kernelName) { 161 return kernelInfos().get(kernelName); 162 } 163 164 public static class Builder extends ImmutableOpenCLExecutionContext.Builder { 165 } 166 167 /** 168 * Creates a new builder for constructing OpenCL execution contexts. 169 * 170 * @return a new builder instance 171 */ 172 public static Builder builder() { 173 return new Builder(); 174 } 175 }