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