Interface IComputeEngine

Namespace

DotCompute.Abstractions.Interfaces.Compute

Assembly

DotCompute.Abstractions.dll

Provides a unified interface for kernel compilation and execution across different compute backends. This interface serves as the main entry point for all compute operations in the DotCompute framework.

public interface IComputeEngine : IAsyncDisposable

Inherited Members

IAsyncDisposable.DisposeAsync()

Remarks

The IComputeEngine interface abstracts the complexity of different compute backends (CPU, GPU, etc.) and provides a consistent API for kernel compilation and execution. It supports asynchronous operations for better performance and scalability.

Properties

AvailableBackends

Gets the list of compute backends available on the current system.

IReadOnlyList<ComputeBackendType> AvailableBackends { get; }

Property Value

IReadOnlyList<ComputeBackendType>

An array of ComputeBackendType values representing the backends that are currently available and can be used for kernel execution. This list is determined at runtime based on the system capabilities and installed drivers.

Remarks

The availability of backends depends on system configuration, installed drivers, and hardware capabilities. For example, CUDA backend requires NVIDIA drivers, while Metal backend is only available on Apple platforms.

DefaultBackend

Gets the default backend for the current system.

ComputeBackendType DefaultBackend { get; }

Property Value

ComputeBackendType

The ComputeBackendType that represents the most optimal backend for the current system configuration. This is typically determined by performance characteristics and availability of compute resources.

Remarks

The default backend is selected based on system capabilities and performance characteristics. The selection algorithm prioritizes GPU backends when available and falls back to optimized CPU execution when dedicated compute hardware is not present.

Methods

CompileKernelAsync(string, string?, CompilationOptions?, CancellationToken)

Compiles a kernel from source code asynchronously.

ValueTask<ICompiledKernel> CompileKernelAsync(string kernelSource, string? entryPoint = null, CompilationOptions? options = null, CancellationToken cancellationToken = default)

Parameters

kernelSource string

The kernel source code to compile. Must be valid according to the target backend's specification.

entryPoint string

Optional entry point function name. If null, uses default entry point detection.

options CompilationOptions

Optional compilation options that control optimization level, debugging, and other compilation behaviors.

cancellationToken CancellationToken

Token to observe for cancellation requests during compilation.

Returns

ValueTask<ICompiledKernel>

A ValueTask containing the compiled kernel that can be executed on compute backends.

Exceptions

ArgumentNullException

Thrown when kernelSource is null or empty.

CompilationException

Thrown when the kernel source contains compilation errors.

OperationCanceledException

Thrown when the operation is cancelled via the cancellation token.

ExecuteAsync(ICompiledKernel, object[], ComputeBackendType, ExecutionOptions?, CancellationToken)

Executes a compiled kernel on the specified backend asynchronously.

ValueTask ExecuteAsync(ICompiledKernel kernel, object[] arguments, ComputeBackendType backendType, ExecutionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

kernel ICompiledKernel

The compiled kernel to execute. Must be a valid compiled kernel from CompileKernelAsync.

arguments object[]

Array of arguments to pass to the kernel. Types must match kernel parameter expectations.

backendType ComputeBackendType

The compute backend to use for execution (CPU, CUDA, OpenCL, etc.).

options ExecutionOptions

Optional execution options that control work group sizes, profiling, and execution priority.

cancellationToken CancellationToken

Token to observe for cancellation requests during execution.

Returns

ValueTask

A ValueTask representing the asynchronous execution operation.

Exceptions

ArgumentNullException

Thrown when kernel or arguments are null.

ArgumentException

Thrown when arguments don't match kernel parameter requirements.

InvalidOperationException

Thrown when the specified backend is not available.

OperationCanceledException

Thrown when the operation is cancelled via the cancellation token.