Class BaseAccelerator

Namespace

DotCompute.Core

Assembly

DotCompute.Core.dll

Base abstract class for accelerator implementations, consolidating common patterns. This addresses the critical issue of 240+ lines of duplicate code across accelerator implementations.

public abstract class BaseAccelerator : IAccelerator, IAsyncDisposable

Inheritance

object

BaseAccelerator

Implements

IAccelerator

IAsyncDisposable

Derived

CpuAccelerator

CudaAccelerator

MetalAccelerator

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

AcceleratorExtensions.AcceleratorType(IAccelerator)

AcceleratorExtensions.CreateGraph(IAccelerator)

AcceleratorExtensions.GetMemoryStatistics(IAccelerator)

IAcceleratorExtensions.CreateStream(IAccelerator)

IAcceleratorExtensions.Description(IAccelerator)

IAcceleratorExtensions.GetMemoryInfoAsync(IAccelerator)

IAcceleratorExtensions.GetPerformanceMetrics(IAccelerator)

IAcceleratorExtensions.IsAvailable(IAccelerator)

IAcceleratorExtensions.IsDisposed(IAccelerator)

IAcceleratorExtensions.Name(IAccelerator)

IAcceleratorExtensions.SupportsFeature(IAccelerator, string)

Constructors

BaseAccelerator(AcceleratorInfo, AcceleratorType, IUnifiedMemoryManager, AcceleratorContext, ILogger)

Initializes a new instance of the BaseAccelerator class.

protected BaseAccelerator(AcceleratorInfo info, AcceleratorType type, IUnifiedMemoryManager memory, AcceleratorContext context, ILogger logger)

Parameters

info AcceleratorInfo

type AcceleratorType

memory IUnifiedMemoryManager

context AcceleratorContext

logger ILogger

Properties

Context

Gets the accelerator context.

public AcceleratorContext Context { get; }

Property Value

AcceleratorContext

DeviceType

Gets the device type as a string (e.g., "CPU", "GPU", "TPU").

public string DeviceType { get; }

Property Value

string

Info

Gets device information.

public AcceleratorInfo Info { get; }

Property Value

AcceleratorInfo

IsAvailable

Gets whether the accelerator is available for use.

public virtual bool IsAvailable { get; }

Property Value

bool

IsDisposed

Gets whether this accelerator has been disposed.

public bool IsDisposed { get; }

Property Value

bool

Logger

Gets the logger instance for this accelerator.

protected ILogger Logger { get; }

Property Value

ILogger

Memory

Gets memory manager for this accelerator.

public IUnifiedMemoryManager Memory { get; }

Property Value

IUnifiedMemoryManager

MemoryManager

Gets the memory manager for this accelerator (alias for Memory).

public IUnifiedMemoryManager MemoryManager { get; }

Property Value

IUnifiedMemoryManager

Type

Gets the accelerator type.

public AcceleratorType Type { get; }

Property Value

AcceleratorType

Methods

CompileKernelAsync(KernelDefinition, CompilationOptions?, CancellationToken)

Compiles a kernel for execution.

public virtual ValueTask<ICompiledKernel> CompileKernelAsync(KernelDefinition definition, CompilationOptions? options = null, CancellationToken cancellationToken = default)

Parameters

definition KernelDefinition

options CompilationOptions

cancellationToken CancellationToken

Returns

ValueTask<ICompiledKernel>

CompileKernelCoreAsync(KernelDefinition, CompilationOptions, CancellationToken)

Core kernel compilation logic to be implemented by derived classes.

protected abstract ValueTask<ICompiledKernel> CompileKernelCoreAsync(KernelDefinition definition, CompilationOptions options, CancellationToken cancellationToken)

Parameters

definition KernelDefinition

options CompilationOptions

cancellationToken CancellationToken

Returns

ValueTask<ICompiledKernel>

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

DisposeCoreAsync()

Core disposal logic to be implemented by derived classes.

protected virtual ValueTask DisposeCoreAsync()

Returns

ValueTask

GetEffectiveOptions(CompilationOptions?)

Creates compilation options with defaults if not provided.

protected virtual CompilationOptions GetEffectiveOptions(CompilationOptions? options)

Parameters

options CompilationOptions

Returns

CompilationOptions

GetHealthSnapshotAsync(CancellationToken)

Gets a comprehensive health snapshot of the device including sensor readings, health status, and performance metrics.

public virtual ValueTask<DeviceHealthSnapshot> GetHealthSnapshotAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<DeviceHealthSnapshot>

A task containing the device health snapshot.

Remarks

This method queries the device for real-time health information including: - Temperature, power consumption, and utilization - Memory usage and availability - Error counts and device status - Throttling information

Performance: Typically takes 1-10ms to collect all metrics. For high-frequency monitoring, consider caching snapshots for 100-500ms.

Orleans Integration: Use for grain placement decisions and health monitoring.

GetProfilingMetricsAsync(CancellationToken)

Gets current profiling metrics from the device.

public virtual ValueTask<IReadOnlyList<ProfilingMetric>> GetProfilingMetricsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<ProfilingMetric>>

A task containing the collection of profiling metrics.

Remarks

This is a lighter-weight alternative to GetProfilingSnapshotAsync(CancellationToken) when you only need raw metrics without statistics or recommendations.

GetProfilingSnapshotAsync(CancellationToken)

Gets a comprehensive profiling snapshot of accelerator performance.

public virtual ValueTask<ProfilingSnapshot> GetProfilingSnapshotAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ProfilingSnapshot>

A task containing the profiling snapshot.

Remarks

This method provides detailed performance metrics including: - Kernel execution statistics (average, min, max, percentiles) - Memory operation statistics (bandwidth, transfer times) - Device utilization metrics - Performance trends and bottlenecks - Optimization recommendations

Performance: Typically takes 1-5ms to collect all metrics. Profiling overhead is minimal (<1%) when not actively querying.

Use Cases: Performance optimization, backend selection, monitoring dashboards.

GetSensorReadingsAsync(CancellationToken)

Gets current sensor readings from the device.

public virtual ValueTask<IReadOnlyList<SensorReading>> GetSensorReadingsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<SensorReading>>

A task containing the collection of available sensor readings.

Remarks

This is a lighter-weight alternative to GetHealthSnapshotAsync(CancellationToken) when you only need raw sensor data without health scoring or status analysis.

InitializeCore()

Core initialization logic to be implemented by derived classes.

protected virtual object? InitializeCore()

Returns

object

Initialization result (typically null or status object)

LogCompilationMetrics(string, TimeSpan, long?)

Logs performance metrics for kernel compilation.

protected void LogCompilationMetrics(string kernelName, TimeSpan compilationTime, long? byteCodeSize = null)

Parameters

kernelName string

compilationTime TimeSpan

byteCodeSize long?

ResetAsync(ResetOptions?, CancellationToken)

Resets the accelerator device to a clean state.

public virtual ValueTask<ResetResult> ResetAsync(ResetOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options ResetOptions

Reset configuration options. If null, uses Default.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ResetResult>

A task containing detailed information about the reset operation.

Remarks

Device reset clears device state and optionally reinitializes resources. The extent of reset depends on ResetType:

• Soft: Flush queues, clear pending operations (1-10ms)
• Context: Reset context, clear caches (10-50ms)
• Hard: Full reset, clear all memory (50-200ms)
• Full: Complete reinitialization (200-1000ms)

Important: Hard and Full invalidate all existing UnifiedBuffer instances. The application must recreate buffers after reset completes.

Orleans Integration: Use during grain deactivation, error recovery, or when transferring device ownership between grains. Consider GrainDeactivation for typical grain lifecycle scenarios.

Error Recovery: When recovering from device errors or hangs, use ErrorRecovery which forces a hard reset and clears all state.

Thread Safety: Reset operations are thread-safe. Concurrent operations will wait for completion or be cancelled depending on WaitForCompletion.

Exceptions

TimeoutException

Thrown if reset exceeds Timeout.

InvalidOperationException

Thrown if reset cannot be performed (e.g., device lost).

ObjectDisposedException

Thrown if the accelerator has been disposed.

SynchronizeAsync(CancellationToken)

Synchronizes all pending operations.

public virtual ValueTask SynchronizeAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

SynchronizeCoreAsync(CancellationToken)

Core synchronization logic to be implemented by derived classes.

protected abstract ValueTask SynchronizeCoreAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

ThrowIfDisposed()

Throws if the accelerator has been disposed.

protected void ThrowIfDisposed()

ValidateKernelDefinition(KernelDefinition)

Validates kernel definition parameters. Common validation logic that was duplicated across implementations.

protected virtual void ValidateKernelDefinition(KernelDefinition definition)

Parameters

definition KernelDefinition