1 package net.bmahe.genetics4j.gpu.spec.fitness.cldata;
2
3 import java.util.Objects;
4
5 import org.apache.commons.lang3.Validate;
6 import org.immutables.value.Value;
7 import org.jocl.cl_mem;
8
9 /**
10 * Container representing data stored in OpenCL device memory for GPU-accelerated evolutionary algorithm processing.
11 *
12 * <p>CLData encapsulates the information needed to reference and manage data that has been allocated and stored on an
13 * OpenCL device (GPU). This includes the OpenCL memory object, the data type, and the number of elements, providing a
14 * type-safe way to work with GPU memory buffers in evolutionary algorithm fitness evaluation.
15 *
16 * <p>Key characteristics:
17 * <ul>
18 * <li><strong>Memory reference</strong>: OpenCL memory object (cl_mem) pointing to device memory</li>
19 * <li><strong>Type information</strong>: OpenCL data type for proper kernel parameter binding</li>
20 * <li><strong>Size tracking</strong>: Number of elements for bounds checking and memory management</li>
21 * <li><strong>Resource management</strong>: Facilitates proper cleanup of OpenCL memory objects</li>
22 * </ul>
23 *
24 * <p>Common usage patterns:
25 *
26 * <pre>{@code
27 * // Create CLData for population chromosomes
28 * CLData populationData = CLData.of(chromosomeBuffer, CL.CL_FLOAT, populationSize * chromosomeLength);
29 *
30 * // Create CLData for fitness results
31 * CLData fitnessData = CLData.of(fitnessBuffer, CL.CL_DOUBLE, populationSize);
32 *
33 * // Create CLData for algorithm parameters
34 * CLData parameterData = CLData.of(paramBuffer, CL.CL_INT, parameterCount);
35 *
36 * // Use in kernel execution
37 * clSetKernelArg(kernel, 0, Sizeof.cl_mem, Pointer.to(populationData.clMem()));
38 * clSetKernelArg(kernel, 1, Sizeof.cl_mem, Pointer.to(fitnessData.clMem()));
39 * }</pre>
40 *
41 * <p>Memory lifecycle management:
42 * <ol>
43 * <li><strong>Allocation</strong>: Memory is allocated using clCreateBuffer or similar OpenCL functions</li>
44 * <li><strong>Wrapping</strong>: CLData object is created to wrap the allocated memory</li>
45 * <li><strong>Usage</strong>: Memory is used in kernel execution through CLData references</li>
46 * <li><strong>Cleanup</strong>: Memory is released using clReleaseMemObject when no longer needed</li>
47 * </ol>
48 *
49 * <p>Data type mapping:
50 * <ul>
51 * <li><strong>CL_FLOAT</strong>: Single-precision floating-point data</li>
52 * <li><strong>CL_DOUBLE</strong>: Double-precision floating-point data</li>
53 * <li><strong>CL_INT</strong>: 32-bit integer data</li>
54 * <li><strong>CL_CHAR</strong>: 8-bit character data</li>
55 * </ul>
56 *
57 * <p>Error handling considerations:
58 * <ul>
59 * <li><strong>Memory validation</strong>: Ensures cl_mem objects are valid before use</li>
60 * <li><strong>Type safety</strong>: Validates OpenCL data types are positive</li>
61 * <li><strong>Size validation</strong>: Ensures element counts are positive</li>
62 * <li><strong>Resource tracking</strong>: Facilitates proper memory cleanup</li>
63 * </ul>
64 *
65 * @see DataLoader
66 * @see ResultExtractor
67 * @see net.bmahe.genetics4j.gpu.spec.fitness.OpenCLFitness
68 */
69 @Value.Immutable
70 public interface CLData {
71
72 /**
73 * Returns the OpenCL memory object that references the data stored on the device.
74 *
75 * @return the OpenCL memory object (cl_mem) containing the device data
76 */
77 @Value.Parameter
78 cl_mem clMem();
79
80 /**
81 * Returns the OpenCL data type of the elements stored in the memory buffer.
82 *
83 * <p>Common OpenCL types include CL_FLOAT, CL_DOUBLE, CL_INT, and CL_CHAR. This information is used for proper
84 * kernel parameter binding and type checking.
85 *
86 * @return the OpenCL data type constant (e.g., CL_FLOAT, CL_DOUBLE)
87 */
88 @Value.Parameter
89 int clType();
90
91 /**
92 * Returns the number of elements stored in the OpenCL memory buffer.
93 *
94 * <p>This represents the count of individual data elements (not bytes) contained in the memory object. For example,
95 * a buffer containing 1000 floating-point values would have a size of 1000, regardless of the actual byte size.
96 *
97 * @return the number of elements in the memory buffer
98 */
99 @Value.Parameter
100 int size();
101
102 /**
103 * Creates a new CLData instance with the specified OpenCL memory object, data type, and size.
104 *
105 * @param clMem the OpenCL memory object containing the device data
106 * @param clType the OpenCL data type constant (e.g., CL_FLOAT, CL_DOUBLE)
107 * @param size the number of elements in the memory buffer
108 * @return a new CLData instance
109 * @throws IllegalArgumentException if clMem is null, clType is not positive, or size is not positive
110 */
111 static CLData of(final cl_mem clMem, final int clType, final int size) {
112 Objects.requireNonNull(clMem);
113 Validate.isTrue(clType > 0);
114 Validate.isTrue(size > 0);
115
116 return ImmutableCLData.of(clMem, clType, size);
117 }
118 }