| 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 |
2
1. of : removed call to net/bmahe/genetics4j/gpu/spec/fitness/cldata/ImmutableCLData::of → NO_COVERAGE 2. of : replaced return value with null for net/bmahe/genetics4j/gpu/spec/fitness/cldata/CLData::of → NO_COVERAGE |
return ImmutableCLData.of(clMem, clType, size); |
| 117 | } | |
| 118 | } | |
Mutations | ||
| 116 |
1.1 2.2 |