KernelInfoUtils.java
package net.bmahe.genetics4j.gpu.opencl;
import org.apache.commons.lang3.Validate;
import org.jocl.CL;
import org.jocl.Pointer;
import org.jocl.Sizeof;
import org.jocl.cl_device_id;
import org.jocl.cl_kernel;
/**
* Utility class providing convenient methods for querying OpenCL kernel work group information.
*
* <p>KernelInfoUtils encapsulates the low-level OpenCL API calls required for retrieving kernel-specific
* execution characteristics on target devices. This information is essential for optimizing kernel
* launch parameters and ensuring efficient resource utilization in GPU-accelerated evolutionary algorithms.
*
* <p>Key functionality includes:
* <ul>
* <li><strong>Work group queries</strong>: Retrieve kernel-specific work group size limits and preferences</li>
* <li><strong>Memory usage queries</strong>: Query local and private memory requirements per work-item</li>
* <li><strong>Performance optimization</strong>: Access preferred work group size multiples for optimal execution</li>
* <li><strong>Resource validation</strong>: Obtain kernel resource requirements for launch parameter validation</li>
* </ul>
*
* <p>Common usage patterns:
* <pre>{@code
* // Query kernel work group characteristics
* long maxWorkGroupSize = KernelInfoUtils.getKernelWorkGroupInfoLong(
* deviceId, kernel, CL.CL_KERNEL_WORK_GROUP_SIZE);
*
* long preferredMultiple = KernelInfoUtils.getKernelWorkGroupInfoLong(
* deviceId, kernel, CL.CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE);
*
* // Query memory requirements
* long localMemSize = KernelInfoUtils.getKernelWorkGroupInfoLong(
* deviceId, kernel, CL.CL_KERNEL_LOCAL_MEM_SIZE);
*
* long privateMemSize = KernelInfoUtils.getKernelWorkGroupInfoLong(
* deviceId, kernel, CL.CL_KERNEL_PRIVATE_MEM_SIZE);
*
* // Optimize work group size based on kernel characteristics
* long optimalWorkGroupSize = (maxWorkGroupSize / preferredMultiple) * preferredMultiple;
* }</pre>
*
* <p>Kernel optimization workflow:
* <ol>
* <li><strong>Kernel compilation</strong>: Compile kernel for target device</li>
* <li><strong>Characteristic query</strong>: Retrieve kernel-specific execution parameters</li>
* <li><strong>Launch optimization</strong>: Configure work group sizes based on kernel requirements</li>
* <li><strong>Resource validation</strong>: Ensure memory requirements don't exceed device limits</li>
* </ol>
*
* <p>Error handling:
* <ul>
* <li><strong>Parameter validation</strong>: Validates all input parameters</li>
* <li><strong>OpenCL error propagation</strong>: OpenCL errors are propagated as runtime exceptions</li>
* <li><strong>Memory management</strong>: Automatically handles buffer allocation and cleanup</li>
* </ul>
*
* @see KernelInfo
* @see KernelInfoReader
* @see net.bmahe.genetics4j.gpu.opencl.model.Device
*/
public class KernelInfoUtils {
private KernelInfoUtils() {
}
/**
* Queries and returns a long value for kernel work group information on the specified device.
*
* <p>This method retrieves kernel-specific execution characteristics that vary by device,
* such as maximum work group size, preferred work group size multiples, and memory usage
* requirements. This information is essential for optimizing kernel launch parameters.
*
* @param deviceId the OpenCL device to query
* @param kernel the compiled OpenCL kernel
* @param parameter the OpenCL parameter constant (e.g., CL_KERNEL_WORK_GROUP_SIZE, CL_KERNEL_LOCAL_MEM_SIZE)
* @return the long value of the requested kernel work group property
* @throws IllegalArgumentException if deviceId or kernel is null
*/
public static long getKernelWorkGroupInfoLong(final cl_device_id deviceId, final cl_kernel kernel,
final int parameter) {
Validate.notNull(deviceId);
Validate.notNull(kernel);
final long[] values = new long[1];
CL.clGetKernelWorkGroupInfo(kernel, deviceId, parameter, Sizeof.cl_long, Pointer.to(values), null);
return values[0];
}
}