Table of Contents

Class DotGpuBackendConfiguration

Namespace
Orleans.GpuBridge.Backends.DotCompute.Configuration
Assembly
Orleans.GpuBridge.Backends.DotCompute.dll

Configuration options for the DotCompute backend provider.

public class DotGpuBackendConfiguration
Inheritance
DotGpuBackendConfiguration
Inherited Members

Examples

// Basic configuration for production use
services.AddGpuBridge(options => options.PreferGpu = true)
        .AddDotGpuBackend(config =>
        {
            config.EnableOptimizations = true;
            config.OptimizationLevel = OptimizationLevel.O2;
            config.PreferredPlatforms.Clear();
            config.PreferredPlatforms.Add(GpuBackend.CUDA);
            config.PreferredPlatforms.Add(GpuBackend.OpenCL);
        });

// Debug configuration for development
services.AddGpuBridge(options => options.PreferGpu = true)
        .AddDotGpuBackend(config =>
        {
            config.EnableDebugMode = true;
            config.EnableOptimizations = false;
            config.OptimizationLevel = OptimizationLevel.O0;
            config.EnableDiskCache = false;
        });

// High-performance configuration for compute-intensive workloads
services.AddGpuBridge(options => options.PreferGpu = true)
        .AddDotGpuBackend(config =>
        {
            config.OptimizationLevel = OptimizationLevel.O3;
            config.MaxConcurrentCompilations = Environment.ProcessorCount * 2;
            config.MemorySettings.InitialPoolSize = 1024 * 1024 * 1024; // 1 GB
            config.MemorySettings.MaxPoolSize = 8L * 1024 * 1024 * 1024; // 8 GB
        });

Remarks

This class provides comprehensive configuration options for the DotCompute GPU backend, allowing fine-tuned control over compilation, execution, memory management, and platform preferences. The configuration supports multiple GPU vendors and compute platforms.

The DotCompute backend serves as a unified abstraction over multiple GPU compute APIs including CUDA, OpenCL, DirectCompute, Metal, and Vulkan. Configuration settings allow you to optimize for specific hardware configurations and use cases.

Default settings are optimized for production use with balanced performance and resource usage. Adjust specific settings based on your deployment environment and performance requirements.

Properties

CacheDirectory

Gets or sets the directory path for caching compiled kernels.

public string? CacheDirectory { get; set; }

Property Value

string

The directory path for kernel cache, or null to use the default system cache directory.

Examples

// Use custom cache directory
config.CacheDirectory = "/opt/app/gpu-cache";

// Use default system directory
config.CacheDirectory = null;

Remarks

Specifies the filesystem location where compiled kernel binaries are stored for caching. If null or empty, the backend will use a system-appropriate default cache directory.

Default cache locations by platform: - Windows: %LOCALAPPDATA%\Orleans.GpuBridge\DotCompute\Cache - Linux: ~/.cache/orleans-gpubridge/dotcompute - macOS: ~/Library/Caches/Orleans.GpuBridge.DotCompute

Directory requirements: - Must be writable by the application process - Should have sufficient disk space (recommend 1GB minimum) - Can be shared across application instances for efficiency - Should be on a fast storage device (SSD preferred)

This setting is only effective when EnableDiskCache is true.

DeviceFilter

Gets or sets the device selection filter function for choosing specific GPU devices.

public Func<object, bool>? DeviceFilter { get; set; }

Property Value

Func<object, bool>

A function that takes a device object and returns true if the device should be used, or null to use all available devices.

Examples

// Filter for high-memory devices only
config.DeviceFilter = device =>
{
    return device switch
    {
        CudaDevice cuda => cuda.TotalMemory > 8L * 1024 * 1024 * 1024, // 8GB+
        OpenCLDevice opencl => opencl.GlobalMemorySize > 8L * 1024 * 1024 * 1024,
        _ => true // Accept other device types
    };
};

// Filter for discrete GPUs only
config.DeviceFilter = device =>
{
    return device switch
    {
        OpenCLDevice opencl => opencl.DeviceType == DeviceType.GPU,
        _ => true
    };
};

Remarks

This filter allows fine-grained control over which GPU devices are selected for kernel execution. The function receives a platform-specific device object and should return true for devices that meet your criteria.

The device object type depends on the underlying platform: - CUDA: CudaDevice with properties like ComputeCapability, TotalMemory - OpenCL: OpenCLDevice with properties like DeviceType, MaxWorkGroupSize - DirectCompute: DirectComputeDevice with DirectX-specific properties - Metal: MetalDevice with Apple-specific properties - Vulkan: VulkanDevice with Vulkan API properties

Common filtering criteria: - Memory capacity (minimum required GPU memory) - Compute capability (minimum hardware feature support) - Device type (discrete vs. integrated GPUs) - Vendor preference (specific GPU manufacturers) - Performance characteristics (memory bandwidth, compute units)

EnableDebugMode

Gets or sets whether to enable debug mode for DotCompute kernel compilation and execution.

public bool EnableDebugMode { get; set; }

Property Value

bool

true to enable debug mode; otherwise, false. Default is false.

Remarks

Debug mode enables additional runtime checks, detailed error reporting, and debugging symbols in compiled kernels. This significantly impacts performance and should only be used during development.

When enabled, debug mode provides: - Detailed kernel compilation errors and warnings - Runtime bounds checking and validation - Debugging symbols for GPU debuggers - Verbose logging of GPU operations - Slower kernel execution due to additional checks

Recommended settings: - Development: true - Staging: false - Production: false

EnableDiskCache

Gets or sets whether to cache compiled kernels to disk for faster subsequent loads.

public bool EnableDiskCache { get; set; }

Property Value

bool

true to enable disk caching; otherwise, false. Default is true.

Remarks

Disk caching stores compiled kernel binaries to persistent storage, significantly reducing application startup time and kernel compilation overhead on subsequent runs.

Cache benefits: - Faster application startup (avoids recompilation) - Reduced CPU usage for repeated kernel compilations - Consistent performance across application restarts - Shared cache across application instances

Cache considerations: - Disk space usage (compiled kernels can be 1MB-100MB each) - Cache invalidation when kernel source or compiler versions change - File system permissions for cache directory access - Concurrent access from multiple application instances

The cache directory is specified by CacheDirectory or uses a system-appropriate default location if not specified.

EnableOptimizations

Gets or sets whether to enable compiler optimizations for kernel compilation.

public bool EnableOptimizations { get; set; }

Property Value

bool

true to enable optimizations; otherwise, false. Default is true.

Remarks

This setting controls whether the DotCompute compiler applies general optimizations during kernel compilation. Works in conjunction with OptimizationLevel to control the specific level of optimization applied.

When enabled, optimizations can include: - Dead code elimination - Constant folding and propagation - Loop optimizations and unrolling - Instruction scheduling and reordering - Memory access pattern optimization

Disabling optimizations is primarily useful for debugging scenarios where you need predictable code generation and line-by-line correspondence with source code.

LanguageSettings

Gets or sets the kernel language compilation settings.

public KernelLanguageSettings LanguageSettings { get; set; }

Property Value

KernelLanguageSettings

A KernelLanguageSettings instance containing language configuration. Never null.

Remarks

These settings control how the DotCompute backend handles different kernel programming languages and their compilation. The backend supports multiple source languages and can automatically translate between them when needed.

Language settings affect: - Source language preference for each platform - Automatic language translation capabilities - Preprocessor definitions and include paths - Compilation flags and optimization settings

The default settings provide good cross-platform compatibility while optimizing for platform-specific languages when available.

MaxConcurrentCompilations

Gets or sets the maximum number of concurrent kernel compilations allowed.

public int MaxConcurrentCompilations { get; set; }

Property Value

int

The maximum number of concurrent compilations. Default is the processor count. Must be a positive integer.

Remarks

This setting controls the parallelism level for kernel compilation operations. Higher values can reduce overall compilation time when compiling multiple kernels simultaneously, but may increase memory usage and system load.

Considerations for setting this value: - CPU cores: Generally set to processor count or 2x processor count - Memory: Each compilation uses significant memory (100MB-1GB per compilation) - I/O: Concurrent disk operations for cache and temporary files - GPU driver limits: Some drivers have limits on concurrent compilation contexts

Recommended values: - Development machines: 2-4 - CI/Build servers: ProcessorCount - Production servers: ProcessorCount * 2 (if memory permits)

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than or equal to zero.

MemorySettings

Gets or sets the memory management settings for the DotCompute backend.

public DotComputeMemorySettings MemorySettings { get; set; }

Property Value

DotComputeMemorySettings

A DotComputeMemorySettings instance containing memory configuration. Never null.

Remarks

These settings control how the DotCompute backend manages GPU memory allocation, pooling, and optimization. Proper memory configuration is crucial for achieving optimal performance in GPU compute workloads.

Memory management affects: - Allocation performance and fragmentation - Memory usage efficiency and peak consumption - Transfer performance between CPU and GPU - Multi-kernel memory sharing and reuse

The default settings are optimized for typical workloads, but may need adjustment based on your specific memory usage patterns and hardware configuration.

OptimizationLevel

Gets or sets the optimization level for kernel compilation.

public OptimizationLevel OptimizationLevel { get; set; }

Property Value

OptimizationLevel

An OptimizationLevel value specifying the optimization level. Default is O2.

Remarks

The optimization level controls the trade-off between compilation time and runtime performance. Higher levels generally produce faster code but take longer to compile.

Recommended levels by use case: - Development and debugging: O0 or O1 - Production deployments: O2 - Performance-critical applications: O3

This setting is only effective when EnableOptimizations is true.

PlatformSpecificSettings

Gets or sets platform-specific configuration settings.

public Dictionary<GpuBackend, object> PlatformSpecificSettings { get; set; }

Property Value

Dictionary<GpuBackend, object>

A dictionary mapping GpuBackend values to platform-specific configuration objects.

Examples

// CUDA-specific settings
config.PlatformSpecificSettings[GpuBackend.CUDA] = new CudaSettings
{
    EnableP2P = true,
    StreamPriority = CudaStreamPriority.High
};

// OpenCL-specific settings
config.PlatformSpecificSettings[GpuBackend.OpenCL] = new OpenCLSettings
{
    EnableImageSupport = true,
    PreferredWorkGroupSize = 256
};

Remarks

This dictionary allows you to specify platform-specific configuration that cannot be expressed through the common configuration properties. Each platform may have unique settings that are not applicable to other platforms.

Platform-specific settings examples: - CUDA: Stream priorities, memory pool configurations, P2P settings - OpenCL: Context properties, queue properties, extension usage - DirectCompute: Device debug layer settings, feature level requirements - Metal: Command queue configurations, heap settings - Vulkan: Instance extensions, device extensions, queue families

The configuration objects are platform-specific and should match the expected types for each backend. Consult the DotCompute documentation for detailed information about supported platform-specific options.

PreferredPlatforms

Gets or sets the list of preferred GPU compute platforms in priority order.

public List<GpuBackend> PreferredPlatforms { get; set; }

Property Value

List<GpuBackend>

A list of GpuBackend values representing preferred platforms. Default includes all supported platforms in optimal order.

Examples

// NVIDIA-first configuration
config.PreferredPlatforms = new List<GpuBackend>
{
    GpuBackend.CUDA,
    GpuBackend.Vulkan,
    GpuBackend.OpenCL
};

// Cross-platform configuration
config.PreferredPlatforms = new List<GpuBackend>
{
    GpuBackend.OpenCL,
    GpuBackend.Vulkan
};

Remarks

This list defines the platform selection priority when multiple GPU backends are available on the system. The DotCompute backend will attempt to use platforms in the specified order until a compatible one is found.

Platform characteristics: - CUDA: NVIDIA GPUs only, excellent performance - OpenCL: Cross-vendor compatibility, good portability - DirectCompute: Windows DirectX, good Windows integration - Metal: Apple platforms only, optimized for Apple hardware - Vulkan: Modern cross-platform API, excellent performance

Selection considerations: - Hardware availability (vendor-specific platforms) - Performance requirements (vendor-specific vs. cross-platform) - Portability needs (single platform vs. multiple platforms) - Development tools and debugging support

Edit this page