Package net.bmahe.genetics4j.gpu.spec

Class Program

java.lang.Object
net.bmahe.genetics4j.gpu.spec.Program
Direct Known Subclasses:
ImmutableProgram
@Immutable public abstract class Program extends Object
Specification for OpenCL programs containing kernel source code, build options, and compilation settings.

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:

  1. Source loading: Load content from strings and resource files
  2. Source concatenation: Combine all sources into a single compilation unit
  3. Compilation: Compile with specified build options for target devices
  4. Kernel extraction: Create kernel objects for specified kernel names
  5. 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 Details

    • Program

      public Program()

  • Method Details

    • content

      @Parameter public abstract List<String> 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

      @Parameter public abstract Set<String> 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

      @Parameter public abstract Set<String> 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

      public abstract Optional<String> 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

      public static Program ofContent(String content, String kernelName)
      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 string
      kernelName - 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

      public static Program ofResource(String resource, String kernelName)
      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 file
      kernelName - 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

      public static Program ofResource(String resource, String kernelName, String buildOptions)
      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 file
      kernelName - the name of the kernel function to extract
      buildOptions - 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

      public static ImmutableProgram.Builder 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