Table of Contents

Interface IKernelCompiler

Namespace
Orleans.GpuBridge.Abstractions.Providers
Assembly
Orleans.GpuBridge.Abstractions.dll

Defines the contract for GPU kernel compilation services.

public interface IKernelCompiler

Examples

// Compile a C# method to a GPU kernel
var compiler = serviceProvider.GetRequiredService<IKernelCompiler>();
var options = new KernelCompilationOptions(OptimizationLevel.O2);
var kernel = await compiler.CompileFromMethodAsync(methodInfo, options);

// Compile from CUDA source code
var cudaKernel = await compiler.CompileFromSourceAsync(
    cudaCode, "vectorAdd", KernelLanguage.CUDA, options);

// Validate before compilation
var validation = await compiler.ValidateMethodAsync(methodInfo);
if (validation.IsValid)
{
    var kernel = await compiler.CompileFromMethodAsync(methodInfo, options);
}

Remarks

This interface abstracts the kernel compilation process across different GPU backends, providing a unified API for compiling C# methods, source code, or assembly IL into GPU-executable kernels. Implementations handle backend-specific compilation details while maintaining consistent behavior across different GPU architectures and vendors.

The compiler interface supports multiple compilation paths: - Direct C# method compilation with reflection - Source code compilation from various GPU languages - Assembly IL compilation for advanced scenarios

All compilation operations are asynchronous and support cancellation to handle potentially long-running compilation processes, especially when aggressive optimizations are enabled.

Methods

ClearCache()

Clears the internal compilation cache to free memory and force recompilation.

void ClearCache()

Remarks

The compiler may cache compiled kernels to improve performance of repeated compilations. This method clears all cached data, which may be useful for:

  • Freeing memory in long-running applications
  • Forcing recompilation with updated options
  • Debugging compilation-related issues

After calling this method, subsequent compilation requests will not benefit from cached results until the cache is repopulated.

CompileFromAssemblyAsync(Assembly, string, string, KernelCompilationOptions, CancellationToken)

Compiles a GPU kernel from .NET assembly intermediate language (IL).

[RequiresUnreferencedCode("Uses reflection to find types and methods which may be trimmed.")]
Task<CompiledKernel> CompileFromAssemblyAsync(Assembly assembly, string typeName, string methodName, KernelCompilationOptions options, CancellationToken cancellationToken = default)

Parameters

assembly Assembly

The assembly containing the method to compile.

typeName string

The full name of the type containing the kernel method.

methodName string

The name of the method to compile as a kernel.

options KernelCompilationOptions

Compilation options that control optimization level, debug information, and other compilation behaviors.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the compilation operation.

Returns

Task<CompiledKernel>

A task that represents the asynchronous compilation operation. The task result contains the compiled kernel if successful.

Remarks

This method enables compilation of kernels from pre-compiled assemblies, which is useful for dynamic kernel loading scenarios or when working with assemblies loaded at runtime. The method will be located using reflection and compiled to GPU code.

Exceptions

ArgumentNullException

Thrown when assembly, typeName, methodName, or options is null.

ArgumentException

Thrown when typeName or methodName is empty.

InvalidOperationException

Thrown when the specified type or method cannot be found in the assembly, or the method cannot be compiled as a GPU kernel.

OperationCanceledException

Thrown when the compilation is cancelled via cancellationToken.

CompileFromMethodAsync(MethodInfo, KernelCompilationOptions, CancellationToken)

Compiles a GPU kernel from a C# method using reflection.

[RequiresUnreferencedCode("Uses method validation which may not work with trimming.")]
Task<CompiledKernel> CompileFromMethodAsync(MethodInfo method, KernelCompilationOptions options, CancellationToken cancellationToken = default)

Parameters

method MethodInfo

The MethodInfo representing the C# method to compile. The method should be static and follow GPU kernel conventions.

options KernelCompilationOptions

Compilation options that control optimization level, debug information, and other compilation behaviors.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the compilation operation.

Returns

Task<CompiledKernel>

A task that represents the asynchronous compilation operation. The task result contains the compiled kernel if successful.

Remarks

This method analyzes the provided C# method and generates equivalent GPU code. Not all C# constructs are supported in GPU kernels - use ValidateMethodAsync(MethodInfo, CancellationToken) to check compatibility before compilation.

Exceptions

ArgumentNullException

Thrown when method or options is null.

InvalidOperationException

Thrown when the method cannot be compiled as a GPU kernel due to unsupported constructs or incompatible signature.

OperationCanceledException

Thrown when the compilation is cancelled via cancellationToken.

CompileFromSourceAsync(string, string, KernelLanguage, KernelCompilationOptions, CancellationToken)

Compiles a GPU kernel from source code in a specified language.

Task<CompiledKernel> CompileFromSourceAsync(string sourceCode, string entryPoint, KernelLanguage language, KernelCompilationOptions options, CancellationToken cancellationToken = default)

Parameters

sourceCode string

The source code of the kernel in the specified language.

entryPoint string

The name of the entry point function within the source code.

language KernelLanguage

The programming language of the source code.

options KernelCompilationOptions

Compilation options that control optimization level, debug information, and other compilation behaviors.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the compilation operation.

Returns

Task<CompiledKernel>

A task that represents the asynchronous compilation operation. The task result contains the compiled kernel if successful.

Remarks

This method provides flexibility to compile kernels written in native GPU languages like CUDA C, OpenCL C, or other supported languages. The availability of specific languages depends on the backend implementation.

Exceptions

ArgumentNullException

Thrown when sourceCode, entryPoint, or options is null.

ArgumentException

Thrown when sourceCode or entryPoint is empty.

NotSupportedException

Thrown when the specified language is not supported by the current backend.

InvalidOperationException

Thrown when the source code contains compilation errors or the entry point cannot be found.

OperationCanceledException

Thrown when the compilation is cancelled via cancellationToken.

GetDiagnosticsAsync(CompiledKernel, CancellationToken)

Retrieves detailed compilation diagnostics for a compiled kernel.

Task<CompilationDiagnostics> GetDiagnosticsAsync(CompiledKernel kernel, CancellationToken cancellationToken = default)

Parameters

kernel CompiledKernel

The compiled kernel for which to retrieve diagnostics.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the diagnostic operation.

Returns

Task<CompilationDiagnostics>

A task that represents the asynchronous diagnostic operation. The task result contains detailed compilation diagnostics.

Remarks

Diagnostics provide detailed information about the compilation process, including intermediate representations, optimization reports, and performance characteristics. This information is valuable for debugging and optimization.

The availability of specific diagnostic information depends on the backend and compilation options used when the kernel was originally compiled.

Exceptions

ArgumentNullException

Thrown when kernel is null.

ObjectDisposedException

Thrown when kernel has been disposed.

OperationCanceledException

Thrown when the operation is cancelled via cancellationToken.

ValidateMethodAsync(MethodInfo, CancellationToken)

Validates whether a C# method can be successfully compiled as a GPU kernel.

[RequiresUnreferencedCode("Uses method body analysis which may not work with trimming.")]
Task<KernelValidationResult> ValidateMethodAsync(MethodInfo method, CancellationToken cancellationToken = default)

Parameters

method MethodInfo

The MethodInfo representing the C# method to validate.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the validation operation.

Returns

Task<KernelValidationResult>

A task that represents the asynchronous validation operation. The task result contains validation results including any errors or warnings.

Remarks

This method performs static analysis of the C# method to determine if it can be successfully compiled to GPU code. It checks for unsupported language constructs, invalid memory access patterns, and other compatibility issues.

Use this method before attempting compilation to provide better error messages and avoid unnecessary compilation attempts for incompatible methods.

Exceptions

ArgumentNullException

Thrown when method is null.

OperationCanceledException

Thrown when the validation is cancelled via cancellationToken.

Edit this page