Class Program
- Direct Known Subclasses:
ImmutableProgram
Program represents a complete OpenCL program specification that includes kernel source code (either as direct content or resource references), kernel definitions, and compilation options. This specification is used by the GPU EA system to compile and execute OpenCL kernels for fitness evaluation on GPU devices.
A program can contain:
- Source content: Direct OpenCL C code as strings
- Resource references: Paths to OpenCL source files in the classpath
- Kernel definitions: Names of kernels to be compiled and made available
- Build options: Compiler flags and preprocessor definitions
Program compilation workflow:
- Source loading: Load content from strings and resource files
- Source concatenation: Combine all sources into a single compilation unit
- Compilation: Compile with specified build options for target devices
- Kernel extraction: Create kernel objects for specified kernel names
- Validation: Verify all kernels were successfully created
Common usage patterns:
// Simple single-kernel program from resource
Program basicProgram = Program.ofResource("/kernels/fitness.cl", "evaluate_fitness");
// Program with build options for optimization
Program optimizedProgram = Program.ofResource(
"/kernels/optimization.cl",
"fitness_kernel",
"-O3 -DPOPULATION_SIZE=1000 -DUSE_FAST_MATH"
);
// Complex program with multiple sources and kernels
Program complexProgram = Program.builder()
.addContent("#define PROBLEM_SIZE 256") // Direct content
.addResources("/kernels/common.cl") // Common utilities
.addResources("/kernels/fitness.cl") // Main fitness logic
.addKernelNames("fitness_eval") // Primary kernel
.addKernelNames("data_preparation") // Helper kernel
.buildOptions("-cl-fast-relaxed-math -DLOCAL_SIZE=64")
.build();
Build options support:
- Optimization flags: -O0, -O1, -O2, -O3 for performance tuning
- Math optimizations: -cl-fast-relaxed-math for numerical performance
- Preprocessor definitions: -DMACRO=value for compile-time configuration
- Warning control: -w to disable warnings, -Werror to treat warnings as errors
- Standards compliance: -cl-std=CL1.2 for specific OpenCL version targeting
Resource loading considerations:
- Classpath resolution: Resources loaded relative to classpath
- Encoding: Source files assumed to be UTF-8 encoded
- Include simulation: Manual concatenation instead of OpenCL #include
- Error handling: Resource loading failures result in compilation errors
Validation and constraints:
- Kernel names required: At least one kernel name must be specified
- Source availability: Either content or resources must provide source code
- Name uniqueness: Kernel names must be unique within the program
- Compilation validity: Source code must compile successfully for target devices
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic ImmutableProgram.Builder
builder()
Creates a new builder for constructing complex program specifications.Returns the OpenCL compiler build options for program compilation.protected void
check()
content()
Returns the direct OpenCL source code content as strings.Returns the names of kernels to be extracted from the compiled program.static Program
Creates a program from direct OpenCL source content with a single kernel.static Program
ofResource
(String resource, String kernelName) Creates a program from a classpath resource with a single kernel.static Program
ofResource
(String resource, String kernelName, String buildOptions) Creates a program from a classpath resource with a single kernel and build options.Returns the classpath resource paths containing OpenCL source code.
-
Constructor Details
-
Program
public Program()
-
-
Method Details
-
content
Returns the direct OpenCL source code content as strings.Content represents OpenCL C source code provided directly as strings rather than loaded from resources. Multiple content strings are concatenated during compilation to form a single compilation unit.
- Returns:
- list of OpenCL source code strings
-
resources
Returns the classpath resource paths containing OpenCL source code.Resources are loaded from the classpath at compilation time and concatenated with any direct content to form the complete program source. Resource paths should be relative to the classpath root.
- Returns:
- set of classpath resource paths for OpenCL source files
-
kernelNames
Returns the names of kernels to be extracted from the compiled program.Kernel names specify which functions in the OpenCL source should be made available as executable kernels. These names must correspond to functions declared with the
__kernel
qualifier in the source code.- Returns:
- set of kernel function names to extract after compilation
-
buildOptions
Returns the OpenCL compiler build options for program compilation.Build options are passed to the OpenCL compiler to control optimization, define preprocessor macros, and configure compilation behavior. Common options include optimization levels, math optimizations, and macro definitions.
- Returns:
- optional build options string for OpenCL compilation
-
check
@Check protected void check() -
ofContent
Creates a program from direct OpenCL source content with a single kernel.This factory method creates a simple program specification with source code provided directly as a string and a single kernel to be extracted.
- Parameters:
content
- the OpenCL source code as a stringkernelName
- the name of the kernel function to extract- Returns:
- a new program specification with the given content and kernel
- Throws:
IllegalArgumentException
- if content or kernelName is null or blank
-
ofResource
Creates a program from a classpath resource with a single kernel.This factory method creates a program specification that loads OpenCL source code from a classpath resource and extracts a single named kernel.
- Parameters:
resource
- the classpath path to the OpenCL source filekernelName
- the name of the kernel function to extract- Returns:
- a new program specification with the given resource and kernel
- Throws:
IllegalArgumentException
- if resource or kernelName is null or blank
-
ofResource
Creates a program from a classpath resource with a single kernel and build options.This factory method creates a program specification that loads OpenCL source code from a classpath resource, extracts a single named kernel, and applies the specified build options during compilation.
- Parameters:
resource
- the classpath path to the OpenCL source filekernelName
- the name of the kernel function to extractbuildOptions
- the build options for OpenCL compilation- Returns:
- a new program specification with the given resource, kernel, and build options
- Throws:
IllegalArgumentException
- if resource or kernelName is null or blank
-
builder
Creates a new builder for constructing complex program specifications.The builder provides a fluent interface for creating programs with multiple source files, kernels, and advanced configuration options.
- Returns:
- a new builder instance for creating program specifications
-