Class MetalComputeGraph

Namespace

DotCompute.Backends.Metal.Execution.Graph

Assembly

DotCompute.Backends.Metal.dll

Represents a Metal computational graph that can be constructed, optimized, and executed efficiently. Provides high-performance execution through kernel fusion and optimization for Apple Silicon architecture.

public sealed class MetalComputeGraph : IDisposable

Inheritance

object

MetalComputeGraph

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BufferExtensions.IsSafeToDispose(IDisposable)

BufferExtensions.SafeDispose(IDisposable)

Remarks

Metal compute graphs enable efficient execution of complex computation pipelines by reducing CPU-GPU synchronization overhead and enabling advanced optimizations like kernel fusion, memory coalescing, and command buffer batching.

Constructors

MetalComputeGraph(string, ILogger<MetalComputeGraph>?)

Initializes a new instance of the MetalComputeGraph class.

public MetalComputeGraph(string name, ILogger<MetalComputeGraph>? logger = null)

Parameters

name string

The human-readable name for this graph.

logger ILogger<MetalComputeGraph>

Optional logger instance for debugging and monitoring.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

Properties

Configuration

Gets the configuration options for this graph.

public MetalGraphConfiguration Configuration { get; }

Property Value

MetalGraphConfiguration

CreatedAt

Gets the timestamp when this graph was created.

public DateTimeOffset CreatedAt { get; }

Property Value

DateTimeOffset

EstimatedMemoryFootprint

Gets the total estimated memory footprint of this graph in bytes.

public long EstimatedMemoryFootprint { get; }

Property Value

long

Id

Gets the unique identifier for this Metal compute graph.

public string Id { get; }

Property Value

string

IsBuilt

Gets a value indicating whether the graph has been built and is ready for execution.

public bool IsBuilt { get; }

Property Value

bool

IsEmpty

Gets a value indicating whether the graph is empty (contains no nodes).

public bool IsEmpty { get; }

Property Value

bool

IsOptimized

Gets a value indicating whether the graph has been optimized for execution.

public bool IsOptimized { get; }

Property Value

bool

Name

Gets the human-readable name for this Metal compute graph.

public string Name { get; }

Property Value

string

NodeCount

Gets the current count of nodes in the graph.

public int NodeCount { get; }

Property Value

int

Nodes

Gets the thread-safe collection of graph nodes that comprise this Metal compute graph.

public IReadOnlyList<MetalGraphNode> Nodes { get; }

Property Value

IReadOnlyList<MetalGraphNode>

Statistics

Gets the current statistics for this graph.

public MetalGraphStatistics Statistics { get; }

Property Value

MetalGraphStatistics

Methods

AddBarrierNode(MetalGraphNode[])

Adds a synchronization barrier node to the graph.

public MetalGraphNode AddBarrierNode(MetalGraphNode[] dependencies)

Parameters

dependencies MetalGraphNode[]

The nodes that must complete before subsequent operations.

Returns

MetalGraphNode

The created barrier node.

AddKernelNode(ICompiledKernel, MTLSize, MTLSize, object[], MetalGraphNode[]?)

Adds a kernel computation node to the graph.

public MetalGraphNode AddKernelNode(ICompiledKernel kernel, MTLSize threadgroupsPerGrid, MTLSize threadsPerThreadgroup, object[] arguments, MetalGraphNode[]? dependencies = null)

Parameters

kernel ICompiledKernel

The compiled Metal kernel to execute.

threadgroupsPerGrid MTLSize

The number of threadgroups to dispatch.

threadsPerThreadgroup MTLSize

The number of threads per threadgroup.

arguments object[]

The kernel arguments.

dependencies MetalGraphNode[]

Optional array of nodes this kernel depends on.

Returns

MetalGraphNode

The created kernel node.

Exceptions

ArgumentNullException

Thrown when kernel is null.

ObjectDisposedException

Thrown when the graph has been disposed.

AddMemoryCopyNode(nint, nint, long, MetalGraphNode[]?)

Adds a memory copy node to the graph.

public MetalGraphNode AddMemoryCopyNode(nint sourceBuffer, nint destinationBuffer, long size, MetalGraphNode[]? dependencies = null)

Parameters

sourceBuffer nint

The source Metal buffer.

destinationBuffer nint

The destination Metal buffer.

size long

The number of bytes to copy.

dependencies MetalGraphNode[]

Optional array of nodes this copy depends on.

Returns

MetalGraphNode

The created memory copy node.

AddMemorySetNode(nint, byte, long, MetalGraphNode[]?)

Adds a memory set node to the graph.

public MetalGraphNode AddMemorySetNode(nint buffer, byte value, long size, MetalGraphNode[]? dependencies = null)

Parameters

buffer nint

The Metal buffer to fill.

value byte

The value to fill with.

size long

The number of bytes to fill.

dependencies MetalGraphNode[]

Optional array of nodes this operation depends on.

Returns

MetalGraphNode

The created memory set node.

AnalyzeOptimizationOpportunities()

Analyzes the graph for optimization opportunities.

public MetalGraphAnalysis AnalyzeOptimizationOpportunities()

Returns

MetalGraphAnalysis

Analysis results containing optimization information.

Build()

Builds the graph by analyzing dependencies and preparing for execution.

public void Build()

Exceptions

InvalidOperationException

Thrown when circular dependencies are detected.

Clear()

Clears all nodes from the graph.

public void Clear()

Dispose()

Releases all resources used by the Metal compute graph.

public void Dispose()

~MetalComputeGraph()

Finalizer for the MetalComputeGraph class.

protected ~MetalComputeGraph()

FindNode(string)

Finds a node in the graph by its ID.

public MetalGraphNode? FindNode(string nodeId)

Parameters

nodeId string

The ID of the node to find.

Returns

MetalGraphNode

The node with the specified ID, or null if not found.

GetExecutionOrder()

Gets the execution order of nodes using topological sorting.

public IReadOnlyList<MetalGraphNode> GetExecutionOrder()

Returns

IReadOnlyList<MetalGraphNode>

A list of nodes in execution order.

Exceptions

InvalidOperationException

Thrown when the graph hasn't been built.

RemoveNode(string)

Removes a node from the graph by its ID.

public bool RemoveNode(string nodeId)

Parameters

nodeId string

The ID of the node to remove.

Returns

bool

true if the node was found and removed; otherwise, false.

Exceptions

ArgumentException

Thrown when nodeId is null or whitespace.

ObjectDisposedException

Thrown when the graph has been disposed.