CLData.java
package net.bmahe.genetics4j.gpu.spec.fitness.cldata;
import org.apache.commons.lang3.Validate;
import org.immutables.value.Value;
import org.jocl.cl_mem;
/**
* Container representing data stored in OpenCL device memory for GPU-accelerated evolutionary algorithm processing.
*
* <p>CLData encapsulates the information needed to reference and manage data that has been allocated and stored
* on an OpenCL device (GPU). This includes the OpenCL memory object, the data type, and the number of elements,
* providing a type-safe way to work with GPU memory buffers in evolutionary algorithm fitness evaluation.
*
* <p>Key characteristics:
* <ul>
* <li><strong>Memory reference</strong>: OpenCL memory object (cl_mem) pointing to device memory</li>
* <li><strong>Type information</strong>: OpenCL data type for proper kernel parameter binding</li>
* <li><strong>Size tracking</strong>: Number of elements for bounds checking and memory management</li>
* <li><strong>Resource management</strong>: Facilitates proper cleanup of OpenCL memory objects</li>
* </ul>
*
* <p>Common usage patterns:
* <pre>{@code
* // Create CLData for population chromosomes
* CLData populationData = CLData.of(chromosomeBuffer, CL.CL_FLOAT, populationSize * chromosomeLength);
*
* // Create CLData for fitness results
* CLData fitnessData = CLData.of(fitnessBuffer, CL.CL_DOUBLE, populationSize);
*
* // Create CLData for algorithm parameters
* CLData parameterData = CLData.of(paramBuffer, CL.CL_INT, parameterCount);
*
* // Use in kernel execution
* clSetKernelArg(kernel, 0, Sizeof.cl_mem, Pointer.to(populationData.clMem()));
* clSetKernelArg(kernel, 1, Sizeof.cl_mem, Pointer.to(fitnessData.clMem()));
* }</pre>
*
* <p>Memory lifecycle management:
* <ol>
* <li><strong>Allocation</strong>: Memory is allocated using clCreateBuffer or similar OpenCL functions</li>
* <li><strong>Wrapping</strong>: CLData object is created to wrap the allocated memory</li>
* <li><strong>Usage</strong>: Memory is used in kernel execution through CLData references</li>
* <li><strong>Cleanup</strong>: Memory is released using clReleaseMemObject when no longer needed</li>
* </ol>
*
* <p>Data type mapping:
* <ul>
* <li><strong>CL_FLOAT</strong>: Single-precision floating-point data</li>
* <li><strong>CL_DOUBLE</strong>: Double-precision floating-point data</li>
* <li><strong>CL_INT</strong>: 32-bit integer data</li>
* <li><strong>CL_CHAR</strong>: 8-bit character data</li>
* </ul>
*
* <p>Error handling considerations:
* <ul>
* <li><strong>Memory validation</strong>: Ensures cl_mem objects are valid before use</li>
* <li><strong>Type safety</strong>: Validates OpenCL data types are positive</li>
* <li><strong>Size validation</strong>: Ensures element counts are positive</li>
* <li><strong>Resource tracking</strong>: Facilitates proper memory cleanup</li>
* </ul>
*
* @see DataLoader
* @see ResultExtractor
* @see net.bmahe.genetics4j.gpu.spec.fitness.OpenCLFitness
*/
@Value.Immutable
public interface CLData {
/**
* Returns the OpenCL memory object that references the data stored on the device.
*
* @return the OpenCL memory object (cl_mem) containing the device data
*/
@Value.Parameter
cl_mem clMem();
/**
* Returns the OpenCL data type of the elements stored in the memory buffer.
*
* <p>Common OpenCL types include CL_FLOAT, CL_DOUBLE, CL_INT, and CL_CHAR.
* This information is used for proper kernel parameter binding and type checking.
*
* @return the OpenCL data type constant (e.g., CL_FLOAT, CL_DOUBLE)
*/
@Value.Parameter
int clType();
/**
* Returns the number of elements stored in the OpenCL memory buffer.
*
* <p>This represents the count of individual data elements (not bytes) contained
* in the memory object. For example, a buffer containing 1000 floating-point values
* would have a size of 1000, regardless of the actual byte size.
*
* @return the number of elements in the memory buffer
*/
@Value.Parameter
int size();
/**
* Creates a new CLData instance with the specified OpenCL memory object, data type, and size.
*
* @param clMem the OpenCL memory object containing the device data
* @param clType the OpenCL data type constant (e.g., CL_FLOAT, CL_DOUBLE)
* @param size the number of elements in the memory buffer
* @return a new CLData instance
* @throws IllegalArgumentException if clMem is null, clType is not positive, or size is not positive
*/
static CLData of(final cl_mem clMem, final int clType, final int size) {
Validate.notNull(clMem);
Validate.isTrue(clType > 0);
Validate.isTrue(size > 0);
return ImmutableCLData.of(clMem, clType, size);
}
}