Package net.bmahe.genetics4j.gpu.opencl

Class DeviceUtils

java.lang.Object
net.bmahe.genetics4j.gpu.opencl.DeviceUtils
public class DeviceUtils extends Object
Utility class providing convenient methods for OpenCL device discovery and information queries.

DeviceUtils encapsulates the low-level OpenCL API calls required for device enumeration and property retrieval, providing a higher-level interface for GPU-accelerated evolutionary algorithm implementations. This class handles the OpenCL buffer management and type conversions necessary for interacting with the native OpenCL runtime.

Key functionality includes:

  • Device enumeration: Discover available devices on OpenCL platforms
  • Property queries: Retrieve device characteristics and capabilities
  • Type conversions: Convert between OpenCL native types and Java types
  • Buffer management: Handle memory allocation for OpenCL information queries

Common usage patterns: 


 // Enumerate devices on a platform
 int deviceCount = DeviceUtils.numDevices(platformId);
 List<cl_device_id> deviceIds = DeviceUtils.getDeviceIds(platformId, deviceCount);
 
 // Query device properties
 String deviceName = DeviceUtils.getDeviceInfoString(deviceId, CL.CL_DEVICE_NAME);
 int computeUnits = DeviceUtils.getDeviceInfoInt(deviceId, CL.CL_DEVICE_MAX_COMPUTE_UNITS);
 long maxWorkGroupSize = DeviceUtils.getDeviceInfoLong(deviceId, CL.CL_DEVICE_MAX_WORK_GROUP_SIZE);
 
 // Query array properties
 int maxDimensions = DeviceUtils.getDeviceInfoInt(deviceId, CL.CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS);
 long[] maxWorkItemSizes = DeviceUtils.getDeviceInfoLongArray(deviceId, 
     CL.CL_DEVICE_MAX_WORK_ITEM_SIZES, maxDimensions);

Device type filtering:

  • CL_DEVICE_TYPE_ALL: All available devices
  • CL_DEVICE_TYPE_GPU: GPU devices only
  • CL_DEVICE_TYPE_CPU: CPU devices only
  • CL_DEVICE_TYPE_ACCELERATOR: Accelerator devices only

Error handling:

  • Parameter validation: Validates all input parameters
  • OpenCL error propagation: OpenCL errors are propagated as runtime exceptions
  • Memory management: Automatically handles buffer allocation and cleanup
See Also:

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    DeviceUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<org.jocl.cl_device_id>
    getDeviceIds(org.jocl.cl_platform_id platformId, int numDevices)
    Returns a list of all OpenCL device identifiers from the platform.
    static List<org.jocl.cl_device_id>
    getDeviceIds(org.jocl.cl_platform_id platformId, int numDevices, long deviceType)
    Returns a list of OpenCL device identifiers of the specified type from the platform.
    static int
    getDeviceInfoInt(org.jocl.cl_device_id deviceId, int parameter)
    Queries and returns a single integer property of the specified OpenCL device.
    static long
    getDeviceInfoLong(org.jocl.cl_device_id deviceId, int parameter)
    Queries and returns a single long property of the specified OpenCL device.
    static long[]
    getDeviceInfoLongArray(org.jocl.cl_device_id deviceId, int parameter, int size)
    Queries and returns a long array property of the specified OpenCL device.
    static String
    getDeviceInfoString(org.jocl.cl_device_id deviceId, int parameter)
    Queries and returns a string property of the specified OpenCL device.
    static int
    numDevices(org.jocl.cl_platform_id platformId)
    Returns the total number of OpenCL devices available on the platform.
    static int
    numDevices(org.jocl.cl_platform_id platformId, long deviceType)
    Returns the number of OpenCL devices of the specified type available on the platform.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DeviceUtils

      private DeviceUtils()

  • Method Details

    • numDevices

      public static int numDevices(org.jocl.cl_platform_id platformId, long deviceType)
      Returns the number of OpenCL devices of the specified type available on the platform.
      Parameters:
      platformId - the OpenCL platform to query
      deviceType - the type of devices to count (e.g., CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ALL)
      Returns:
      the number of available devices of the specified type
      Throws:
      IllegalArgumentException - if platformId is null

    • numDevices

      public static int numDevices(org.jocl.cl_platform_id platformId)
      Returns the total number of OpenCL devices available on the platform.

      This is equivalent to calling numDevices(cl_platform_id, long) with CL_DEVICE_TYPE_ALL as the device type.

      Parameters:
      platformId - the OpenCL platform to query
      Returns:
      the total number of available devices on the platform
      Throws:
      IllegalArgumentException - if platformId is null

    • getDeviceIds

      public static List<org.jocl.cl_device_id> getDeviceIds(org.jocl.cl_platform_id platformId, int numDevices, long deviceType)
      Returns a list of OpenCL device identifiers of the specified type from the platform.
      Parameters:
      platformId - the OpenCL platform to query
      numDevices - the number of devices to retrieve
      deviceType - the type of devices to retrieve (e.g., CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ALL)
      Returns:
      list of OpenCL device identifiers
      Throws:
      IllegalArgumentException - if platformId is null or numDevices is not positive

    • getDeviceIds

      public static List<org.jocl.cl_device_id> getDeviceIds(org.jocl.cl_platform_id platformId, int numDevices)
      Returns a list of all OpenCL device identifiers from the platform.

      This is equivalent to calling getDeviceIds(cl_platform_id, int, long) with CL_DEVICE_TYPE_ALL as the device type.

      Parameters:
      platformId - the OpenCL platform to query
      numDevices - the number of devices to retrieve
      Returns:
      list of all OpenCL device identifiers
      Throws:
      IllegalArgumentException - if platformId is null or numDevices is not positive

    • getDeviceInfoString

      public static String getDeviceInfoString(org.jocl.cl_device_id deviceId, int parameter)
      Queries and returns a string property of the specified OpenCL device.

      This method handles the OpenCL API calls and buffer management required to retrieve string properties from devices, such as device name, vendor, or version information.

      Parameters:
      deviceId - the OpenCL device to query
      parameter - the OpenCL parameter constant (e.g., CL_DEVICE_NAME, CL_DEVICE_VENDOR)
      Returns:
      the string value of the requested device property
      Throws:
      IllegalArgumentException - if deviceId is null

    • getDeviceInfoLongArray

      public static long[] getDeviceInfoLongArray(org.jocl.cl_device_id deviceId, int parameter, int size)
      Queries and returns a long array property of the specified OpenCL device.

      This method is useful for retrieving array properties such as maximum work-item sizes per dimension, which require multiple values to fully describe the device capability.

      Parameters:
      deviceId - the OpenCL device to query
      parameter - the OpenCL parameter constant (e.g., CL_DEVICE_MAX_WORK_ITEM_SIZES)
      size - the number of long values to retrieve
      Returns:
      array of long values for the requested device property
      Throws:
      IllegalArgumentException - if deviceId is null or size is not positive

    • getDeviceInfoLong

      public static long getDeviceInfoLong(org.jocl.cl_device_id deviceId, int parameter)
      Queries and returns a single long property of the specified OpenCL device.

      This method is useful for retrieving single long value properties such as maximum work group size, global memory size, or local memory size.

      Parameters:
      deviceId - the OpenCL device to query
      parameter - the OpenCL parameter constant (e.g., CL_DEVICE_MAX_WORK_GROUP_SIZE)
      Returns:
      the long value of the requested device property
      Throws:
      IllegalArgumentException - if deviceId is null

    • getDeviceInfoInt

      public static int getDeviceInfoInt(org.jocl.cl_device_id deviceId, int parameter)
      Queries and returns a single integer property of the specified OpenCL device.

      This method is useful for retrieving integer properties such as maximum compute units, maximum clock frequency, or maximum work-item dimensions.

      Parameters:
      deviceId - the OpenCL device to query
      parameter - the OpenCL parameter constant (e.g., CL_DEVICE_MAX_COMPUTE_UNITS)
      Returns:
      the integer value of the requested device property
      Throws:
      IllegalArgumentException - if deviceId is null