View Javadoc
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 }