PlatformUtils.java

package net.bmahe.genetics4j.gpu.opencl;

import java.util.Arrays;
import java.util.List;

import org.apache.commons.lang3.Validate;
import org.jocl.CL;
import org.jocl.Pointer;
import org.jocl.cl_platform_id;

/**
 * Utility class providing convenient methods for OpenCL platform discovery and information queries.
 * 
 * <p>PlatformUtils encapsulates the low-level OpenCL API calls required for platform 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.
 * 
 * <p>Key functionality includes:
 * <ul>
 * <li><strong>Platform enumeration</strong>: Discover available OpenCL platforms in the system</li>
 * <li><strong>Property queries</strong>: Retrieve platform characteristics and capabilities</li>
 * <li><strong>Device counting</strong>: Count available devices on each platform</li>
 * <li><strong>Buffer management</strong>: Handle memory allocation for OpenCL information queries</li>
 * </ul>
 * 
 * <p>Common usage patterns:
 * 
 * <pre>{@code
 * // Enumerate platforms in the system
 * int platformCount = PlatformUtils.numPlatforms();
 * List<cl_platform_id> platformIds = PlatformUtils.platformIds(platformCount);
 * 
 * // Query platform properties
 * for (cl_platform_id platformId : platformIds) {
 * 	String platformName = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_NAME);
 * 	String vendor = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_VENDOR);
 * 	String version = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_VERSION);
 * 
 * 	// Count devices on this platform
 * 	int deviceCount = PlatformUtils.numDevices(platformId);
 * 	int gpuCount = PlatformUtils.numDevices(platformId, CL.CL_DEVICE_TYPE_GPU);
 * }
 * }</pre>
 * 
 * <p>Platform discovery workflow:
 * <ol>
 * <li><strong>System enumeration</strong>: Query the number of available platforms</li>
 * <li><strong>Platform retrieval</strong>: Get platform identifiers for all available platforms</li>
 * <li><strong>Property queries</strong>: Retrieve platform characteristics for filtering</li>
 * <li><strong>Device counting</strong>: Determine available devices for each platform</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>
 * <li><strong>Empty platform handling</strong>: Gracefully handles systems with no OpenCL platforms</li>
 * </ul>
 * 
 * @see Platform
 * @see PlatformReader
 * @see net.bmahe.genetics4j.gpu.opencl.model.PlatformProfile
 */
public class PlatformUtils {

	private PlatformUtils() {

	}

	/**
	 * Returns the number of OpenCL platforms available in the system.
	 * 
	 * @return the number of available OpenCL platforms
	 */
	public static int numPlatforms() {
		final int[] numPlatforms = new int[1];
		CL.clGetPlatformIDs(0, null, numPlatforms);

		return numPlatforms[0];
	}

	/**
	 * Returns a list of OpenCL platform identifiers for all available platforms.
	 * 
	 * @param numPlatforms the number of platforms to retrieve
	 * @return list of OpenCL platform identifiers, or empty list if numPlatforms is 0
	 * @throws IllegalArgumentException if numPlatforms is negative
	 */
	public static List<cl_platform_id> platformIds(final int numPlatforms) {
		Validate.isTrue(numPlatforms >= 0);

		if (numPlatforms == 0) {
			return List.of();
		}

		final cl_platform_id[] platformIds = new cl_platform_id[numPlatforms];
		CL.clGetPlatformIDs(platformIds.length, platformIds, null);

		return Arrays.asList(platformIds);
	}

	/**
	 * Queries and returns a string property of the specified OpenCL platform.
	 * 
	 * <p>This method handles the OpenCL API calls and buffer management required to retrieve string properties from
	 * platforms, such as platform name, vendor, or version information.
	 * 
	 * @param platformId   the OpenCL platform to query
	 * @param platformName the OpenCL parameter constant (e.g., CL_PLATFORM_NAME, CL_PLATFORM_VENDOR)
	 * @return the string value of the requested platform property
	 * @throws IllegalArgumentException if platformId is null
	 */
	public static String getStringParameter(final cl_platform_id platformId, final int platformName) {
		Validate.notNull(platformId);

		final long[] parameterSize = new long[1];
		CL.clGetPlatformInfo(platformId, platformName, 0, null, parameterSize);

		final byte[] buffer = new byte[(int) parameterSize[0]];
		CL.clGetPlatformInfo(platformId, platformName, buffer.length, Pointer.to(buffer), null);

		return new String(buffer, 0, buffer.length - 1);
	}

	/**
	 * Returns the number of OpenCL devices of the specified type available on the platform.
	 * 
	 * @param platformId the OpenCL platform to query
	 * @param deviceType the type of devices to count (e.g., CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ALL)
	 * @return the number of available devices of the specified type
	 * @throws IllegalArgumentException if platformId is null
	 */
	public static int numDevices(final cl_platform_id platformId, final long deviceType) {
		Validate.notNull(platformId);

		int[] numDevices = new int[1];
		CL.clGetDeviceIDs(platformId, deviceType, 0, null, numDevices);

		return numDevices[0];
	}

	/**
	 * Returns the total number of OpenCL devices available on the platform.
	 * 
	 * <p>This is equivalent to calling {@link #numDevices(cl_platform_id, long)} with {@code CL_DEVICE_TYPE_ALL} as the
	 * device type.
	 * 
	 * @param platformId the OpenCL platform to query
	 * @return the total number of available devices on the platform
	 * @throws IllegalArgumentException if platformId is null
	 */
	public static int numDevices(final cl_platform_id platformId) {
		Validate.notNull(platformId);

		return numDevices(platformId, CL.CL_DEVICE_TYPE_ALL);
	}
}


















Active mutators

CONDITIONALS_BOUNDARY
CONSTRUCTOR_CALLS
EMPTY_RETURNS
EXPERIMENTAL_ARGUMENT_PROPAGATION
EXPERIMENTAL_BIG_DECIMAL
EXPERIMENTAL_BIG_INTEGER
EXPERIMENTAL_MEMBER_VARIABLE
EXPERIMENTAL_NAKED_RECEIVER
EXPERIMENTAL_REMOVE_SWITCH_MUTATOR_[0-99]
EXPERIMENTAL_SWITCH
FALSE_RETURNS
INCREMENTS
INLINE_CONSTS
INVERT_NEGS
MATH
NEGATE_CONDITIONALS
NON_VOID_METHOD_CALLS
NULL_RETURNS
PRIMITIVE_RETURNS
REMOVE_CONDITIONALS_EQUAL_ELSE
REMOVE_CONDITIONALS_EQUAL_IF
REMOVE_CONDITIONALS_ORDER_ELSE
REMOVE_CONDITIONALS_ORDER_IF
REMOVE_INCREMENTS
TRUE_RETURNS
VOID_METHOD_CALLS

Tests examined

Report generated by PIT 1.20.3

1		package net.bmahe.genetics4j.gpu.opencl;
2
3		import java.util.Arrays;
4		import java.util.List;
5
6		import org.apache.commons.lang3.Validate;
7		import org.jocl.CL;
8		import org.jocl.Pointer;
9		import org.jocl.cl_platform_id;
10
11		/**
12		* Utility class providing convenient methods for OpenCL platform discovery and information queries.
13		*
14		* <p>PlatformUtils encapsulates the low-level OpenCL API calls required for platform enumeration and property
15		* retrieval, providing a higher-level interface for GPU-accelerated evolutionary algorithm implementations. This class
16		* handles the OpenCL buffer management and type conversions necessary for interacting with the native OpenCL runtime.
17		*
18		* <p>Key functionality includes:
19		* <ul>
20		* <li><strong>Platform enumeration</strong>: Discover available OpenCL platforms in the system</li>
21		* <li><strong>Property queries</strong>: Retrieve platform characteristics and capabilities</li>
22		* <li><strong>Device counting</strong>: Count available devices on each platform</li>
23		* <li><strong>Buffer management</strong>: Handle memory allocation for OpenCL information queries</li>
24		* </ul>
25		*
26		* <p>Common usage patterns:
27		*
28		* <pre>{@code
29		* // Enumerate platforms in the system
30		* int platformCount = PlatformUtils.numPlatforms();
31		* List<cl_platform_id> platformIds = PlatformUtils.platformIds(platformCount);
32		*
33		* // Query platform properties
34		* for (cl_platform_id platformId : platformIds) {
35		* String platformName = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_NAME);
36		* String vendor = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_VENDOR);
37		* String version = PlatformUtils.getStringParameter(platformId, CL.CL_PLATFORM_VERSION);
38		*
39		* // Count devices on this platform
40		* int deviceCount = PlatformUtils.numDevices(platformId);
41		* int gpuCount = PlatformUtils.numDevices(platformId, CL.CL_DEVICE_TYPE_GPU);
42		* }
43		* }</pre>
44		*
45		* <p>Platform discovery workflow:
46		* <ol>
47		* <li><strong>System enumeration</strong>: Query the number of available platforms</li>
48		* <li><strong>Platform retrieval</strong>: Get platform identifiers for all available platforms</li>
49		* <li><strong>Property queries</strong>: Retrieve platform characteristics for filtering</li>
50		* <li><strong>Device counting</strong>: Determine available devices for each platform</li>
51		* </ol>
52		*
53		* <p>Error handling:
54		* <ul>
55		* <li><strong>Parameter validation</strong>: Validates all input parameters</li>
56		* <li><strong>OpenCL error propagation</strong>: OpenCL errors are propagated as runtime exceptions</li>
57		* <li><strong>Memory management</strong>: Automatically handles buffer allocation and cleanup</li>
58		* <li><strong>Empty platform handling</strong>: Gracefully handles systems with no OpenCL platforms</li>
59		* </ul>
60		*
61		* @see Platform
62		* @see PlatformReader
63		* @see net.bmahe.genetics4j.gpu.opencl.model.PlatformProfile
64		*/
65		public class PlatformUtils {
66
67		private PlatformUtils() {
68
69		}
70
71		/**
72		* Returns the number of OpenCL platforms available in the system.
73		*
74		* @return the number of available OpenCL platforms
75		*/
76		public static int numPlatforms() {
77	1 1. numPlatforms : Substituted 1 with 0 → NO_COVERAGE	final int[] numPlatforms = new int[1];
78	3 1. numPlatforms : replaced call to org/jocl/CL::clGetPlatformIDs with argument → NO_COVERAGE 2. numPlatforms : removed call to org/jocl/CL::clGetPlatformIDs → NO_COVERAGE 3. numPlatforms : Substituted 0 with 1 → NO_COVERAGE	CL.clGetPlatformIDs(0, null, numPlatforms);
79
80	2 1. numPlatforms : replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numPlatforms → NO_COVERAGE 2. numPlatforms : Substituted 0 with 1 → NO_COVERAGE	return numPlatforms[0];
81		}
82
83		/**
84		* Returns a list of OpenCL platform identifiers for all available platforms.
85		*
86		* @param numPlatforms the number of platforms to retrieve
87		* @return list of OpenCL platform identifiers, or empty list if numPlatforms is 0
88		* @throws IllegalArgumentException if numPlatforms is negative
89		*/
90		public static List<cl_platform_id> platformIds(final int numPlatforms) {
91		Validate.isTrue(numPlatforms >= 0);
92
93	3 1. platformIds : negated conditional → NO_COVERAGE 2. platformIds : removed conditional - replaced equality check with true → NO_COVERAGE 3. platformIds : removed conditional - replaced equality check with false → NO_COVERAGE	if (numPlatforms == 0) {
94	1 1. platformIds : removed call to java/util/List::of → NO_COVERAGE	return List.of();
95		}
96
97		final cl_platform_id[] platformIds = new cl_platform_id[numPlatforms];
98	2 1. platformIds : replaced call to org/jocl/CL::clGetPlatformIDs with argument → NO_COVERAGE 2. platformIds : removed call to org/jocl/CL::clGetPlatformIDs → NO_COVERAGE	CL.clGetPlatformIDs(platformIds.length, platformIds, null);
99
100	2 1. platformIds : removed call to java/util/Arrays::asList → NO_COVERAGE 2. platformIds : replaced return value with Collections.emptyList for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::platformIds → NO_COVERAGE	return Arrays.asList(platformIds);
101		}
102
103		/**
104		* Queries and returns a string property of the specified OpenCL platform.
105		*
106		* <p>This method handles the OpenCL API calls and buffer management required to retrieve string properties from
107		* platforms, such as platform name, vendor, or version information.
108		*
109		* @param platformId the OpenCL platform to query
110		* @param platformName the OpenCL parameter constant (e.g., CL_PLATFORM_NAME, CL_PLATFORM_VENDOR)
111		* @return the string value of the requested platform property
112		* @throws IllegalArgumentException if platformId is null
113		*/
114		public static String getStringParameter(final cl_platform_id platformId, final int platformName) {
115		Validate.notNull(platformId);
116
117	1 1. getStringParameter : Substituted 1 with 0 → NO_COVERAGE	final long[] parameterSize = new long[1];
118	3 1. getStringParameter : removed call to org/jocl/CL::clGetPlatformInfo → NO_COVERAGE 2. getStringParameter : Substituted 0 with 1 → NO_COVERAGE 3. getStringParameter : replaced call to org/jocl/CL::clGetPlatformInfo with argument → NO_COVERAGE	CL.clGetPlatformInfo(platformId, platformName, 0, null, parameterSize);
119
120	1 1. getStringParameter : Substituted 0 with 1 → NO_COVERAGE	final byte[] buffer = new byte[(int) parameterSize[0]];
121	3 1. getStringParameter : replaced call to org/jocl/CL::clGetPlatformInfo with argument → NO_COVERAGE 2. getStringParameter : removed call to org/jocl/CL::clGetPlatformInfo → NO_COVERAGE 3. getStringParameter : removed call to org/jocl/Pointer::to → NO_COVERAGE	CL.clGetPlatformInfo(platformId, platformName, buffer.length, Pointer.to(buffer), null);
122
123	5 1. getStringParameter : removed call to java/lang/String::<init> → NO_COVERAGE 2. getStringParameter : Substituted 1 with 0 → NO_COVERAGE 3. getStringParameter : replaced return value with "" for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::getStringParameter → NO_COVERAGE 4. getStringParameter : Replaced integer subtraction with addition → NO_COVERAGE 5. getStringParameter : Substituted 0 with 1 → NO_COVERAGE	return new String(buffer, 0, buffer.length - 1);
124		}
125
126		/**
127		* Returns the number of OpenCL devices of the specified type available on the platform.
128		*
129		* @param platformId the OpenCL platform to query
130		* @param deviceType the type of devices to count (e.g., CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ALL)
131		* @return the number of available devices of the specified type
132		* @throws IllegalArgumentException if platformId is null
133		*/
134		public static int numDevices(final cl_platform_id platformId, final long deviceType) {
135		Validate.notNull(platformId);
136
137	1 1. numDevices : Substituted 1 with 0 → NO_COVERAGE	int[] numDevices = new int[1];
138	3 1. numDevices : Substituted 0 with 1 → NO_COVERAGE 2. numDevices : replaced call to org/jocl/CL::clGetDeviceIDs with argument → NO_COVERAGE 3. numDevices : removed call to org/jocl/CL::clGetDeviceIDs → NO_COVERAGE	CL.clGetDeviceIDs(platformId, deviceType, 0, null, numDevices);
139
140	2 1. numDevices : Substituted 0 with 1 → NO_COVERAGE 2. numDevices : replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE	return numDevices[0];
141		}
142
143		/**
144		* Returns the total number of OpenCL devices available on the platform.
145		*
146		* <p>This is equivalent to calling {@link #numDevices(cl_platform_id, long)} with {@code CL_DEVICE_TYPE_ALL} as the
147		* device type.
148		*
149		* @param platformId the OpenCL platform to query
150		* @return the total number of available devices on the platform
151		* @throws IllegalArgumentException if platformId is null
152		*/
153		public static int numDevices(final cl_platform_id platformId) {
154		Validate.notNull(platformId);
155
156	3 1. numDevices : Substituted -1 with 0 → NO_COVERAGE 2. numDevices : replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE 3. numDevices : removed call to net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE	return numDevices(platformId, CL.CL_DEVICE_TYPE_ALL);
157		}
158		}
		Mutations
77		1.1 Location : numPlatforms Killed by : none Substituted 1 with 0 → NO_COVERAGE
78		1.1 Location : numPlatforms Killed by : none replaced call to org/jocl/CL::clGetPlatformIDs with argument → NO_COVERAGE 2.2 Location : numPlatforms Killed by : none removed call to org/jocl/CL::clGetPlatformIDs → NO_COVERAGE 3.3 Location : numPlatforms Killed by : none Substituted 0 with 1 → NO_COVERAGE
80		1.1 Location : numPlatforms Killed by : none replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numPlatforms → NO_COVERAGE 2.2 Location : numPlatforms Killed by : none Substituted 0 with 1 → NO_COVERAGE
93		1.1 Location : platformIds Killed by : none negated conditional → NO_COVERAGE 2.2 Location : platformIds Killed by : none removed conditional - replaced equality check with true → NO_COVERAGE 3.3 Location : platformIds Killed by : none removed conditional - replaced equality check with false → NO_COVERAGE
94		1.1 Location : platformIds Killed by : none removed call to java/util/List::of → NO_COVERAGE
98		1.1 Location : platformIds Killed by : none replaced call to org/jocl/CL::clGetPlatformIDs with argument → NO_COVERAGE 2.2 Location : platformIds Killed by : none removed call to org/jocl/CL::clGetPlatformIDs → NO_COVERAGE
100		1.1 Location : platformIds Killed by : none removed call to java/util/Arrays::asList → NO_COVERAGE 2.2 Location : platformIds Killed by : none replaced return value with Collections.emptyList for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::platformIds → NO_COVERAGE
117		1.1 Location : getStringParameter Killed by : none Substituted 1 with 0 → NO_COVERAGE
118		1.1 Location : getStringParameter Killed by : none removed call to org/jocl/CL::clGetPlatformInfo → NO_COVERAGE 2.2 Location : getStringParameter Killed by : none Substituted 0 with 1 → NO_COVERAGE 3.3 Location : getStringParameter Killed by : none replaced call to org/jocl/CL::clGetPlatformInfo with argument → NO_COVERAGE
120		1.1 Location : getStringParameter Killed by : none Substituted 0 with 1 → NO_COVERAGE
121		1.1 Location : getStringParameter Killed by : none replaced call to org/jocl/CL::clGetPlatformInfo with argument → NO_COVERAGE 2.2 Location : getStringParameter Killed by : none removed call to org/jocl/CL::clGetPlatformInfo → NO_COVERAGE 3.3 Location : getStringParameter Killed by : none removed call to org/jocl/Pointer::to → NO_COVERAGE
123		1.1 Location : getStringParameter Killed by : none removed call to java/lang/String::<init> → NO_COVERAGE 2.2 Location : getStringParameter Killed by : none Substituted 1 with 0 → NO_COVERAGE 3.3 Location : getStringParameter Killed by : none replaced return value with "" for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::getStringParameter → NO_COVERAGE 4.4 Location : getStringParameter Killed by : none Replaced integer subtraction with addition → NO_COVERAGE 5.5 Location : getStringParameter Killed by : none Substituted 0 with 1 → NO_COVERAGE
137		1.1 Location : numDevices Killed by : none Substituted 1 with 0 → NO_COVERAGE
138		1.1 Location : numDevices Killed by : none Substituted 0 with 1 → NO_COVERAGE 2.2 Location : numDevices Killed by : none replaced call to org/jocl/CL::clGetDeviceIDs with argument → NO_COVERAGE 3.3 Location : numDevices Killed by : none removed call to org/jocl/CL::clGetDeviceIDs → NO_COVERAGE
140		1.1 Location : numDevices Killed by : none Substituted 0 with 1 → NO_COVERAGE 2.2 Location : numDevices Killed by : none replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE
156		1.1 Location : numDevices Killed by : none Substituted -1 with 0 → NO_COVERAGE 2.2 Location : numDevices Killed by : none replaced int return with 0 for net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE 3.3 Location : numDevices Killed by : none removed call to net/bmahe/genetics4j/gpu/opencl/PlatformUtils::numDevices → NO_COVERAGE

PlatformUtils.java

Mutations

Active mutators

Tests examined